2. Markdown Snippets

SnippetsLab supports Markdown with a live preview, formatting shortcuts, syntax-highlighted code blocks, math formulas with MathJax, and Mermaid diagrams. These features apply to snippets whose language is Markdown.

A Markdown note in preview, with a formula, a diagram, and code A Markdown note in preview, with a formula, a diagram, and code

2.1. Preview

  • To show or hide the preview: Choose Editor > Show Markdown Preview, click the eye button in the toolbar, or press Shift Command M.

  • To switch between full and side-by-side preview: Control-click, or click and hold, the eye button and choose a mode. For direct access to each mode, add the Preview Modes control to the toolbar.

  • Scroll sync: By default, the editor and the preview scroll together in side-by-side mode. To make scroll sync one-way or turn it off, choose an option from Editor > Sync Scroll.

  • Preview mode for each snippet: By default, the preview mode applies to all snippets. To remember the mode for each snippet, for example to keep finished snippets in full preview, go to Settings > Markdown > Options and select Remember the selected preview mode for each snippet.

2.2. Editing

  • Formatting shortcuts: Apply formatting with keyboard shortcuts or the Format menu. For example:

    • Command B for bold

    • Command I for emphasis

    • Command U for underline

    • Command ` for inline code

    • Option Command 1 through Option Command 6 for heading levels 1 through 6

    • Command K for links

    The Format menu also has commands for other Markdown elements, such as images, tables, and footnotes. For quick access to common formatting options, add the Format button to the toolbar.

  • Rich text styles in the editor: For easier reading, SnippetsLab applies rich text styles to Markdown source in the editor, for example to bold text and headings. To turn this off, go to Settings > Markdown > Options and deselect Use in-editor rich text styles.

  • Line breaks: By default, a single line break is a hard break, as on GitHub. To switch to CommonMark style and treat a single line break as a soft break, go to Settings > Markdown > Options and deselect Treat newlines as line breaks.

  • Smart symbols: To convert ASCII symbols such as (c) and --> to typographic symbols, go to Settings > Markdown > Options and select Smart symbols. For the full list of supported replacements, see the SmartSymbols documentation.

2.3. Code Blocks

Code blocks in the preview have full syntax highlighting, using the same color palette as the app theme. Specify a language alias after the opening fence to highlight the code:

```swift
import Foundation

print("Hello, World!")
```

Indented code blocks are also supported, but only fenced code blocks accept a language and the options below.

  • To find the alias for a language: Control-click in the editor and choose the language from the Insert Markdown Code Block submenu. The submenu includes only active languages.

  • To show line numbers: Use the linenums option with a starting line number, for example linenums="1".

    ```swift linenums="1"
import Foundation
import AppKit
import SwiftUI
```

  • To highlight specific lines: Use the hl_lines option with line numbers and ranges separated by spaces, for example hl_lines="1 3-5".

    ```swift hl_lines="2"
import Foundation
import AppKit
import SwiftUI
```

  • To turn off line wrapping in code blocks: Go to Settings > Markdown > Options and deselect Soft wrap code blocks.

  • To highlight code blocks without a language: Code blocks without a language aren’t highlighted by default. To have SnippetsLab guess the language, go to Settings > Markdown > Options and select Highlight code blocks without explicit languages.

  • To keep a code block plain: When Highlight code blocks without explicit languages is selected, use the text alias to turn off highlighting for that code block.

2.4. Alerts

You can use alerts (also known as callouts or admonitions) to call out important information. To create an alert, start a block quote with one of the alert type markers on its own line:

> [!NOTE]
> Background information that's useful to know.

> [!TIP]
> An optional way to do something better or faster.

> [!IMPORTANT]
> Information that's required to succeed.

> [!WARNING]
> A problem that needs attention right away.

> [!CAUTION]
> The risks of an action, such as losing data.

Each type of alert has its own color and icon in the preview. You can also change the title and type of an alert, or make it collapsible:

  • Custom titles: Add text after the marker to replace the default title, for example > [!WARNING] Back up first.

  • Custom types: Use any word as the type, for example > [!QUESTION]. The word becomes the title, such as “Question”, and the alert appears in a neutral style.

  • Collapsible alerts: Add - after the marker for an alert that starts collapsed, or + for one that starts expanded, for example > [!NOTE]-. Click the title to expand or collapse the alert.

2.5. Table of Contents

Add [TOC] to a snippet to show an interactive table of contents in the preview. For best results, put it at the start of the snippet.

2.6. LaTeX/MathJax

SnippetsLab supports LaTeX math formulas with MathJax, rendered with high-quality typography. Use $...$ for inline formulas and $$...$$ for block formulas. Avoid spaces directly inside the $ delimiters.

Highlights Review in Larkspur 2.3 brings saved highlights back on a schedule based on SM-2. After each review, the reader grades how well they remembered the highlight, from $q = 0$ (forgot) to $q = 5$ (easy).

## Interval

The $n$th review happens $I(n)$ days after the previous one:

$$
I(n) =
\begin{cases}
1 & n = 1 \\
6 & n = 2 \\
\lceil I(n-1) \cdot EF \rceil & n > 2
\end{cases}
$$

## Ease factor

Each highlight starts with $EF = 2.5$, updated after every review:

$$
EF' = \max\Bigl(1.3,\; EF + 0.1 - (5 - q)\bigl(0.08 + 0.02\,(5 - q)\bigr)\Bigr)
$$

A grade below 3 resets $n$ to 1 but keeps the ease factor.
Math formulas in a Markdown preview Math formulas in a Markdown preview

For more information, see the official MathJax documentation.

2.7. Diagrams

SnippetsLab has built-in support for Mermaid, a popular library for creating diagrams and charts from text. Supported diagram types:

  • Block diagram

  • C4 diagram

  • Class diagram

  • Entity relationship diagram

  • Flowchart

  • Gantt chart

  • Git graph

  • Mindmap

  • Pie chart

  • Quadrant chart

  • Requirement diagram

  • Sankey diagram

  • Sequence diagram

  • State diagram

  • Timeline diagram

  • User journey diagram

  • XY chart

Put the diagram code in a code block marked ```mermaid or ```diagram. To quickly start from a template, choose a diagram type from Format > Diagram.

A Mermaid flowchart next to its Markdown code A Mermaid flowchart next to its Markdown code

For the syntax of each diagram type, see the official Mermaid documentation.

2.8. Preview Themes

To choose or customize the Markdown preview theme, go to Settings > Markdown > Theme. The background color, accent color, syntax highlighting colors, and alert colors of the app theme are applied to the preview theme automatically.

To create a theme, click the + button below the theme list. To start from an existing theme, click the gear button below the theme list and choose Duplicate. To share a theme or use one from elsewhere, choose Export or Import from the same menu. Themes are saved as CSS files.

To restore every included theme to its latest version, click the gear button and choose Reset All. This also deletes your custom themes, so export any theme that you want to keep first.

Tip

When writing CSS for a theme, Control-click the preview and choose Inspect Element to see the document structure and find the selectors you need.