Usage

This is designed as a preprocessor plugin for mdbook and a compiler server running standalone.

Installation

There are two ways to install mdbook-lang:

You can install it with cargo if you have rust environment:

cargo install mdbook-lang

Or you can download the binary from github page. You should put the binary in your system's PATH.

You can cheeck the instalation with:

mdbook-lang --version

Configuration

After installation, you can configure mdbook-lang in your book's book.toml file through mdbook-lang install to config the plugin usefull for your mdbook.

$ mdbook-lang install /path/to/your/book

This will set the lang preprocessor plugins and the url of compiler server parameters.

For example:

[book]
authors = ["gaoxu.jeffrey"]
language = "en"
multilingual = false
src = "src"
title = "mdbook-lang example"

[preprocessor]

[preprocessor.lang]
command = "mdbook-lang"
server = "http://127.0.0.1:3333/api/v1/build-code"
cpp-enable = true
java-enable = true
go-enable = true
python-enable = true
javascript-enable = true
typescript-enable = true
scheme-enable = true
editable = true
disable-devtool-auto = false
disable-menu = false
clear-log = false
disable-select = false
disable-copy = false
disable-cut = false
disable-paste = false
ace-strict = false

[output]

[output.html]
additional-js = ["jquery.js", "disable-devtool.js", "lang.js"]
additional-css = ["lang.css"]

• server: The url of compiler server.

I deployed a compiler server, you can modify the value of server use it for test directly.

server = "https://183.205.132.14:3000/playground/api/v1/build-code"

Notice You should open https://183.205.132.14:3000 in your browser and ignore or close the security alert first, othewise you cannot access it when playing your programming language.

• language-enable: Enable the language for the repl, default value is true.

• disable-devtool-auto : Disable the browser debugger automatically, default value is false.

• ace-strict: Enable the strict mode of ace editor, default value is false. When enabled, the editor will not allow the user to cut, copy, and paste code in ACE editor.

Run the compiler server

Only Windows 7/8/10/11 needs install/uninstall Service

All cmd prompt commands need to be run as administrator.

• insrall the install the mdbook-lang as a service

C:\Windows\System32>mdbook-lang server install --hostname 127.0.0.1 --port 3333

Or use 127.0.0.1 as the default hostname, and 3333 for port:

C:\Windows\System32>mdbook-lang server install

When you donn't need the mdbook-lang service or want to change the hostname and/or port, you should uninstall and re- install it with different hostname and/or port argument(s).

Delete it forever:

mdbook-lang uninstall

If you want change hostname and/or port:

mdbook-lang server uninstall
mdbook-lang server install --hostname 0.0.0.0 --port 3333

Unix like OS and Windows 7/8/10/11

start mdbook-lang compiler server

Administror privilege needed for Windows oS.

You can run the compiler server with:

mdbook-lang server start

Or you can run the compiler server with --hostname or short -n and --port or short -parguments in Unix like OS:

mdbook-lang server start --hostname 127.0.0.1 -port 3333

For Windows

• start the service

C:\Windows\System32>mdbook-lang server start

or through the OS provided Service manager or Task manager GUI tool.

stop/restart/status subcommands

• stop server

mdbook-lang server stop

• restart server

mdbook-lang server restart

• check server status

mdbook-lang server status

Run the mdbook

mdbook serve -o

Options

norun

norun option will make the codeblock not rendered by the preprocessor. You can use this option if you want to show some code examples that should not be executed, and the language is enabled by language-enable=true.

```java,norun
// java codeblock with norun option
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}
```

And it will not be rendered by this preprocessor:

// java codeblock with norun option
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}

```java
// java codeblock without norun option
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}
```

And it will be rendered by this preprocessor:

// java codeblock with norun option
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}

Shortcuts

Language Extensions

This preprocessor only recongnizes specific extensions for sepecific language. For example, you can only use use c++ or cpp codeblock for cpp code, use python or py codeblock for python code.

Here is the full list of extensions:

In order to to support some langguages, you should install corresponding compilers on compiler server host.

Performance

It is no doubt that the execution of codeblock through browser is really fast compared with in IDEs with additional a slight network delay. And the overload of the compiler server is also not a big problem.