GitBook Plugin for including file.
book.json
{
"plugins": [
"include-codeblock"
]
}and
gitbook installSeveral 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 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.
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
}
}
}[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.
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)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.
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>oflang-<lang-name>from language-map'saceModevalue.
e.g.) typescript's aceMode value is typescript.
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)
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)- ℹ️ 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)
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
Please See examples/.
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
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/.
npm test
- 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
MIT