Gitbook Templating
GitBook uses the Nunjucks templating language to process pages and theme's templates.
The Nunjucks syntax is very similar to Jinja2 or Liquid. Its syntax uses surrounding braces { } to mark content that needs to be processed.
The gitbook documentation on templating covers the basics, but the docs-theme has some specific layouts that are used within the Bandwidth documentation.
The theme allows to easily define methods with examples for different languages, using the templating blocks syntax.
A method block can contain any number of nested sample and common blocks.
Those nested blocks are documented below.
While the body of the method block will be used as the definition for your method, each sample will be used to display examples. To do so, each sample block should specify a language using the lang arguments.
This is great for managing examples in different languages, for instance when documenting multiple API clients.
{% method -%}
## Install {#install}
The first thing is to get the GitBook API client.
{% sample lang="js" -%}
```bash
$ npm install gitbook-api
```
{% sample lang="go" -%}
```bash
$ go get github.com/GitbookIO/go-gitbook-api
```
{% endmethod %}
On each page containing method blocks with samples, a switcher is automatically added at the top-right corner to easily select which language to display.
The name of each language can be configured in your book.json file, with it's lang property corresponding to the sample block lang argument:
{
"plugins": ["theme-bandwidth"],
"pluginsConfig": {
"theme-api": {
"languages": [
{
"lang": "js", // sample lang argument
"name": "JavaScript", // corresponding name to be displayed
"default": true // default language to show
},
{
"lang": "go",
"name": "Go"
}
]
}
}
}
Most programming languages are supported by default, with name mapping following the highlight.js convention.
Note that a sample block can contain any markdown content to be displayed for this language, not only code blocks, as illustrated below.
The Bandwidth documentation site has two different ways of breaking the site into 'triple column' layouts.
The {% method %} template can only be used once per page. However, it can be used anywhere and be closed anywhere. But once the {% method %} has been used, you can not create another method
# Title of the article here
Some sort of text, maybe a table.
The text here will span across the entire page.
| thing 1 | thing 2 |
|:--------|:---------|
| Crazy | Craziest |
{% method %}
## Demo on how to use thing1
Here's how to use thing1.
The text here will be in the 'middle column'
{% common %}
The `{% common %}` tag moves the text to the 'right column'.
Once you go to the right column, **you can not go back to the middle**
You can, however bounce between `{% common %}` and `{% sample lang="" %}` as many times as you'd like.
Keep in mind that whatever is after `{% common %}` and before the `{% sample lang="" %}` will be common across all samples.
{% sample lang="js" -%}
This will only be viewable when the language selector is `js`
{% sample lang="ruby" -%}
This will only be viewable when the language selector is `ruby`
{% common %}
This is now viewable by all langauges again.
{% endmethod %}
The `{% endmethod %}` ends the 'triple column layout' and defaults back to the normal page.
Text here will now stretch across the entire page.
The other common layout uses both the multimethod & extendmethod template tags to permit multiple methods within a single document. Using the default theme-api provided by gitbook does already allow multiple methods. However, the docs-theme does not allow using multiple {% method %} in the same page. To work around the self-imposed limitions, we created {% multimethod %} and {% extendmethod %}. The template tag {% extendmethod %} works the same as {% method %} described above. Using the {% extendmethod %} tag will create a three column layout with {% common %} forcing the content in the right column. However, after the {% endextendmethod %} tag, you can use the {% extendmethod %} again to bounce back and forth between triple column and dual column layouts. This type of document and layout can be really useful for building complex tutorial where multiple different methods are explained.
The only gotcha with this system is the {% multimethod %} tag.
{% extendmethod %} MUST START WITH {% multimethod %} {% endmultimethod %}
The {% multimethod %} tag is used to grab various sample languages specified within the various {% extendmethod %}. It's a relatively hacked together solution that works with few fallouts.
All together a document or tutorial that wanted to use multiple different triple-column sections, would look something like the example below.
{% multimethod %}
{% endmultimethod %}
# Title of the article here
## About
**Note that before any text the multimethod tag is opened and closed**
## Demo on how to use thing1
Some sort of text, maybe a table.
The text here will span across the entire page.
| thing 1 | thing 2 |
|:--------|:---------|
| Crazy | Craziest |
{% extendmethod %}
### Specific parameters
Here's how to use thing1.
The text here will be in the 'middle column'
{% common %}
The `{% common %}` tag moves the text to the 'right column'.
Once you go to the right column, **you can not go back to the middle**
You can, however bounce between `{% common %}` and `{% sample lang="" %}` as many times as you'd like.
Keep in mind that whatever is after `{% common %}` and before the `{% sample lang="" %}` will be common across all samples.
{% sample lang="js" -%}
This will only be viewable when the language selector is `js`
{% sample lang="ruby" -%}
This will only be viewable when the language selector is `ruby`
{% common %}
This is now viewable by all langauges again.
{% endextendmethod %}
## Demo on how to use thing 2
At this point we're still in dual column layout.
The text here will span the entire page.
| Parameters | Description |
|:-----------|:-------------------------------------|
| `key` | overview on what the key does for ya |
{% extendmethod %}
### Specific parameters
Here is how to use thing2.
Text here will be in the 'middle column'.
{% common %}
Back to the far right column
{% sample lang="js" -%}
`JS` example
<etc>...</etc>
{% endextendmethod %}
And back to dual-column layout.