Markdown syntax

Pages are stored as Markdown. You never have to write it by hand, because the editor does it for you. But you can, and it is the format used when you import content, copy a page or work with an AI assistant.

#Standard Markdown

GitRead supports GitHub flavoured Markdown:

#Extensions

GitRead adds a few blocks that are written as tags in curly braces with percent signs.

#Hints

Hints are call-out boxes in the styles info, success, warning and danger. They are written with a hint tag that has a style attribute and wraps the text. Unknown styles fall back to info.

The easiest way to create a hint is the Hint block of the editor. Use the same tag syntax when you write Markdown for an AI assistant or import it.

#Code with a title and line numbers

A code tag wraps a fenced code block and adds a title above it and optional line numbers (lineNumbers="true"). Both are optional. In the editor, use the With caption and With line numbers options of the code block.

#Buttons

{% button href="https://example.com" style="primary" %}Get started{% endbutton %}

The style is primary or secondary. Buttons on consecutive lines are grouped in a row. Only safe link targets are allowed. Unsafe ones such as javascript: are replaced by an empty link.

#Link cards

{% link href="https://example.com" title="Example" sub="example.com" %}
{% link href="page:42" %}

A link card shows a title, an optional subtitle and an icon. Use page: followed by the number of a page of the same project to link to it. The page number is part of the page's public address. Use icon with an image address to set the icon.

#Diagrams

Use a fenced code block with the language mermaid to draw a diagram.

```mermaid
flowchart LR
    Write --> Review --> Publish
```

#Safe by default

Raw HTML in Markdown is removed, and links with unsafe targets are blocked. If you need something that the editor or the syntax above does not provide, use a link card or button to point to it.

#Headings and the table of contents

Headings of level 2 and 3 appear in the On this page table of contents. Each one gets an anchor you can link to, for example #hints.