These days, I’m writing instruction manuals. After that, I would like to publish it as a website. So I’ve investigated about solutions, which suit below needs.

  • Writing a document based on markdown syntax
  • Embedding a video
  • Generating a website
  • Searching documents
  • Custom theme

GitBook looks a nice option. See a generated site using it, “Front-end Handbook”. It generates a static website from markdown documents. To install it, you just need to type one line command.

❯ npm install -g gitbook-cli

After that, you can initialize with gitbook init command. That will generate two files:README.md and SUMMARY.md.

  • README.md is the first page and contains an introduction.
  • SUMMARY.md contains the table of content, which is shown as a left slide menu.
❯ gitbook init
info: create README.md
info: create SUMMARY.md
info: initialization is finished

❯ ls
README.md  SUMMARY.md

After modifying a document, run the gitbook serve command. If your document is modified, that will detect it and automatically update the static site.

❯ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.6s !

Starting server ...
Serving book on http://localhost:4000

If you just want to build a static site only, run gitbook buid instead of gitbook serve.

When you open the site (either open the index.html or http://localhost:4000), you will see a similar page like this.

Last but not least thing is publishing as a website. Github Pages allows us to publish a static website freely. What you need to do is to add files into the gh-pages branch. We already have generated files for that. So, remaining thing is to add those fils into the gh-pages branch. Unfortunately, gitbook doesn’t support it as a command line option. You need to do it manually. To do it easily, I’ve created a shell script.

Whenever you run this script, it will generate files for the static website and push into the gh-pages branch. With a continuous integration, such as TeamCity, it can be triggered hourly or when the repository file is changed.

❯ ./publish_gitbook.sh

Your site will be available at http(s)://<username>.github.io/<projectname>.

If you want to use GitBook but are not interested in publishing your github pages, check GitBook site. You can easily create manuals on the site with nice wysiwyg(what you see is what you get) editor.

References