Introduction

  • 🎨 Optimized for every theme.
  • 🔥 Zero-Setup installation: Use the installer or download the standalone files from the repository.
  • 🔧 Highly configurable.

Installation

In the directory of your book, install whichlang with the following command.

curl -sSf -o install-whichlang.sh https://raw.githubusercontent.com/phoenixr-codes/mdbook-whichlang/master/install.sh &&
bash install-whichlang.sh

Alternatively, you can download dist/whichlang.js and src/whichlang.css and save them in the appropiate directories within your book.

Don't forget to add these files in your book.toml:

# ...

[output.html]
additional-css = ["path/to/whichlang.css"]
additional-js = ["path/to/whichlang.js"]

Uninstallation

Simply remove the whichlang.js and whichlang.css files and remove the references to them in the book.toml configuration file.

Usage

whichlang works out of the box. It detects the language defined on each code block and customizes them appropiately. You can furthermore configure them individually which is recommended:

  • override the name of the language
  • override the icon of the language
  • set a file path shown in the code block

Cheat Sheet

Remember that you can combine all features shown below.

Override the language name

```python,lang=mojo
def greet():
    print("Hello World")
```

becomes

def greet():
    print("Hello World")

It's always a good idea to manually specify the language with the lang key because highlightjs might assign the entire family of the language. For example if you use toml as the language, whichlang might use INI as the language.

Disable language detection

Because whichlang always infers the language by the code block's class name which may even be set when you didn't specify a language, you can disable language detection by using nolang:

```toml,nolang
[player]
name = "John"
```

becomes

[player]
name = "John"

Override the language icon

```python,icon=.devicon-python-plain
def greet():
    print("Hello World")
```

becomes

def greet():
    print("Hello World")

You can read more in this chapter.

Classes

You can set multiple classes to create an icon out of it. This mechanic is used by many tools such as FontAwesome. Each class must be prefixed by a period and must not be separated by spaces.

URL or Path

icon=@url/to/icon.svg

Set the file path

```python,filepath=path/to/file.py
def greet():
    print("Hello World")
```

becomes

def greet():
    print("Hello World")

Using Icons

Devicon

This book uses Devicon so you can see exactly how it's done in the repository.

  1. Download the stylesheet and put it in the root of your book.
  2. Download the fonts and put them in the theme/fonts/ directory of your book.
  3. Add the CSS file to the additional-css field of your book.toml.

FontAwesome 4

At the moment, mdBook relies on Font Awesome 4 which means you don't need to install anything.

```html,icon=.fa.fa-html5
<h1>Hello, World</h1>
```

Kitchen Sink

Note, that Devicon is used in this book which allows the usage of .devicon-* icons.

All combined

import this

Code Blocks in Block Quotes

Hello World.

This is a block quote.

#![allow(unused)]
fn main() {
println!("Hello World");
}

Automatic language detection

[[player]]
name = "john"
score = 3

Enforce no language

puts "hey"

puts "ho"

puts "let's go"

External icon

Make sure you have an internet connection.

numpy==1.26.2

Hiding lines

<!DOCTYPE html>
<html>
<body>
  <h1>Hello World</h1>
  <p>Click on the eye icon on the right side of the code block</p>
</body>
</html>

Multiple classes

puts "hi"