gitbook-plugin-include-codeblock

GitBook plugin for including file


Keywords
gitbook, plugin, gitbook-plugin
License
MIT
Install
npm install gitbook-plugin-include-codeblock@3.2.3

Documentation

gitbook-plugin-include-codeblock Actions Status: test

GitBook Plugin for including file.

  1. Installation
  2. Plugin options
  3. Usage
  4. Example
  5. CLI

Installation

book.json

{
  "plugins": [
    "include-codeblock"
  ]
}

and

gitbook install

Plugin options

Several options can be set in book.json to customize the plugin.

option value Description
template {"default","full","ace",...} or custom path reindent code if marker or slice is used
unindent {true,false} default:false reindent code if marker or slice is used
fixlang {true,false} default:false fix some errors with code lang (e.g C++, ...)
lang {"c_cpp","javascript", ...} lang color syntax (not set => auto deduce, see lang section).
edit {true,false} allow edit code (ace template required)
check {true,false} syntax validation (ace template required)
theme {"monokai","coffee",...} check syntax (ace template required)

Just add the desired optin under pluginConfig in the book.json file

{
    "gitbook": "3.x.x",
    "pluginsConfig": {
        "include-codeblock": {
            "template": "ace",
            "unindent": true,
            "theme": "monokai"
        }
    }
}

Templates

Templates let customize the rendered code. Several default templates are available

template description
"default" default template, standard markdown code style
"full" enable title, labeling, id, ...
"ace" enable ace code rendering (ace plugin required)
"acefull" enable ace code rendering with title, label, id, ... (ace plugin required)

Custom templates can be created to render the code by specifying a custom path to the template file.

{
    "gitbook": "3.x.x",
    "pluginsConfig": {
        "include-codeblock": {
            "template": __dirname + "/" + "path/to/custom.hbs",
        }
    }
}

See templates/ and examples/ for details.

Any contribution is welcome. Propose your new templates via pull-requests.

Ace plugin

It is possible to use the gitbook ace plugin to have code numbering or custom themes (See gitbook-ace-plugin for more details). To use ace within include-codeblock, you have to load the ace plugin after include-codeblock! and choose an ace temple (see templates/)

{
    "gitbook": "3.x.x",
    "plugins" : [
        "include-codeblock",
        "ace"
    ]
    "pluginsConfig": {
        "include-codeblock": {
            "template": "ace", // or acefull
        }
    }
}

Usage

General usage:

[import:"tag",option0:"value0", ...](path/to/file)

where <...> are required tags, <<...>> are optional tags.

tag description
import use import or include tag.
tag optional tag to include code snippet (see snippet.
optionX optional key:value or key=value option (See Command options).

See examples for more details.

Examples

fixtures/test.js

console.log("test");

Write following the link with include or import label.

[include](fixtures/test.js)

or

[import](fixtures/test.js)

Result

console.log("test");

ℹ️ Do not inline!

// won't work
Example of code [import](fixtures/test.js)

You could import the same code directly from the repository with nice color template

[import, template:"acefull", title:"example of code", theme:"monokai"](https://raw.githubusercontent.com/azu/gitbook-plugin-include-codeblock/master/test/fixtures/test.js)

Command options

Option can be passed locally and may depend on the template your are using.

option value Description
unindent {"true","false"} reindent code if marker or slice is used
title "<your title>" Title for the code full template required
name "<your_filename>" name of the included file full template required
class "<your_classname>" html class for the title full template required
id "<your_id>" html class for custom style full template required
label "<your_ref_label>" reference label (latex like) full template required
edit {"true","false"} allow edit code (ace template required)
check {"true","false"} check syntax (ace template required)
template {default,full,ace,...} or custom path reindent code if marker or slice is used
lang {"c_cpp","javascript", ...} lang color syntax (not set => auto deduce, see lang section).
fixlang {true,false} default:false fix some errors with code lang (e.g C++, ...)
theme {"monokai","coffee",...} check syntax (ace template required)

For more details see sections below.

Hardcoded class

When you import a TypeScript file .ts: The parser correctly finds .ts in the language-map extensions for both TypeScript and XML, then automatically chooses XML.

If you want to specify language type, put lang:"<lang-name>" to label.

[import, lang:"typescript"](hello-world.ts)

e.g.) typescript's aceMode value is typescript.

Sliced Code

If you want to slice imported code and show.

[import:<start-lineNumber>-<end-lineNumber>](path/to/file)
  • ℹ️ lineNumber start with 1.

All Patterns:

All: [import, hello-world.js](../src/hello-world.js)
1-2: [import:1-2, hello-world.js](../src/hello-world.js)
2-3: [import:2-3, hello-world.js](../src/hello-world.js)
2>=: [import:2-, hello-world.js](../src/hello-world.js)
<=3: [import:-3, hello-world.js](../src/hello-world.js)

Snippet code

You can also import snippet code delimited by a tag. It follows the doxygen snippet standard Snippet is doxygen compatible. (See also how to document the code)

[import:'<marker0,marker1,...>'](path/to/file)

Remarks

  • ℹ️ marker name begins with an alphabet character
  • ℹ️ tags follows the doxygen standard: language comment for documenting code + tag between bracket
  • ℹ️ Several markers separated by a comma will concatene snippets into a unique snippet. Spaces are taken into account.

For example, considering the following C++ source code

// test.cpp source code
int main()
{
    /// [marker0]
    int a;
    //! [marker1]
    int b;
    //! [marker1]
    int c;
    /// [marker0]

    // [notmarked]
    int d;
    // [notmarked]

    //! [marker2]
    int e;
    //! [marker2]
}

In GitBook, the following commands

[import:'marker1'](path/to/test.cpp)

will result to

    int b;

The command [import:'marker0'](path/to/test.cpp) will result to

    int a;
    int b;
    int c;

The command [import:'marker1,marker2'](path/to/test.cpp) will result to

    int b; 
    int e;

But the command [import:'notmarked'](path/to/test.cpp) will fail as it does not respect the doxygen documenting standard. (See documenting the code)

Unindented code

Consider the following source code:

class Hello {
    /// [some-marker]
    void world() {
        // nice
    }
    /// [some-marker]
}

And the following command:

[import:"some-marker",unindent:"true"](path/to/test.java)

This will result in unindented code:

void world() {
    // nice
}

Unindent behaviour can also be specified globally in the plugin configuration.

See also

Example

Please See examples/.

screenshot

CLI

This gitbook plugin include Command line tools. It just convert markdown to markdown.

$ npm install -g gitbook-plugin-include-codeblock
# Convert Markdown to Markdown
$ include-codeblock ./README.md --output RENDER_README.md

FAQ

How to migrate Version 1.x to 2.x

Version 2.0 contain a breaking change.

It change default template for displaying embed code.

Version 1.x template.

{{#if title}}
{{#if id}}
{% if file.type=="asciidoc" %}
> [[{{id}}]]link:{{originalPath}}[{{title}}]
{% else %}
> <a id="{{id}}" href="{{originalPath}}">{{title}}</a>
{% endif %}
{{else}}
{% if file.type=="asciidoc" %}
> [[{{title}}]]link:{{originalPath}}[{{title}}]
{% else %}
> <a id="{{title}}" href="{{originalPath}}">{{title}}</a>
{% endif %}
{{/if}}
{{else}}
{% if file.type=="asciidoc" %}
> [[{{fileName}}]]link:{{originalPath}}[{{fileName}}]
{% else %}
> <a id="{{fileName}}" href="{{originalPath}}">{{fileName}}</a>
{% endif %}
{{/if}}

``` {{lang}}
{{{content}}}
```

Version 2.x template.

``` {{lang}}
{{{content}}}
```

If you want to use Version 1.x template, please set template option to book.json or book.js

const fs = require("fs");
module.exports = {
    "gitbook": "3.x.x",
    "title": "gitbook-plugin-include-codeblock example",
    "plugins": [
        "include-codeblock"
    ],
    "pluginsConfig": {
        "include-codeblock": {
            // Before, create user-template.hbs
            "template": fs.readFileSync(__dirname + "/user-template.hbs", "utf-8")
        }
    }
};

If you want to know more details, please see templates/.

Tests

npm test

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

License

MIT