How to use this template for your documentation
Chapter Outline
How to start
Creating your repository
This template is created to help you develop and maintain your documentation on GitHub platform. We use GitHub Pages for C++ Toolkit documentation and for this template.
To start your project on GitHub you have to create a repository. All NCBI repositories must reside under GitHub NCBI organization https://github.com/ncbi. To create a repository you need to create a JIRA ticket in OSS project. You will have to provide them with the name for your repository. This name will be part of URL of your GitHub website. You can find the information about GitHub Pages here.
You also have to ask NCBI GitHub support group to give admin permissions to a person or group of persons that will administer your repository. This person(s) will administer your site, give permissions to other contributors, review and merge pull requests, etc.
You can read about GitHub permissions here.
The result of this request should be an empty GitHub repository located here: https://github.com/ncbi/
Creating your site
Now, you have to clone our template into your empty repository. We have created a script that will do this and some other steps that are necessary to start your project.
This script:
- clones this template into your empty repository
- replaces /ncbi_doc_template/ (the name of template repository) in files with the name of your repository
- commits updated files to your new repository
- publishes the repository
Click here to download the init.sh script.
Save it to your working directory on Linux and run there the command as follows:
$ ./init.sh <your_repository_name>
To check whether it is published on web go to:
https://github.com/ncbi/<your_repository_name>/settings
Scroll down to ‘GitHub Pages’ section. If everything is fine, you should see a message that your site is successfully published. Click the link to see the published site.
Editing your site
After the original set up is complete, you can now customize the template for your needs. The structure of the template is described below.
About this template
This template is based on C++ Toolkit documentation. It consists of several blocks:
- Header
- Sidebar
- Footer
- Content
- Help page
You can customize any of these blocks. The footer might not need to be customized/updated because it is a standard NCBI footer.
HTML files for header, sidebar, and footer are located in ncbi_doc_template/_includes/ directory. We use static site generator Jekyll to render your GitHub pages. Header, sidebar, and footer are parts of page template, i.e. they will be displayed on each of your GitHub page.
The content consists of your parts and chapters. All content files are located in ncbi_doc_template/pages/ directory.
How to edit the parts of the template
- Editing the content.
To edit the content (chapters), click ‘Edit’ button at the top right corner of each chapter.
You can also use this URL to reach any of your files:
https://github.com/ncbi/<your_repository_name>/edit/gh-pages/<path_to_your_file>
Indexing your GitHub site with Google.
In order to enable Google search on your site, you can use Google sitemaps. Follow the steps on how to build and submit Google sitemaps here. There are also samples of sitemap (sitemap_000.xml), google759adab84e4ed1fd.html, and robots.txt files in the template’s root directory. You should replace them with your customized files when you set up your own Google indexing or remove them if you will use some other type of indexing.