Writing and formatting guidelines

The living Markdown style guide for Fliplet documentation, with source examples and rendered output for every supported format.

This guide shows the Markdown authors write and the output readers see. The examples below were recovered from the original formatting guide.

How to use this guide

Each section includes a copyable Markdown source block followed by its Rendered output. The source is stored as article content in Versions.markdown; Pages identifies the article and its published revision. Older examples use the label Pages Markdown for the authoring field.

Review heading hierarchy, links, spacing, code presentation and accessibility before publishing. Every fenced code block must include a language identifier.

Paragraphs and inline emphasis

Use ordinary paragraphs for prose and reserve emphasis for words that need a reader’s attention.

Markdown source

Fliplet documentation favors short paragraphs with a clear subject and a useful next step.

Bold text marks a key term, italic text adds gentle emphasis, and bold italic text combines both treatments.

~~Strikethrough~~ is useful when documenting a retired option. Escaped characters such as \literal asterisks\ stay visible as text.

The divider above separates related editorial beats without introducing another heading.

Rendered output

Fliplet documentation favors short paragraphs with a clear subject and a useful next step.

Bold text marks a key term, italic text adds gentle emphasis, and bold italic text combines both treatments.

~~Strikethrough~~ is useful when documenting a retired option. Escaped characters such as \literal asterisks\ stay visible as text.

The divider above separates related editorial beats without introducing another heading.

Headings and generated anchors

Use a clear heading hierarchy. The renderer creates stable, readable anchors from heading text and adds numeric suffixes when headings repeat.

Markdown source

# H1 page heading

## H2 section heading

### H3 supporting heading

#### H4 detail heading

## Stable anchor example

Linkable headings use a lowercase slug such as stable-anchor-example.

## Stable anchor example

A duplicate heading receives the next stable suffix, such as stable-anchor-example-1.

Rendered output

H2 section heading

H3 supporting heading

H4 detail heading

Stable anchor example

Linkable headings use a lowercase slug such as stable-anchor-example.

Stable anchor example

A duplicate heading receives the next stable suffix, such as stable-anchor-example-1.

Links

Make link destinations understandable from the link text, and use secure HTTPS destinations for external references.

Markdown source

Read the Markdown authoring guide before editing a long documentation page.

Descriptive link text tells readers what they will find in the publishing checklist for documentation releases.

Automatic URLs are supported when the renderer recognizes a secure address: https://developers.fliplet.com

Use HTTPS links and never paste unsafe JavaScript URL schemes into documentation.

Rendered output

Read the Markdown authoring guide before editing a long documentation page.

Descriptive link text tells readers what they will find in the publishing checklist for documentation releases.

Automatic URLs are supported when the renderer recognizes a secure address: https://developers.fliplet.com

Use HTTPS links and never paste unsafe JavaScript URL schemes into documentation.

Lists

Use list types to show sequence, grouping, nesting, or completion state at a glance.

Markdown source

• Unordered list item for a concept
• Another concept with a short explanation
  • Nested detail for the second concept
  • A second nested detail

1. Ordered step for a repeatable process
2. Next step with a clear outcome
   1. Nested verification step
   2. Nested publishing step

• [x] Confirm the heading hierarchy
• [ ] Preview links and code blocks
• [ ] Check the page in both browser color schemes

Rendered output

• Unordered list item for a concept
• Another concept with a short explanation
  • Nested detail for the second concept
  • A second nested detail

1. Ordered step for a repeatable process
2. Next step with a clear outcome
   1. Nested verification step
   2. Nested publishing step

• [x] Confirm the heading hierarchy
• [ ] Preview links and code blocks
• [ ] Check the page in both browser color schemes

Blockquotes

Ordinary blockquotes are for attributed guidance, editorial context, or a short quotation—not for alerts.

Markdown source

> “Good documentation makes the next correct action obvious.” > > — Fliplet documentation team

Rendered output

> “Good documentation makes the next correct action obvious.” > > — Fliplet documentation team

Tables

Keep tables focused on comparable information and align numeric or status columns when it improves scanning.

Markdown source

| Format | Best for | Review before publishing | | :--- | :--- | ---: | | Heading | Naming sections and topics | Required | | Link | Connecting readers to a next step | Required | | Alert | Calling out a meaningful constraint | Optional | | Code block | Showing a copyable example | Required |

Rendered output

Inline code

Use inline code for short interface labels, field names, commands, and values that readers should distinguish from prose.

Markdown source

Set the page status to published after the Markdown preview matches the intended public result.

The Pages Markdown field accepts the same source shown in these examples.

Rendered output

Set the page status to published after the Markdown preview matches the intended public result.

The Pages Markdown field accepts the same source shown in these examples.

Fenced code blocks

Add a language identifier to every fenced code block so the renderer can label and highlight it correctly.

Markdown source

### JavaScript

``javascript const route = '/writing-and-formatting-guidelines'; console.log(Previewing ${route}); ``

### HTML

``html <a href="/guides">Guides</a> ``

### XML

``xml <a href="/guides">Writing guidelines</a> ``

### JSON

``json { "status": "published", "locale": "en-US" } ``

### Plaintext

``plaintext Preview the page before publishing. ``

Rendered output

JavaScript

const route = '/writing-and-formatting-guidelines';
console.log(`Previewing ${route}`);

HTML

<a href="/guides">Guides</a>

XML

<a href="/guides">Writing guidelines</a>

JSON

{
  "status": "published",
  "locale": "en-US"
}

Plaintext

Preview the page before publishing.

GitHub alerts

Use alerts sparingly for guidance that deserves stronger visual emphasis than ordinary prose.

Markdown source

> [!NOTE] > The public result is rendered from the exact Markdown source shown in the left panel.

> [!TIP] > Use descriptive link text and keep the surrounding sentence concise.

> [!IMPORTANT] > Every fenced code block should include a language identifier.

> [!WARNING] > Do not publish a page until its links and rendered output have been reviewed.

> [!CAUTION] > Never include credentials, private tokens, or personal information in documentation examples.

Rendered output

> [!NOTE] > The public result is rendered from the exact Markdown source shown in the left panel.

> [!TIP] > Use descriptive link text and keep the surrounding sentence concise.

> [!IMPORTANT] > Every fenced code block should include a language identifier.

> [!WARNING] > Do not publish a page until its links and rendered output have been reviewed.

> [!CAUTION] > Never include credentials, private tokens, or personal information in documentation examples.

Custom renderer behavior

These examples document the behaviors added by the shared renderer and the language aliases authors can rely on.

Markdown source

## Renderer support summary

| Behavior | Authoring pattern | Public result | | :--- | :--- | :--- | | Code copy | Fenced code block | A copy control appears in the code toolbar | | Heading anchors | H2, H3, or H4 text | A stable anchor is generated from the heading | | JavaScript alias | js or javascript | JavaScript language label and highlighting | | Markup aliases | html or xml | Markup language label and highlighting | | JSON alias | json | JSON language label and highlighting | | Text aliases | text or plaintext | Plain text language label | | Sanitization | Safe Markdown links and formatting | Unsafe HTML and schemes are not treated as executable content | | Ordinary quote | A blockquote marker before editorial context | Standard blockquote styling, not an alert |

The renderer keeps ordinary blockquotes ordinary while giving explicit alert syntax a distinct treatment.

Rendered output

Renderer support summary

The renderer keeps ordinary blockquotes ordinary while giving explicit alert syntax a distinct treatment.

Authoring checklist

Use this final pass before a documentation page is published.

Markdown source

• [ ] Use descriptive headings that match the reader’s task
• [ ] Write accessible link text that makes the destination clear
• [ ] Add a language identifier to every fenced code block
• [ ] Use alerts sparingly and only for meaningful constraints
• [ ] Preview the page in both browser color schemes before publishing

Rendered output

• [ ] Use descriptive headings that match the reader’s task
• [ ] Write accessible link text that makes the destination clear
• [ ] Add a language identifier to every fenced code block
• [ ] Use alerts sparingly and only for meaningful constraints
• [ ] Preview the page in both browser color schemes before publishing

Internal page links

Use a stable Page ID when linking to another documentation article. This example links back to this page. Linking to the current page will not open a different article.

[Writing and formatting guidelines](#p_W8mQ3hN6tB2rY7cF)

Writing and formatting guidelines

A link to another Page follows its published content. Use a heading anchor such as #authoring-checklist when linking to a section within this article.