Shulou(Shulou.com)06/02 Report--

This article mainly explains "how to use gitbook to write Api documents," interested friends may wish to take a look. The method introduced in this paper is simple, fast and practical. Let Xiaobian take you to learn "how to use gitbook to write Api documents"!

Use of Gitbook

When you use Gitbook, when you create a new project, the following options will pop up. There are four types of templates available to you to choose from. In fact, they are no different, just a Markdown template:

We chose the first option, and of course, for those of you who are trying it for the first time, you can choose to look at different Markdown templates.

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

SUMMARY.md This file is the directory structure of the book. Gitbook Editor does not support Chinese very well. Sometimes you create a chapter with Editor and name it in Chinese, but when you click on the new chapter, an error will be reported. The solution is to open the file with your own editor and edit it directly.

Specific Editor how to get started, I will not say in detail, I believe you will use Markdown editor will use Editor.

When you create a book, you can go to "Book->Publish As..." function to publish your book to Gitbook, but only if you create the book on the Gitbook website accordingly.

You can also use Git to create and upload your book with the help of Gitbook:

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 Editor's Preview Website function locally to generate static web pages, i.e., Web versions of books, in your local_books directory. Earlier versions of Gitbook Editor could generate files in epub, pdf, and mobi formats directly locally, but the latest version removes these features.

Write your own Api documentation using Gitbook

Gitbook is very convenient to write your own book. I also released a free book called Chef's Way some time ago. In fact, you can use Gitbook not only to write books, but also to write Api documents. I have always used Gitbook to write Api documents. I have summarized several advantages:

Gitbook allows you to create private libraries for free, with high confidentiality.

Similar to Github, there is version control. It's an e-book version of Github.

Gitbook Editor is a good Markdown editor, there are a lot of thoughtful shortcuts for you to discover, such as cmd+shift+d, if you are used to Atom, Sublime, Textmate and other editors, you will like these features. Of course, there are not many such shortcut keys, but I believe that the Editor function will be richer in the future, because the feature I just mentioned should also be added. At least it's better than Logdown, the Markdown editor.

Write once, use in many places. So let's focus on that, and that's what I'm going to focus on today.

Write once, use in many places.

Now is the era of mobile Internet, many apps have been developed in maintenance, there are still a lot of apps to be developed, and HTML5, js mvc framework development, there are many people in maintenance Api interface. So how important is it to write a maintainable, readable, version-controlled, freely distributable interface document?

Readability/Maintainability/Version Control

Gitbook is written in Markdown, and also supports syntax highlighting, etc. The documents written in it look quite pleasant, see the example below.

Gitbook comes with version control, so you can choose any version you've ever released.

can be distributed at will.

Once the documentation is written, you can copy all the files from the Gitbook source directory to your project (app_root/docs/api/gitbook_api_dir). In this way, your project has a beautiful document, developers can also open Web Preview locally to generate static web pages in the_book directory to enjoy looking at your API documentation. If copying is too corny, you can create the Gitbook Editor's Api documentation directory directly into your project.

Background interface projects, Android App projects, iOS App projects can all be distributed one copy, you can use Gitbook Editor to collaboratively manage the interface.

Upload to Github, and you can also modify and read your documents online, because Github also supports Markdown.

Is that convenient?

At this point, I believe that we have a deeper understanding of "how to use gitbook to write Api documents," may wish to actually operate it! Here is the website, more related content can enter the relevant channels for inquiry, pay attention to us, continue to learn!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.