/gitbook-docs-template

Gitbookで作成するマークダウンドキュメントのテンプレート

Gitbook docs template

CircleCI

What is it?

An boilerplate for writing technical documentation on local Gitbook.

  • Work on local with Gitbook-cli and your repository. Private repository also yes.
  • Install gitbook/gitbook-cli as a project dependency. No use globally.
  • Some of the Gitbook plugins that are useful for writing technical documents is installed.

Tested on macOS.

Installed plugins

Following plugins is installed.

Get started

Default docs to your book's name. and run it.

export PJNAME=docs && git clone --depth 1 https://github.com/TakuyaHarayama/gitbook-docs-template.git docs && cd docs && npm install && rm -fr .git && npm run serve

open http://localhost:4000

Additional requirements

gitbook-plugin-uml

If you need uml plugin. you need following steps.

Step 1. Install PlantUML. (Download plantuml.jar to root path)

Step 2. Install graphviz package.

$ brew install graphviz

Usage

# gitbook init
$ npm run init

# gitbook install
$ npm run install

# gitbook serve
$ npm run serve

# gitbook build
$ npm run build

Plugins Usage

gitbook-plugin-mermaid-gb3

sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?
Loading 
graph LR
    subgraph Side-A
        A[A]
        B[BB]
    end
    subgraph Side-B
        C[CCC]
        D(DDDD)
    end

    A-. ほげ<br>hoge .->B
    A-->C
    B-->D
    C-->D
Loading

gitbook-plugin-uml

@startuml

    Class Stage
    Class Timeout {
        +constructor:function(cfg)
        +timeout:function(ctx)
        +overdue:function(ctx)
        +stage: Stage
    }
     Stage <|-- Timeout

@enduml

@startuml
testdot
@enduml

gitbook-plugin-graph

{% graph %} { "title":"cos(2PIx/2)(1+0.5cos(2PIx/100))",
"grid":true, "xAxis": { "label":"Sample", "domain": [0,300] }, "yAxis": { "label":"Amplitude", "domain": [-1.5,1.5] }, "data": [ { "fn": "cos(2PIx/2)(1+0.5cos(2PIx/100))"},
{ "fn": "(1+0.5cos(2PIx/100))"} ] } {% endgraph %}

theme-api

{% method %} How to install GitBook API client.

{% sample lang="curl" %}

$curl -X GET https://api.keion.com/v1/members \
     -H "Content-Type: application/json" \
     -d @- << EOF
     {
       "access_token": "59xxxxxxxxxxxxxxxxxxxxxxxxxx",
       "space_id": "59xxxxxxxxxxxxxxxxxxxxxxxxxx",
       "limit": 1
     }
EOF

Example Response

{
  "data": {
    "members": [
      {
        "id": "1",
        "name": "Yui Hirasawa",
        "job": "guitar",
        "sex": "female",
        "age": "18"
      }
    ]
  }
}

{% endmethod %}

include-csv

{% includeCsv src="./csv/members.csv", useHeader="true", limit=6 %} {% endincludeCsv %}

Linter

$ npm run -s lint
$ npm run -s lintfix

Deploy to S3

EXAMPLE CircleCI

  • Change YOUR-PROJECT to your project name
  • Craete AWS S3 bucket YOUR-PROJECT-docs
  • Set IAM KEYS to CircleCI environment variables
<script src="https://gist.github.com/TakuyaHarayama/447318ad453b3673f81feed4b7feaf75.js"></script>

License

Released under the MIT license.