Introduction

Features

📱 Optimized for all screen sizes
🎨 Optimized for all themes
👑 Written in Nim
📦 No additional dependencies required (not even Cargo or Rust)

Planned

Map languages to icons in book.toml
Support local SVGs

Installation

Quick Install (CLI)

echo "---" && echo "Enter the path where the JavaScript file should be put in (no trailing slash, period for current directory)" && read path_scripts && echo $(curl -sS https://raw.githubusercontent.com/phoenixr-codes/mdbook-code-block-plus/master/codeblockplus.min.js) > "$path_scripts/codeblockplus.min.js" && echo "Enter the path where the CSS file should be put in (no trailing slash, period for current directory)" && read path_stylesheet && echo $(curl -sS https://raw.githubusercontent.com/phoenixr-codes/mdbook-code-block-plus/master/codeblockplus.css) > "$path_stylesheet/codeblockplus.css"

Manual Installation

Visit the repository
Download codeblockplus.min.js
Download codeblockplus.css
Move these file into your book directory

Build Manually

Script and Stylesheet

git clone --depth 1 https://github.com/phoenixr-codes/mdbook-code-block-plus.git
./build
# or: ./build debug
cp codeblockplus.min.js PATH/TO/BOOK
cp codeblockplus.css PATH/TO/BOOK

Book

cd book
mdbook serve

Usage

In order to use Code Block Plus in your book the script and stylesheet must be included in your project. Depending on the location of these files within your project directory following lines need to be added or modified in your book.toml configuration file.

# ...
[output.html]
additional_css = ["theme/codeblockplus.css"]
additional_js = ["scripts/codeblockplus.min.js"]

After that your code block's appearance should be changed in a way that they have a header with the name of the language you specified. So this does not apply to code blocks where no language is specified.

Tip

While code blocks often accept a short variant of the name, it is a good idea to go with the longer one so readers can identify the language better. The syntax is not affected by such changes. For example js and javascript both use the JavaScript highlighter.

Customization

Add an Icon

You can add Font Awesome icons to the code block headers. Sadly mdBook uses version 4 which does not have many icons of programming languages.

A workaround is planned for using Font Awesome 5 and custom SVGs.

```html,icon=html5
<p>Hello World!</p>
```

This code block uses the icon named html5 which reneders like below:

<p>Hello World!</p>

Overriding or Setting the Language

Code Block Plus takes the language specified in the code block but can be overriden (or set when no language is specified) by using the lang class.

```python,lang=MOJO
def greet(name: str) -> str:
    print(f"Hello {name}")
```

The above renders as below:

def greet(name: str) -> str:
    print(f"Hello {name}")

If you want to fully remove the header while remaining the syntax highlighting, then do the following:

```python,lang=none
def greet(name: str) -> str:
    print(f"Hello {name}")
```

This will render as familar:

def greet(name: str) -> str:
    print(f"Hello {name}")

Including a file path

A file path can be specified to give the user an idea of which file is beeing talked about. This can be approached by setting the filepath class.

```toml,filepath=app/config.toml
[controls]
jump = 0
left = 4
right = 6
duck = 1
```

The rendered result is:

[controls]
jump = 0
left = 4
right = 6
duck = 1

Everything combined

```html,filepath=path/to/file.html,icon=html5,lang=MEGAHTML,hidelines=%
%<html>
%<body>
<p>hi</p>
%</body>
%</html>
```

As you can see above, built-in classes such as hidelines can still be used. In this case the "view" button on the top right of the code block below can be toggled.

<html>
<body>
<p>hi</p>
</body>
</html>

Kitchen Sink

This chapter exists to see if everything is styled as expected and uses a lot of different examples for that.

no language or attributes specified

this.is((a) => usual("code block"));

Lorem ipsum dolor sit amet consectetur adipisicing elit. Itaque sit temporibus cupiditate in ducimus illum assumenda dolor, dignissimos laboriosam voluptate dolorem dolore eum repellendus minima, nisi sequi? Eveniet, dignissimos asperiores!

<!-- filepath is set -->
<p>
    My name is Oliver Queen. After five years in hell, I have come home with only
    one goal: to save my city. Now others have joined my crusade. To them I'm Oliver
    Queen. To the rest of Starling City, I am someone else. I am... something else.
    I am... The Arrow
</p>

import this

# lang is set to none
import this

/* icon and lang set */
:not(html) { }

Lorem ipsum dolor sit amet consectetur adipisicing elit. Itaque sit temporibus cupiditate in ducimus illum assumenda dolor, dignissimos laboriosam voluptate dolorem dolore eum repellendus minima, nisi sequi? Eveniet, dignissimos asperiores!
<html>
<body>
<p>Hello World</p>
</body>
</html>

[player]
name = "John"