dpFM Markdown Cheat Sheet

Markdown Resources

dpSlate uses a version of Markdown, specifically called dpSlate Flavored Markdown or dpFM. This is a version of standard Markdown that has been extended to encompass the needs of technical documentation through the use of YML directives.

If you are unfamiliar with standard Markdown, below are some helpful resources to help you get started.

dpFM Markdown Extensions

Alerts

Technical documents often have alerts which are warnings and notes that are intended for the reader. Although standard markdown does not support this concept, dpSlate has been extended to support Alerts. You can add warnings and notes with few characters within the Markdown.

=> This is a success message.
-> This is an info or note message.
~> This is a warning message.
!> This is a danger message.

Results

Code Blocks

Code samples are an important way of communicating lines of code. dpSlate utilizes a syntax highlighter (highlightjs.org to display the code using the proper highlighting. When you have a code block inside of your Markdown, you can specify the code's name and the syntax highlighter will apply the appropriate highlighting. This value is also used to determine which code is displayed when a language tab is selected, explained here.

  ```java
  Some Java code here

When you create a code block, you can specify more than one language. For example, you can specify ruby,python (without space breaks). This tells the processor that the sample code should be placed in both the ruby and the python tabs.

Languages for Highlighting

The code that appears in a code block will be highlighted using the syntax rules for the specified language. If you specify more than one language in your code block, the first one will be used. Additionally, you can override syntax highlighting by placing nohighlighting as if it was a language in your string. For example, python,nohighlighting would normally highlight the code using python syntax rules, but because you also specified nohighlighting it will turn off the highlighting. This is useful when you don't want any highlighting but you want to specify which tabs that the code sample will be place into.

Includes

There are times in which you'd like to break a Markdown file into multiple parts and reuse the parts in different documents. Although standard markdown does not support the concept of Includes, dpSlate markdown has been extended to provide this support. Anywhere within the markdown, you can add the contents of another file by using markdown include using two open curly brackets ({{), followed by the file's path, and close with two curly brackets (}}). The Markdown statement must be at the start of a new line and of the form {{filepath/filename.ext}}. Below is an example of using includes within your document.

 {{ /site/content/dpfm/_example.md }}

In the example, the includes is a file called _example.md.

It is highly recommended that your included Markdown files have a file name that begins with an _ (underscore). This is because the dpSlate conversion process does not generate separate HTML files for filenames that begin with a _. This will prevent the includes files from being created as it's own stand-alone page.

Mathematics

Tex and LaTex are a format for expressing mathematics that is a standard used by Mathematicians and Computer Scientists. LaTex is a variant of Tex and it has become the dominate flavor of Tex in use as it is more streamlined. dpSlate uses Tex/LaTex via the MathJax library developed and provided by the American Mathematical Society.

Sometimes, markdown processors have problems with _ because markdown uses them to detect italics while Tex/LaTex uses it to denote an underscore. For example:

\[ x_1 = 132, x_2 = 370 \]

However, as you can see, dpSlate has been modified to ignore the underscores inside a Mathematics expression. The above example was done with the code \\[ x_1 = 132, x_2 = 370 \\].

dpSlate includes support for typeset quality Mathematics using either Tex or LaTex. There are two ways that you can display Mathematics.

Inline - these are mathematical expressions that are shown within the paragraph and you include the Tex/LaTex express between the delimiters of \\(...\\).
Display - these are mathematical expressions that are displayed in their own paragaph you include the Tex/LaTex express between the delimiters of \\[...\\]

For example, if there are two solutions to \(ax^2 + bx + c = 0\), they are \[x = {-b \pm \sqrt{b^2-4ac} \over 2a}\]

or the second example to the right will yield:

\[ \frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x)\]


\\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\]

\\[ \frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x)\\]

HTML in Markdown

You can also use raw HTML in your Markdown and most of it will work. One of the features of Markdown is that you don't have to worry about the formatting details of HTML. Also, it provides a separation of content and format which you lose when you start placing HTML into your Markdown.