2. Markdown Snippets

From version 1.5, SnippetsLab supports previewing Markdown snippets.

To use the Markdown feature, the language of the snippet must be set to “Markdown” first. To do this, click on the language selector located at the bottom left of the editor panel, and choose Markdown from the pop-up menu.

2.1. Enable Markdown Preview

There are three ways to toggle markdown preview:

  • Choose Editor > Enable Markdown Preview from the main menu

  • Click eye button on the top right while editing a markdown snippet

  • Press the keyboard shortcut Command-Shift-M

There are two preview modes available: full preview, and side-by-side preview. To switch between them, either click on the eye button and hold until a pop-up menu appears, or choose an option from the Editor menu.

In side-by-side preview mode, SnippetsLab supports scroll sync, where one pane will automatically scroll to an appropriate position following the other, so the same part of the document is shown. If you want the sync to be one-way only—such that the preview will follow the snippet, but not the other way around—you can do so by disabling Two-Way Sync from the Editor menu.

shadow

2.2. Markdown Features

2.2.1. Quick Formatting

When editing a markdown snippet, you can toggle a variety of formatting options from the Format menu. Common keyboard shortcuts are supported, including Command-B for strong, Command-I for emphasize, Command-` for Code, Option-Command-1~6 for headings level 1-6, and so on.

The Format menu also provides convenient access to common markdown structures, such as link, image, table, footnote, table of content, horizontal rule, and so on. SnippetsLab knows the syntax for them—so you don’t have to.

2.2.2. Syntax Highlighted Code Blocks

Markdown preview supports the same wide range of languages available in the app as ordinary snippets. The preview will guess the most appropriate language, but you may have to provide a hint in order for it to produce the best result. To specify a language explicitly with the fenced code block style, just type the language alias after the opening back-ticks. For example:

```ruby
def robot_invasion
   puts("robot " * 1000)
end
```

In case you are not sure what alias to use, you can alternatively insert the code block by right-clicking on the editor and choosing Insert Markdown Code Block, then select the desired language. Please note that only Active Languages will be included in this menu. If you would like to disable syntax highlighting for a specific code block, use the text alias.

Please note that while both the fenced style and indented style code blocks are supported by SnippetsLab, you can only specify additional options such as language with the fenced code block style.

Highlight lines

You can set specific lines to be highlighted using the hl_lines option. The value can be a single line number, a range, of a combination of both separated by a single space character. Some examples include hl_lines="1", hl_lines="1 3 5", and hl_lines="1 3-5".

```swift hl_lines="2"
import foo
import bar
import baz
```

Include line numbers

You can enable line numbers in the preview by using the linenums option. The value determines the starting line number. For example:

```swift linenums="1"
import foo
import bar
import baz
```

2.2.3. Table of Contents

You can include an interactive, auto-updating table of contents in the preview. To use this feature, you must explicitly include [TOC] in your markdown snippet. Although technically this marker can be placed anywhere, it’s recommended that it be put in the beginning of the markdown snippet for the best result.

shadow

Important

The marker is case-sensitive, so [toc] will not work.

2.2.4. MathJax

SnippetsLab 1.7 introduces MathJax support which allows you to write and preview math formulas written in LaTeX.

To write inline formulas, use $..$ as the delimiters. To write multiline formulas, use $$..$$ as the delimiters. For example, the following snippet:

The **gamma function** is defined for all complex numbers except the non-positive integers. For any positive integer $n$, $\Gamma(n) = (n-1)!\quad$.

Derived by Daniel Bernoulli, for complex numbers with a positive real part, the gamma function is defined via a convergent improper integral:

$$\Gamma(z) = \int_0^\infty x^{z-1} e^{-x}\,dx, \ \qquad \Re(z) > 0\ .$$

The notation $\Gamma (z)$ is due to Legendre. If the real part of the complex number $z$ is strictly positive ($\Re (z)>0$), then the integral converges absolutely, and is known as the Euler integral of the second kind. Using integration by parts, one sees that:

$$
\begin{aligned}
   \Gamma(z+1) & = \int_0^\infty x^{z} e^{-x} \, dx \\
&= \Bigl[-x^z e^{-x}\Bigr]_0^\infty + \int_0^\infty z x^{z-1} e^{-x}\, dx \\
&= \lim_{x\to \infty}\left(-x^z e^{-x}\right) - \left(-0^z e^{-0}\right) + z\int_0^\infty x^{z-1} e^{-x}\, dx.
\end{aligned}
$$

Would produce the result shown below:

shadow

Due to compatibility reasons, there must be no spaces immediately next to the $ inline delimiters. For example, $x$ will work, while $ x $ will not (in this case the dollar sign will be treated as a normal character).

Please note that MathJax syntax may be different from popular TeX or LaTeX builds. For details about MathJax syntax, please refer to official documentation.

2.2.5. Mermaid Diagrams

SnippetsLab 2.1 and above adds support for Mermaid, a library for creating various diagrams and visualizations with source code. Some popular diagram types include:

  • Flowcharts

  • Sequence diagrams

  • Class diagrams

  • Entity relationship diagrams

  • State diagrams

To insert a Mermaid diagram, surround the diagram code with the ```diagram marker. You can also choose Format > Diagram from the menubar to quickly insert the required boilerplate code.

shadow

To learn more about the syntax, please refer to official Mermaid documentations.

Please note that although all Mermaid diagram types can be used, not all diagrams are equally practical given the extent they are implemented. Specifically, some diagrams (such as the git graph and gantt charts) may have scaling issues as they can easily become too wide.

2.3. Markdown Preview Themes

Choose SnippetsLab > Preferences… from the main menu, then select Markdown tab. From here, you can choose and customize the markdown preview themes. These preview themes are, in fact, just CSS stylesheets applied to the resulting HTML document. There are four pre-installed themes: Bootstrap 3, GitHub, Vector, and New York.

The markdown preview themes are designed to work in conjunction with the main application themes. Specifically, various theme-specific styles, including syntax highlighting styles for code blocks, will be automatically applied by SnippetsLab on top of the selected markdown theme.

  • Edit a theme: Click on the theme you want to edit and edit it directly in the code editor (you can also use your favorite text editor to edit the CSS code and paste the code back into the editor). Changes are reflected in real-time. When finished, click the Apply button to apply your changes. You can also click the Revert button to undo all the changes since the last save.

  • Add or remove a theme: Click plus button to add a new theme. Click minus button to delete the selected theme.

  • Reset all themes: Click gearshape.fill button and choose Reset All… to reset all themes. This will delete all your custom themes and restore pre-installed themes.

  • Import or export a theme: Click gearshape.fill button and choose Import or Export. Themes can be exported to and import from a CSS stylesheet.

Tip

If you want to customize the CSS but are unsure what selectors to use, the best way to find out is to right-click on the markdown preview window, and choose Inspect Element.