Sidebar

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 based on GitHub platform. We use GitHub Pages for C++ Toolkit documentation.

To start your project on GitHub you have to create a repository. All NCBI repositories must be reside under GitHub NCBI organisation https://github.com/ncbi. To create a repository you need to submit a request to github-tools@ncbi.nlm.nih.gov. 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 administrate your repository. This person(s) will administrate 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 GitHub repository located here: https://github.com/ncbi/

Cloning the template

The next step is cloning this template.

  1. Clone Template repository to create a local copy on your computer. Run:
$ git clone https://github.com/vserova/template.git -d <your_repository_name>

The result of this command will be a directory named with template files.

You can read about cloning GitHub repositories here.

  1. Run:
$ ./init.sh <your_repository_name>

This script replaces /template/ (the name of template repository) in files with the name of your repository. Now your repository is ready to be published.

  1. Publish your repository.

Run this in your terminal:

$ git init
$ git add --all
$ git commit -m "Initial Commit"
$ git remote add origin https://github.com/ncbi/<your_repository_name>.git
$ git push -u origin master
  1. Check whether it is published on web. Go to:

https://github.com/ncbi//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.

Edit your site

After the original set up is complete, you can now edit your repository.

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 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 template/pages/ directory.

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) and robots.txt files in the template’s root directory.