GitBook is a platform for building documentation sites or enterprise wikis. You can use it to document all sorts of things, from code to APIs and how to use a software product.
GitBook uses a similar process to GitHub repositories. The main copy of the documentation acts as a “master” copy. You can then create “drafts”, which are similar to “branches”.
This process allows many users to work on a single documentation site while managing or preventing conflicts. It also allows changes from different branches to go through a review process before being merged.
How to start using GitBook
You can choose from several GitBook pricing plans. Pricing will depend on whether you are using GitBook for open source projects, personal use, or private team collaboration. GitBook is free if you use it for open source projects.
GitBook supports Markdown, a popular markup language that offers many benefits for writing or documenting on the web.
GitBook also integrates with GitHub, a code hosting, storage, and publishing platform. You can link your GitBook account directly to your GitHub account by logging in using your GitHub credentials.
- Sign up for GitBook. If you have your own GitHub account, you can click Sign up with GitHub.
- Once logged in, GitBook will redirect you to a new internal wiki. It will also pre-populate your wiki with sample content.
An overview of the GitBook interface
GitBook has several functions that allow you to build and make changes to your documentation site.
- The top panel lets you create new drafts, view edit history, or view other threads or attachments.
- The leftmost sidebar allows you to create multiple spaces. You can use separate spaces for different projects so you can separate and organize your documentation areas. You can expand or close the sidebar.
- The left panel serves as a menu for the documentation site. You can view the pages of your documentation site and use it to create groups and nested pages. You can also browse the site using the links provided.
- The bottom panel includes buttons essential to the version control process. You can add a name to your draft, merge an edit, or submit the edit 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.
- In the top panel, click Change requests.
- In the new panel that appears on the right side, click the Disorganized tongue. This will show you all of your active drafts.
- From there, you can click on an existing draft to open it. To create a new draft, click New change requestand wait for the page to finish loading.
- In the bottom panel, click Enter a subject. This will open a window where you can give the new draft a name. For instance, New page – How to configure Codebase.
How to create pages and groups
Once you have a draft, you can start making changes to the documentation. GitBook stores your changes in draft, so they don’t affect the master copy. You can use the left sidebar to add pages and page groups.
- Create a new page by clicking on the New page link at the bottom of the sidebar, and selecting New documents page from the drop-down menu. Alternatively, you can hover under an existing page and click the blue more button.
- To create a new page group, click New pageand select the New group option from the drop-down list.
- You can rename the page by clicking the three dots next to the page or group, and selecting Rename.
- Start adding content to populate your new page. You can add simple content such as text or headings. GitBook also lets you add other content blocks such as images, attachments, tables, tabs, or code snippets. It is also possible to add other integrations such as YouTube integrations or Google Docs content.
- Click on the Differential view in the bottom panel to view the differences between your draft and the original copy of the main documentation.
- Once you are done writing your content, you can click Merge, Submit and mergeWhere Submit for correction.
How to link to the documentation site
You can access the share link from the top panel of GitBook. You will need to be from a draft and view the copy of the main documentation to be able to view the link.
- By default, your documentation site visibility is “unlisted”. This means that you can access the documentation site using a private link, not through search engines. In the top panel, click the Unlisted button.
- Select the 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, there is a link that you can share with other users who will use your documentation site. Copy this link to share with others.
- Below the link, click Link and domain settings. This is where you can link a custom domain name or change part of the URL. If you’re using a custom domain, you can check out Gitbook’s documentation on how to properly configure your DNS.
Creating documentation using GitBook
GitBook allows you to create and work collaboratively on documentation sites or enterprise wikis. GitBook borrows concepts from GitHub like branches and merging to control a master copy and manage conflicts.
You can create a new draft to add your own individual changes to the documentation. In the draft, you can make changes to the content, as well as add new pages or page groups. Once you are done making your changes, you can either merge them or submit them for review.
If you create internal documentation for your Java code, you can explore Javadoc. Javadoc allows you to document your Java code automatically.