Use Gitbook to write your API documentation

Use Gitbook to write your API documentation published On:november 18, 2014

Gitbook is a very good community, there are a lot of good writers to publish their own books, as if leanpub, probably a lot of people like leanpub, but I still like Gitbook, this is similar to the original GitHub community. At the same time, Gitbook also provides an open source supporting tools. Perhaps see this article many people very early know gitbook, but perhaps you have not used, now gitbook already more mature, function also more perfect. Here we first introduce the use of the next gitbook.

Use of Gitbook

When you use Gitbook, when you create a new project, the following options will pop up, a total of four types of templates available to you to choose, in fact, they are no different, just a markdown template:

We have chosen the first, of course, the first attempt of friends, you can choose to see a different markdown template.

, Gitbook Editor, is actually a special markdown editor. I created a test project as an example, you can also create a new book yourself, and then open the source directory, you will see the following file:

• _book folder
• Summary.md
• Readme.md

Summary.md This file is the directory structure of the book. Gitbook Editor for Chinese support is not very good, sometimes you use editor to create a chapter, named in Chinese, but when you click on the new chapter, will be error, the solution is to use your own editor to open this file, directly edit the file is good.

Specific editor how to get started, it is not detailed, I believe you will use the Markdown editor will be used in editors.

Once you have created a book, you can pass "book->publish as..." function to publish your book to Gitbook, but only if you have to create it on the Gitbook website.

You can also use Git to create and upload your book by using Gitbook's help:

Touch Readme.md summary.md
Git init
git add readme.md summary.md
Git commit-m "First commit"
git remote add Gitbook https://push.gitbook.io/blackanger/test.git
git push-u gitbook Master
... or push an existing repository from the command line

git remote add Gitbook https://push.gitbook.io/blackanger/test.git
git push-u gitbook Master

You can also use the Editor's preview website feature locally to generate a static web page in the local _books directory, which is the web version of the book. Earlier versions of the Gitbook Editor can generate EPUB, PDF, and Mobi-formatted files directly locally, but the latest version removes these features.

Use Gitbook to write your own API documentation

Gitbook write his own book is very convenient, I also released a period of time a free book "Chef's Way." Actually you use Gitbook not only can write the book, also can write the API document, I have been using Gitbook to write the API document, I summed up several advantages:

• Gitbook can create private libraries for free, with high privacy.
• Similar to GitHub, there is version control. is an ebook version of GitHub.
• Gitbook Editor is a very useful markdown editor, there are a lot of thoughtful shortcut keys let you explore, such as cmd+shift+d, if you use the custom atom, Sublime, textmate and other editors, will like these features. Of course, this kind of shortcut keys are not many, but I believe that after the editor function will be more rich, because I just said this feature should also be added. At least it's much better than Logdown, the Markdown editor.
• Write one at a time and use it in multiple places. Next, let's focus on that, which is what I'm going to say today.

Write one at a time and use it in multiple places.

Now is the mobile internet era, many apps have been developed in the maintenance, there are a lot of apps to be developed, and the development of HTML5, JS MVC framework, a lot of people are maintaining the API interface. How important it is to write an interface document that is maintainable, readable, versioned, and freely distributed.

Readability/maintainable/versioning

Gitbook is written in markdown, also supports syntax highlighting, and uses it to write documents that look quite enjoyable.

Gitbook is born with version control, you can choose any version you have published.

can be distributed freely

1. After the document is written, you can copy all the files under the Gitbook source directory to your project (App_root/docs/api/gitbook_api_dir). In this way, your project will have a beautiful document, and developers can also open Web preview locally to generate a static web page in the _book directory to see your API interface document. If you think the copy is too earthy, you can create the API document directory for Gitbook editor directly in the project.

2. Background interface items, Android app projects, IOS app projects can all be distributed, and you can use Gitbook editor to co-manage interfaces.

3. Upload to GitHub, or you can edit your documents online, because GitHub also supports markdown.

Isn't it very convenient?

Update: Just after I finished writing this article, I found out that Gitbook has added a pay plan, and that free private projects allow only one to be created.

Transferred from: http://tao.logdown.com/posts/243192-use-gitbook-to-write-api-documentation

Use Gitbook to write your API documentation