docs/README.md

   1 # SGN Documentation
   2 [**View the documentation**](http://solgenomics.github.io/sgn/)
   3
   4 ### Syntax and Use
   5 The documentation is written in [kramdown-flavored](https://kramdown.gettalong.org/) markdown. It also takes advantage of the [Liquid](https://shopify.github.io/liquid/) templating system and the built-in variable in [Jekyll](https://jekyllrb.com), the static site generator that GitHub pages uses.
   6
   7 This folder (`docs/`) can be used to build the site either via GitHUb pages or via a local Jekyll installation.
   8
   9 ### Guidelines for adding to the documentation
  10
  11 #### Headers
  12 ```markdown
  13 Header 1 OR
  14 ===========
  15
  16 # Header 1
  17
  18 Header 2 OR
  19 -----------
  20
  21 ## Header 2
  22
  23 ### Header 3
  24
  25 #### Header 4
  26
  27 ##### Header 5
  28
  29 ###### Header 6
  30 ```
  31 You probably shouldnt use h1 headers, as the title of the page is always displayed as an h1, and using them elsewhere could be visualy confusing.
  32
  33 **DONT USE BOLD INSTEAD OF HEADERS** (except in tables). Doing so makes generating a TOC impossible (and also visually looks off.)
  34
  35 #### Horizontal Rules (Section Seperators)
  36
  37 In kramdown, a horizontal rule must be preceeded and followed by a blank line:
  38 ```markdown
  39 I am above the hr
  40
  41 -----------------
  42
  43 I am below the hr
  44 ```
  45
  46 #### Images/Screenshots
  47
  48 _For screenshots_: try to make sure that the image is of an unbranded version of the db.
  49
  50 To insert an image, we need to tell Jekyll to generate the relative path to the file like so
  51 ```markdown
  52 ![YOUR ALT TEXT]({{'assets/images/YOURIMAGE.png' | relative_url }})
  53 ```
  54
  55 #### Links
  56 To insert an link to something outside of the docs, we can use the usual markdown format:
  57 ```markdown
  58 [LINK TEXT](http://your.link)
  59 ```
  60 If you want to link to a docs page, use this syntax. Note that we put the **path to the file** (from the `docs` directory), **not the rendered HTML page**, after `link`.):
  61 ```markdown
  62 [LINK TEXT]({{ site.baseurl }}{% link your_folder/YOUR_FILE.md %})
  63 ```
  64 If you want to link to a header on a docs page, we can extend the syntax above like so:
  65 First, we assign the header we are linking to an ID:
  66 ```markdown
  67 ### I am the header {#your-header-id}
  68 ```
  69 then, we add that ID to the link:
  70 ```markdown
  71 [LINK TEXT](#your-header-id) <!-- On the same page-->
  72 [LINK TEXT]({{ site.baseurl }}{% link YOUR_FILE.md %}#your-header-id)
  73 ```
  74
  75 ### Creating New Pages
  76 **Every page should start with this YAML "front-matter" before anything else:**
  77 ```markdown
  78 ---
  79 title: "YOUR PAGE TITLE HERE"
  80 layout: doc_page
  81 ---
  82 ```
  83 **To insert a table of contents to a page with the following snippet (INCLUDING the comments [excluding them will cause the TOC to be indexed for search and not be readable by the TOC generator of folder pages.]):**
  84 ```markdown
  85 <!-- TOC-START -->
  86 * TOC
  87 {:toc}
  88 <!-- TOC-END -->
  89 ```