Standard Operating Procedure - Markdown
Most recently edited by: Paul VanderWeele
Most recent edit date: Jan 19th, 2021
Edits were authorized by:
Table of Content
Purpose and Scope
Terms and Definitions
Usage
Syntax Guide
Purpose and Scope
The purpose of this procedure is to demonstrate how to use the Markdown syntax to enrich text to include bolding, italicizing, headers, tables, hyperlinks, and other formatting features without the bulk and complexity of a XML-style document like Office 365's Word Processor. Markdown is used to format the documentation on the NAL Documentation Server.
Terms and Definitions
Raw Text
Raw Text is computer encoded bits that correspond with human readable characters only. These characters can be from any language, and can represent numerals, punctuation, or whitespace.
Raw Text File
A Raw Text File is a indexed file on an operating system consisting of only raw text like a .txt, .csv, or .md file. This excludes XML-based documents like Microsoft Word's .Doc and .Docx formats.
Local IP Address
A Local IP Address is a number correlated by the office router to correspond with the MAC Address of a computer on the local network.
Usage
Adding Markdown
Adding Markdown syntax to text is very straight-forward as the formatting is text itself. Markdown is kept as raw text in files with a .md extension indicating it is a Markdown file. Markdown files can be created or edited in almost any raw text editor like Notepad or Atom, and should contain ONLY Markdown content.
From Markdown to HTML.
However, without another program, the text does not actually look formatted. An extension exists for Atom that allows it to display formatted Markdown within the editor; however this is primarily useful only for personnel that are editing documents. The published and controlled version of the document is rendered using an interpreting program. We use the interpretter MkDocs to convert the Markdown syntax into HTML. The formatting web documents are then served on the NAL Documentation Server's local IP address using NGINX.
Version Control
Because Markdown files are raw text, every bit of information can be broken down into rows and columns. We use the version control system Git to keep track of each change made to Markdown files including exactly which rows and columns were edited, what changes were made, who changed them, what date/time changes were commited, and notes about each change.
Syntax Guide
Headers
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
Emphasis
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
_You **can** combine them_
*You __can__ combine them*
Lists
Unordered
* Item 1
* Item 2
* Item 2a
* Item 2b
Ordered
1. Item 1
1. Item 2
1. Item 3
1. Item 3a
1. Item 3b
Images
Format: 
Links
https://newagelaboratories.com -- automatically makes link
[NEWAGE Labs](https://newagelaboratories.com) -- Use [text](url) format to replace text.
Blockquotes
As we mentioned in our previous email:
> This was a waste of time
> and we are not at fault.
Code
Inline
Use the `SUM()` command in Excel to add two numbers.
Blocks
To write this syntax guide, we used code blocks like this:
## Headers
```{.md}
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
```
The 3 backticks ``` indicate the beginning and end of the code block.
Additional backticks may be used. This allows ``` to be typed within the code block.
Optionally, a language can be specified on the first line.
Use the {} notation to indicate a language besides the default (Python).
Additional Reference
Additional information can be found on Github's guide to Markdown Syntax