GitBook is a platform that you can use to create documentation pages or company wikis. You can use it to document all sorts of things, from code to APIs and usage of a software product.
GitBook uses a process similar to GitHub repositories. The main copy of the documentation acts as the “master” copy. You can then create “drafts” that resemble “branches”.
This process allows many users to work on a single documentation site while also handling or preventing conflicts. It also allows changes from different branches to go through a review process before you merge them.
How to start using GitBook
You can choose from several GitBook pricing plans. Pricing depends on whether you use GitBook for open source projects, personal use, or private team collaboration. GitBook is free to use if you use it for open source projects.
GitBook supports Markdown, a popular markup language with many advantages for writing or documenting on the web.
GitBook also integrates with GitHub, a platform for hosting, storing, and editing code. You can directly link your GitBook account to your GitHub account by logging in with your GitHub credentials.
- Sign in to GitBook. If you have your own GitHub account, you can click Sign in to GitHub.
- Once you’ve logged in, GitBook will redirect you to a new internal wiki. Also, your wiki will be prepopulated with some sample content.
An overview of the GitBook interface
GitBook has several features that you can use to create and modify your documentation page.
- In the top pane, you can create new drafts, view change history, or view other discussions or attachments.
- In the leftmost sidebar, you can create multiple panels. You can use separate areas for different projects to separate and organize your documentation areas. You can expand or collapse the sidebar.
- The left pane acts as a menu for the documentation page. You can view the pages within your documentation site and use them to create groups and nested pages. You can also navigate the website using the links provided.
- The bottom panel contains buttons that are critical to the version control process. You can add a name for your draft, merge a change, or submit the change for review.
How to create a new draft
You can create a new draft by creating a new change request and making changes to it.
- Click in the top pane change requests.
- In the new panel that appears on the right, click draft Tab. This will show you all your active drafts.
- From here you can click on an existing draft to open it. To create a new draft, click New change requestand wait for the page to load completely.
- Click in the lower pane Enter a subject. A window opens in which you can give the new draft a name. For example, New Page – How to set up the code base.
How to create pages and groups
Once you have a draft, you can start making changes to the documentation. GitBook saves your changes within the draft so they don’t affect the master copy. You can add pages and page groups from the left sidebar.
- Create a new page by clicking new page Link at the bottom of the sidebar and select New document page from the drop-down list. Alternatively, you can hover under an existing page and click the blue plus Button.
- To create a new page group, click new pageand select that New group Option from the drop-down list.
- You can rename the page by clicking and selecting the three dots next to the page or group Rename.
- Start adding content to populate your new page. You can add simple content like text or headings. GitBook also allows you to add other blocks of content such as images, file attachments, tables, tabs, or code snippets. There is also an option to add other integrations like YouTube embeds or Google Docs content.
- Click on that diff view Button at the bottom to view the differences between your draft and the original master documentation copy.
- When you’re done writing your content, you can click merge, Send and mergeor Submit for review.
How to create a link to the documentation page
You can access the share link from the top of GitBook. You must be outside of a draft and viewing the copy of the master documentation to view the link.
- By default, the visibility of your documentation page is “unlisted”. This means that you can access the documentation page via a private link and not via search engines. At the top, click the Not listed Button.
- Select your desired visibility settings from the drop-down list. Note that GitBook may lock certain visibility settings and you may need to upgrade to access them.
- Below the list of visibility settings is a link that you can share with other users who will be using your documentation site. Copy this link to share with others.
- Click below the link Link and domain settings. Here you can associate a custom domain name or change part of the URL. If you are using a custom domain, you can view the Gitbook documentation to configure your DNS correctly.
Create documentation with GitBook
With GitBook you can create and edit documentation pages or company wikis together. GitBook borrows concepts from GitHub like branching and merging to control a master copy and manage conflicts.
You can create a new draft to add custom changes to your documentation. Within the draft, you can make changes to the content and add new pages or groups of pages. After you’ve made your changes, you can either merge them or submit them for review.
If you create internal documentation for your Java code, you might want to explore Javadoc. With Javadoc you can automatically document your Java code.