GitBook plugin for including file
npm install gitbook-plugin-include-codeblockGitBook Plugin for including file.
1. Installation
2. Plugin options
3. Usage
4. Example
5. CLI
book.json
``json`
{
"plugins": [
"include-codeblock"
]
}
and
`sh`
gitbook install
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
`js`
{
"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) |
- :information_source: For ace template, see Ace section
- :information_source: 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.
`js`
{
"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/)
`js`
{
"gitbook": "3.x.x",
"plugins" : [
"include-codeblock",
"ace"
]
"pluginsConfig": {
"include-codeblock": {
"template": "ace", // or acefull
}
}
}
#### General usage:
`
import:"tag",option0:"value0", ...
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
`js`
console.log("test");
Write following the link with include or import label.
`markdown`
include
or
`markdown`
import
Result
` js`
console.log("test");
:information_source: Do not inline!
` js`
// won't work
Example of code import
You could import the same code directly from the repository with nice color template
`markdown`
import, template:"acefull", title:"example of code", theme:"monokai"
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
| | " | Title for the code full template required|name
| | " | name of the included file full template required |class
| | " | html class for the title full template required |id
| | " | html class for custom style full template required |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:.ts
The parser correctly finds in theXML
language-map
extensions for both TypeScript and XML, then automatically chooses .
If you want to specify language type, put lang:" to label.
`markdown`
import, lang:"typescript"
- :information_source: choose of lang- 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
If you want to slice imported code and show.
`markdown`
import:
- :information_source: lineNumber start with 1.
All Patterns:
`
All: import, hello-world.js
1-2: import:1-2, hello-world.js
2-3: import:2-3, hello-world.js
2>=: import:2-, hello-world.js
<=3: import:-3, 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)
`markdown`
import:'
#### Remarks
- :information_source: marker name begins with an alphabet character
- :information_source: tags follows the doxygen standard: language comment for documenting code + tag between bracket
- :information_source: 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
`cpp
// 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
`markdown`
import:'marker1'
will result to
`cpp`
int b;
The command import:'marker0' will result to
`cpp`
int a;
int b;
int c;
The command import:'marker1,marker2' will result to`cpp`
int b;
int e;
But the command import:'notmarked' will fail as it
does not respect the doxygen documenting standard.
(See documenting the code)
Consider the following source code:
`java`
class Hello {
/// [some-marker]
void world() {
// nice
}
/// [some-marker]
}
And the following command:
`
import:"some-marker",unindent:"true"
This will result in unindented code:
`java`
void world() {
// nice
}
Unindent behaviour can also be specified globally in the plugin configuration.
See also
- Allow to put marker in xml · Issue #63 · azu/gitbook-plugin-include-codeblock
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 %}
> {{title}}
{% endif %}
{{else}}
{% if file.type=="asciidoc" %}
> [[{{title}}]]link:{{originalPath}}[{{title}}]
{% else %}
> {{title}}
{% endif %}
{{/if}}
{{else}}
{% if file.type=="asciidoc" %}
> [[{{fileName}}]]link:{{originalPath}}[{{fileName}}]
{% else %}
> {{fileName}}
{% 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
`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
1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes:
4. Push to the branch:
5. Submit a pull request :D
MIT