Forge Markdown Syntax (.md)

A guide to every Markdown feature you can use in .md files across Uvilo OS docs. Our site runs on Astro Starlight, which extends standard Markdown with Expressive Code enhancements and directive-based components.

For MDX-specific components (<Tabs>, <Steps>, <Card>, etc.), see Forge Markdown MDX Syntax.

Standard Markdown

Everything you already know works:

• Bold with **double asterisks**
• Italic with *single asterisks*
• Strikethrough with ~~double tildes~~
• Headings with #, ##, ###, up to ######
• Unordered lists with - or *
• Ordered lists with 1., 2., 3.
• Links with [text](url)
• Images with ![alt](url)
• Horizontal rules with ---
• Inline code with single backticks
• Blockquotes with >

Example:

Bold text, italic text, and strikethrough are all supported.

A heading

• An unordered item
• Another item

1. First ordered item
2. Second ordered item

Visit Uvilo

A blockquote with something important to say.

---

Asides

Asides are colored callout boxes for secondary information. In .md files, use the directive syntax with triple colons.

There are four types:

Type	Color	Icon	Use for
note	Blue	ℹ️	Informational notes
tip	Purple	🚀	Helpful suggestions
caution	Yellow	⚠️	Warnings to be careful
danger	Red	🛑	Critical warnings

Basic asides

:::note
This is a note aside.
:::

:::tip
Here's a helpful tip!
:::

:::caution
Be careful with this approach.
:::

:::danger
Do not delete the production database!
:::

Result:

This is a note aside.

Here’s a helpful tip!

Be careful with this approach.

Do not delete the production database!

Custom titles

Override the default title with square brackets:

:::caution[Watch out!]
This has a custom title.
:::

Result:

Watch out!

This has a custom title.

Asides can contain nested Markdown, including code blocks.

Code Blocks

Syntax highlighting

Add a language identifier after the opening backticks:

```js
const greeting = "Hello, world!";
console.log(greeting);
```

Result:

const greeting = "Hello, world!";
console.log(greeting);

Line highlighting

Highlight specific lines with curly braces after the language. Use {1,4-6} for non-consecutive lines.

```js {2-3}
function demo() {
  // This line and the next are highlighted
  return 'highlighted';
}
```

Result:

function demo() {
  // This line and the next are highlighted
  return 'highlighted';
}

Mark inserted and deleted text

Show additions and removals with ins= and del=. Default markers (in quotes) highlight in neutral yellow, ins= in green (additions), del= in red (deletions).

```js "return true;" ins="inserted" del="deleted"
function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}
```

Result:

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Window frames and titles

Expressive Code adds a terminal/editor window frame around code blocks by default. Use title= to add a filename.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
export default defineConfig({});
```

Result:

astro.config.mjs

import { defineConfig } from 'astro/config';
export default defineConfig({});

Mermaid Diagrams

Our site supports Mermaid diagrams inline:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Result:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and more.

Frontmatter

Frontmatter contains metadata used to identify the document and organize it in the sidebar. This is handled automatically by Forge agents, and never edited by humans.

Full frontmatter reference

---
title: My Documentation Page
description: Learn how to use the example feature.

# Table of contents
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
# tableOfContents: false  # hide TOC entirely

# Page template ('doc' is default, 'splash' for landing pages)
template: doc

# Last updated date
lastUpdated: 2024-01-15

# Pagination
prev:
  link: /guides/introduction
  label: Introduction
next: false  # hide next link

# Sidebar customization
sidebar:
  label: Custom Label
  order: 1
  hidden: false
  badge:
    text: New
    variant: tip

# Announcement banner
banner:
  content: We just launched v2.0!

# Exclude from search
pagefind: false

# Draft (hidden in production)
draft: false
---

Summary

Feature	Syntax
Code highlighting	```js {2-3}
Insert/delete markers	ins="text" del="text"
Code block titles	title="file.js"
Asides	:::note / :::tip / :::caution / :::danger
Mermaid	```mermaid
Frontmatter	---yaml---

For the full Starlight component API, see the Starlight Components Reference. For Expressive Code options, see the Expressive Code docs.