Markdown

Supported formatting

Doc bodies are Markdown (CommonMark and GitHub-flavored): headings, lists, tables, fenced code, links and images, plus the :::note, :::warning, :::tip, :::accordion and :::video blocks. A few things are refused, with the line number and how to fix it: raw HTML, task-list checkboxes (write a plain list), footnotes (put the note in the sentence), link hover titles (delete the quoted title), and headings that run over more than one line. In a table cell, write a | as \|. A ::: block starts and ends at the beginning of its own line.

For example:

## Before you begin

Connect a repository under **Settings > Integrations > GitHub**.

- Choose the repositories Teaflask may read.
- Check each repository's production branch.

See [GitHub](/github) for setup.

URLs with an explicit scheme, www. addresses, and email addresses can become links automatically. A bare domain such as example.io stays plain text.

Raw HTML is not accepted as page markup. An invalid body is refused on save with a message identifying the problem. HTML inside a code block is allowed as an example. Doc bodies do not support MDX components, imports, or executable expressions.

Visual editing and source editing

The visual editor supports a subset of valid Markdown and requires the stored formatting to survive a read-and-save cycle unchanged. If it would rewrite the Markdown, Teaflask uses Markdown source editing instead.

This can happen with ordinary formatting differences, such as table spacing or alternative link spellings, not just unusual content. Images are valid stored content but currently require source editing. They still render in Preview and on the help center.

The slash menu's block choices are not the full Markdown grammar. For example, headings through level six and horizontal rules are supported even though they are not all slash-menu entries.

See Editing for the editor controls.

Callouts

Use note, warning, or tip to draw attention to a short passage. Put the opening and closing markers on their own lines:

:::note
You can edit a draft without changing the released page.
:::

:::warning
Rotating the identity secret invalidates tokens signed with the old secret.
:::

:::tip
Use Preview to check a table before releasing the doc.
:::

Callout bodies can contain Markdown. Keep the opening line to the directive name.

Accordions

An accordion needs a summary on its opening line. The body appears when the reader expands it:

:::accordion Where can I find receipts?
Open **Settings > Billing**, then choose **Billing history & receipts**.
:::

The summary is plain text, not a heading. It does not receive its own heading anchor.

Video embeds

A video directive contains one absolute HTTP or HTTPS URL on its opening line and no body:

:::video https://www.youtube.com/embed/aqz-KE-bpKQ
:::

Use an embeddable URL from a provider you trust. The destination must allow embedding; a normal watch-page URL may not work. The embed loads content from that external address.

Place and nest directives

Write directives as standalone blocks, not inside list items or blockquotes. Close each block explicitly.

To nest a directive inside another, use more colons for the outer block:

::::accordion Before you release
Review the draft in Preview.

:::warning
Releasing a shown doc on a live help center changes the public page.
:::
::::

The supported names are note, warning, tip, accordion, and video. A directive example inside a code fence is displayed as code rather than opened as a block.

Heading links and search sections

Rendered headings receive anchors derived from their text. Duplicate heading names receive numbered suffixes. Renaming a heading or changing the order of duplicates can therefore change links to those sections.

Top-level headings also divide the document into sections used by documentation search. Headings inside callouts or accordions retain their rendered anchors but stay within the surrounding search section. An accordion summary does not start a section.

If the body starts with a level-one heading that exactly repeats the doc's title, Teaflask omits that duplicate heading from the reader view. It remains in the stored Markdown.

Read a public page as Markdown

Append .md to a help-center page's address to retrieve its released Markdown. For example, /billing.md is the Markdown form of /billing on your docs domain.

This serves the stored body without converting it from HTML. On an active custom docs domain, the HTML page also advertises the Markdown address for clients that support that discovery.

The Markdown version follows the same content-access rules: the doc must be released, shown on the help center, and served by a live site. It is not a way to retrieve drafts or hidden docs. See Organizing.