Use Gitbook to generate a document center site

After more than a month, Bugtags recently launched its own documentation site (docs.bugtags.com), where you can find most of the issues related to the integration and use of Bugtags.

Before that, we used the help center products and services provided by a third party, edited the content of the documents on the background of their website, and established our own document system; but after using it for a long time, we found that there are still many unpleasant places, at least not in line with ours Habit;

For example: the product documentation is edited and stored in the database in rich text form; and we are very fond of writing documents in Markdown format; and database preservation is also destined to be unable to use git for document version management and control;
Help center page There are only a few default styles, although it provides template design functions, it is actually very tasteless and completely unable to meet our custom needs. Based on this, we try to find other solutions to solve this problem.

our needs

We first want to understand what kind of document management system we need;

1. Use Markdown to write documents, the so-called "no Markdown, no documents"; our engineers are accustomed to using Markdown to write documents, and even Jingjing, the only beauty in our company who is not technical, said: "How can documents not be Markdown? !" Just when she urged the draft, she also said: "It must be Markdown, or I won't accept it."

2. The generated website is purely static, so it will be fast. At the beginning, we also thought of two solutions, one is to download the Markdown file to the front end and render it into HTML at the front end; the other is to generate HTML from all Markdown at the back end, and load HTML directly when browsing the front end. After consideration, the latter option has to be adopted. In the former case, it would be a waste for every end user to spend resources to render Markdown; and the speed cannot be guaranteed. The latter idea is very clear: write Markdown documents first, and generate static websites after the documents are written, so that all the end users visit are static HTML pages.

3. git management. This shouldn't need much to say. To update and upgrade documents, there must be a powerful version management system, which is none other than git.

After a series of attempts, we started to take Gitbook and rewrite it to generate our own documentation center site.

Introduction to Gitbooks

Gitbook is an e-book making program; it generates e-books from the organized Markdown files according to the hierarchy; the format of this e-book can be epub, mobi, pdf, or even a website;

Its use is also very simple, basically only two steps:

Using the gitbook initcommand, SUMMARY.mdthe book directory structure will be generated according to the content in the file;
Use gitbook buildPut Books to generate the format you need.

Then all book configurations can be defined by book.jsonfiles .
For more detailed usage of Gitbook, you can refer to Gitbook Concise Tutorial . This website itself is also generated by Gitbook.

Reasons to use Gitbook

Gitbook is a strong match for our needs, with the following points:

Open source. As a small start-up business, many of our projects benefit from open source products. There are many third-party plug-ins to promote the development of this product;
Write documents in Markdown format;
The directory structure is clear; we can group all Markdown documents into different directory levels according to different themes;
The generated web page is purely static. Gitbook can generate static HTML pages from all Markdown documents;
Since all contents are Markdown files, git can be used for version management and control;
After installing Gitbook on the server, customize a git hookscript to automatically generate a website after each document update is submitted;

Where Gitbook doesn't fit our needs

The idea of Gitbook itself is the concept of organizing Markdown files into a book; this is still a bit different from what we need to do with a website; so there will be a lot of things to change.

If you compare our website with any site generated by Gitbook by default, such as Gitbook's official help documentation site , you will find many differences; specifically, we modify the following things:

directory generation logic;
plugin usage;
search;
Template style.

directory generation logic

We added a header and footer to the Gitbook template. The style of the page directory is also different: this is not just the presentation format. Careful reading will find that in our documentation website, there are some documents that do not appear in the directory. For example, there are a lot of tedious FAQs; if every article has to be put into a table of contents, the table of contents will become very verbose. These have to change the generation logic of Gitbook's default directory menu.

Here's what we do: define a level specifically in the SUMMARY.mdfile (the contents of this file that define the directory structure), and the level name is called hide-docs, something like this:

- [hide-docs]()
    - [集成 iOS SDK 看不到悬浮球？](faq/ios/icon-not-found.md)
    - [用 CocoaPods 集成无法获取最新版的 SDK？](faq/ios/cocoapods-sdk-update.md)
    - [手动集成 SDK 添加 -ObjC 导致编译出错？](faq/ios/integrate-manual-build-error.md)
    - [集成 SDK 后，编译产生了很多警告？](faq/ios/integrate-build-warning.md)

All documents under this level do not need to appear in the directory! However, Gitbook will still read the documents at this level, so we need to slightly rewrite the logic of generating the directory: if it is judged that it is a document at hide-docsthis level, the directory will not be generated.
This requires rewriting the method in the website.jsfile _writeTemplateOur code is as follows:

if( !this.replacedSummary){
  this.replacedSummary = {chapters:[]};
  if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length ){
    var chapters = that.book.summary.chapters;
    for(var i =0; i < chapters.length;i++){
      var cur = chapters[i];
      if(/hide-docs/.test(cur.title)){
          continue;
      }
      this.replacedSummary.chapters.push(cur);
    }
  }
}

Then assign the summaryproperty as our filtered replacedSummaryvariable. Running this again gitbook build, you will find that all Markdown has been generated HTML, but the directory in the generated HTML page does not contain these documents that we need to hide.

Plugin disabled

Gitbook enables 5 plugins such as search and font adjustment by default, but we don't need these; so we need book.jsonto specify pluginsthe properties in as follows:

{
  "plugins":["-sharing","-livereload","-search","-fontsettings"]
}

Use a minus sign to indicate that these plugins are not enabled (the official help document for this configuration method does not mention it).

search

The next important part is the search, because the official Gitbook search does not support Chinese search at all, so we disabled it. Although there are open source search plug-ins that support Chinese, the display of search results is very unintuitive; these need to be Improve from both templates and search engines.

Document search We finally use the powerful elasticsearch to provide full-text search services, and display search results with modified templates. Regarding elasticsearch, this is a more complicated topic; not only that, interested friends can search for related tutorials.

template

Since Gitbook is the concept of organizing Markdown into a book; for a book, except for the cover, it is the table of contents and the body of the table of contents.

What we need is a document website, not only the document content page, but also other pages, such as the home page, search page, 404 page, and possibly other pages. At this time, I can't help but miss jekyllthis static blog generation tool. It will find all the HTML files in the root directory and find their corresponding templates to nest and generate HTML pages.

However jekyll(and what I have tried otherwise hexo) the flaw is that the way Markdown documents are organized is relatively flat; the logical hierarchy is defined by defining directories and tags in the header of each Markdown document, while the physical hierarchy generated is generated by the file defined by the date in the name. This is the biggest flaw.

Currently I've used a more brutal way to solve this problem:

Homepage : Gitbook supports multiple languages, and if multiple languages are defined, there will be a template page to generate a homepage to select the language entry; so I take this page that should be used as the language selection entry as our homepage; well, it’s you The page you see now.
404 page : I wrote a 404 myself, and copied this file to the root directory every time I regenerated the website; it feels silly...
Search page : Every content page can be a search page; because I display the search results in the content area of the current page; in this way, the page results can be displayed by partial refresh; there is no need to make a separate template page.

achievement

Finally, we adopted the part of Gitbook that met our needs, and after trying to solve the above points that were not suitable, we formed our current document center site.

Usually publishing is also very convenient; write Markdown files directly, and submit them to the server after writing. A git hookhook , and every time a document is updated, the static website will be automatically regenerated, and the search index will be regenerated. If you have any questions about the use of Bugtags, you can check it out here first. Welcome to visit.

Alt text