Technical Guide

Tips for contributing new content:

• Format your content in markdown (the theme uses the kramdown flavour), and place your markdown file within the pages folder. Please check out the project tree for any file referenced below.

• If you have been working with Google docs, then the GD2md-html Google Docs add-on can convert the content to kramdown efficiently.

• Append appropriate frontmatter to the top of your markdown. You can simply copy-paste from this file template_sop.md as a starter.

• For the tags to work, you still need to define them in _data/tags.yml file. Additionally, you need to create corresponding markdown pages in pages/tags with the tag name and other details as per the existing examples.

• For the sidebar, it should refer to a file of the intended table of contents found in the directory _data/sidebars. An example file is provided sops_sidebar.yml. Simply, put the name of this file in your frontmatter for it to work. For more information about the sidebar format, refer to this guide and this one.

• For top navigation, simply edit the file: _data/topnav.yml

• For linking to external sites, simply format your text and link as follows: [text to be linked](actual link). If you wish to link to a page within your own site, simply replace the actual link with the permalink of your desired page. However, you may find it optimal to use the complete path along with liquid link tag to have Jekyll inernally check your links before your site is deployed. You may refer to this entry from the official Jekyll site for more details on the later case.

• It is desirable to have a hover-over tooltip helpers next to key abbreviations or terms in each SOP. The convention here is to put such content at the end of a given SOP file, and start the section with [\\]:. Next, put each term in tits own line as in: *[term]: explanation. Again, the template page has some examples.

• References are included as footnotes in this site. In markdown, this means using a [^label] for inline citations, and [^label]: complete citation details in Vancuver style? for biblography. Note that the label does not need to be numeric, as this will be done automatically by the engine.

• For a better user experience, aim for shorter page length within the site. The helper scripts: scripts/split_by_h2.sh and scripts/split_by_h3.sh split up a properly formatted markdown page by level 2 and level 3 respectively, and I typically use them in this orderd. For example,This lengthy page was split up into its level 2 then level 3 headings in those pages.

• Splitting lenghty pages as per the previous tip makes it easier to create workflow maps in your page. Now, you only need 2 things:

  1. Modify the boxes that are to appear in your page by copying and then modifying the contents of this map file. You are only limited to 5 boxes in this simple design. For more complex maps (or more details, please refer to the original documentation theme guide.

  2. In your intended page, add the following lines to your front matter:

     simple_map: true
     map_name: usermap  // this is the name of your map file 
     box_number: 1      // this is the order of the box in your map
     

• To insert special boxes to your page: warning, note, tip, info, … etc, you may use the following divs in your markdown:

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.