How to Create a Simple Internal Wiki Using Gitbook

GitBook is a platform that allows you to build documentation sites or company wikis. You can use it to document all kinds 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 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 will depend on whether you are using GitBook for open source projects, personal use, or private team collaboration. GitBook is free to use if you are using it for open source projects.

GitBook supports Markdown, a popular markup language with many benefits for writing or documenting on the web.

GitBook also integrates with GitHub, a platform for hosting, storing, and editing code. You can link your GitBook account directly to your GitHub account by signing in using your GitHub credentials.

1. Sign up to GitBook. If you have your own GitHub account, you can click on Sign Up With GitHub.

2. Once you have signed in, GitBook will redirect you to a new internal wiki. It will also pre-populate your wiki with some sample content.

An Overview of the GitBook Interface

GitBook has several functions that allow you to build and make changes to your documentation site.

1. The top panel allows you to create new drafts, view the change history, or view any other discussions or attachments.

2. The left-most sidebar allows you to create multiple spaces. You can use separate spaces for different projects so that you can separate and organize your documentation areas. You can expand or close the sidebar.

3. The left panel acts as a menu for the documentation site. You can view the pages within your documentation site, and use it to create groups and nested pages. You can also navigate across the site using the links provided.

4. The bottom panel includes buttons that are vital 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 within it.

1. In the top panel, click on Change Requests.

2. On the new panel that appears on the right-hand side, click on the Draft tab. This will show you all of your active drafts.

3. From here, you can click on an existing draft to open it. To create a new draft, click on New change request, and wait for the page to finish loading.
4. In the bottom panel, click on Enter a Subject. This will open a window where you can give the new draft a name. For example, New Page – How to Set Up Codebase.

How to Create Pages and Groups

Once you have a draft, you can start making changes to the documentation. GitBook stores your changes inside the draft, so they do not affect the master copy. You can use the left-hand sidebar to add pages and page groups.

1. Create a new page by clicking on the New Page link at the bottom of the sidebar, and selecting New document page from the dropdown. Alternatively, you can hover underneath an existing page and click on the blue plus button.

2. To create a new Page Group, click on New Page, and select the New group option from the dropdown.

3. You can rename the page by clicking on the three dots next to the page or group, and selecting Rename.

4. Start adding content to populate your new page. You can add simple content such as text or headings. GitBook also allows you to add other content blocks such as images, file attachments, tables, tabs, or code snippets. There’s also the option to add other integrations such as YouTube embeds or Google Docs content.

5. Click on the Diff view button in the bottom panel to view the differences between your draft and the original master documentation copy.

6. Once you have finished writing your content, you can click on Merge, Submit and merge, or Submit for review.

How to Create a Link to the Documentation Site

You can access the share link from the top panel of GitBook. You will need to be out of a draft and viewing the master documentation copy to be able to view the link.

1. By default, the visibility of your documentation site is “unlisted”. This means that you can access the documentation site using a private link, and not via search engines. In the top panel, click on the Unlisted button.
2. Select your desired visibility settings from the dropdown. Note that GitBook may lock certain visibility settings, and you may need to upgrade to access them.

3. Underneath the list of visibility settings, there is a link that you can share with other users who will be using your documentation site. Copy this link to share it with others.
4. Underneath the link, click on Link and domain settings. This is where you can link a custom domain name, or modify part of the URL. If you are using a custom domain, you can view Gitbook’s documentation on how to correctly configure your DNS.

Creating Documentation Using GitBook

GitBook allows you to collaboratively create and work on documentation sites or company wikis. GitBook borrows concepts from GitHub like branches and merging to control a master copy and manage any conflicts.

You can create a new draft to add your own individual changes to the documentation. Within the draft, you can make changes to the content, as well as add new pages or page groups. Once you have finished making your changes, you can either merge them or submit them for review.

If you are creating internal documentation for your Java code, you may want to explore Javadoc. Javadoc allows you to document your Java code automatically.