theme-api

by GitbookIO

GitbookIO / theme-api

Theme for publishing a beautiful API documentation with GitBook

134 Stars 28 Forks Last release: Not found 69 Commits 6 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

GitBook API Theme

Theme for using GitBook to publish an API documentation.

This theme works perfectly with search plugins (like the default plugin or algolia).

Screenshot

It also integrates well with the default fontsettings plugin to use the Dark theme.

Dark theme

Usage

This theme requires GitBook version 3 or later.

Add the theme to your book's configuration (book.json):

{
    "plugins": ["theme-api"]
}

To use the Dark theme by default:

{
    "plugins": ["theme-api"],
    "pluginsConfig": {
        "theme-api": {
            "theme": "dark"
        }
    }
}

Defining methods

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.

Sample blocks

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" %}

$ npm install gitbook-api

{% sample lang="go" %}

$ go get github.com/GitbookIO/go-gitbook-api

{% endmethod %}

JS Sample Go sample

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-api"],
  "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"
        }
      ]
    }
  }
}

Language switcher

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.

Common blocks

Common blocks are used to display content to be displayed for all languages in your examples.

{% method %}
## Simple method

{% sample lang="js" %} This text will only appear for JavaScript.

{% sample lang="go" %} This text will only appear for Go.

{% common %} This will appear for both JavaScript and Go. {% endmethod %}

Layout

The theme provides two layouts to display your examples: one-column or two-columns (split).

One column layout

One column

Split layout

Split

The layout can be toggled from the toolbar using the layout icon: Layout icon

The default aspect can also be set in the theme configuration in the

book.json
file:
{
  "plugins": ["theme-api"],
  "pluginsConfig": {
    "theme-api": {
      "split": true
    }
  }
}

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.