gitbook-plugin-include-codeblock

GitBook Plugin for including file.

Installation
Plugin options
Usage
Example
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)

ℹ️ For ace template, see Ace section
ℹ️ For more template, consult the list in template/.

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)

[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)

ℹ️ choose <lang-name> of lang-<lang-name> from language-map's aceMode value.
- blakeembrey/language-map: JSON version of the programming language map used in Linguist

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

https://github.com/blakeembrey/language-map/blob/b72edb8c2cb1b05d098782aa85dd2f573ed96ba3/languages.json#L4140

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.

Example

Please See examples/.

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.

Breaking Change: change default template by azu · Pull Request #31 · azu/gitbook-plugin-include-codeblock

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

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

License

MIT

crazycodeboy / gitbook-plugin-include-codeblock