❤
npm
Sign UpSign In

gitbook-plugin-include-codeblock-patched

3.1.2 • Public • Published

gitbook-plugin-include-codeblock Build Status

GitBook Plugin for including file.

  1. Installation
  2. Plugin options
  3. Usage

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", ...](url/or/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>" hmlt 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.

Example

Please See examples/.

screenshot

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

Readme

Keywords

Package Sidebar

Install

npm i gitbook-plugin-include-codeblock-patched

Repository

github.com/azu/gitbook-plugin-include-codeblock

Homepage

github.com/azu/gitbook-plugin-include-codeblock

Weekly Downloads

0

Version

3.1.2

License

MIT

Last publish

Collaborators

  • tschaub
Try on RunKit
Report malware