Formatting Examples

Formatting Examples

This page is a disposable formatting sampler. Use it to judge Starlight spacing, terminal code blocks, tables, asides, Markdoc components, and copyable syntax before writing real content.

Markdoc is enabled

This page is now examples.mdoc, so the examples using {% %} tag syntax render for real. The literal syntax examples are shown in text code blocks immediately after each rendered example.

Markdown Basics

Markdoc is a superset of CommonMark, so normal Markdown still carries the main writing flow. Use inline code for commands like docker compose ps, paths like /srv/apps, and config keys like restart: unless-stopped.

Lists

• Keep unordered lists compact.
• Use them for inventories, requirements, and quick notes.
• Prefer one idea per bullet.

1. Use ordered lists for procedures.
2. Put the command close to the step that uses it.
3. End with a verification step.

Blockquote

Placeholder quote for testing quote spacing. Replace this with a real note, source, or principle later.

Table

Use case	Format	Notes
Procedure	Ordered list	Best for repeatable tasks.
Command output	Fenced code	Use bash, text, or a specific language.
Risk note	Markdoc aside	Use note, tip, caution, or danger.
Structure	Markdoc filetree	Use the filetree tag.

Asides

Rendered

Copy-friendly content

Use Markdoc asides for optional improvements, shortcuts, or small quality-of-life details.

Check the blast radius

Use cautions for actions that can lock you out, delete data, or create confusing follow-up work.

Syntax

{% aside type="tip" title="Copy-friendly content" %}
Use Markdoc asides for optional improvements, shortcuts, or small quality-of-life details.
{% /aside %}

{% aside type="caution" title="Check the blast radius" %}
Use cautions for actions that can lock you out, delete data, or create confusing follow-up work.
{% /aside %}

Terminal Blocks

npm install
npm run build
npm run dev -- --host 127.0.0.1

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

Get-ChildItem -Force
Test-Path .\package.json

Config Blocks

services:
  dashboard:
    image: ghcr.io/example/dashboard:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data

[server]
host = "127.0.0.1"
port = 8080

{
  "scripts": {
    "build": "astro build",
    "dev": "astro dev"
  }
}

Diff Blocks

services:
  dashboard:
    image: ghcr.io/example/dashboard:1.0.0
    image: ghcr.io/example/dashboard:1.1.0
    restart: unless-stopped

Plain Markdown File Tree

Use plain text trees when you need a Markdown-only fallback.

srv/
|-- apps/
|   |-- dashboard/
|   |   |-- compose.yaml
|   |   |-- .env
|   |   `-- data/
|   `-- proxy/
|       |-- compose.yaml
|       `-- Caddyfile
`-- backups/

Markdoc File Tree

Rendered

• Directoryastro.codevibr.dev/ project root

  • astro.config.mjs integration configuration
  • markdoc.config.mjs Markdoc component preset
  • package.json dependency manifest
  • Directorysrc/

    • Directorycontent/

      • Directorydocs/

        • Directorydocs/

          • index.md
          • examples.mdoc
          • Directoryhomelab/

            • docker-compose-notes.md
            • troubleshooting.md
        • Directoryblog/

          • welcome-to-the-site.md
  • Directorypublic/

    • favicon.svg

Syntax

{% filetree %}
- **astro.codevibr.dev/** project root
  - astro.config.mjs integration configuration
  - markdoc.config.mjs Markdoc component preset
  - package.json dependency manifest
  - src/
    - content/
      - docs/
        - docs/
          - index.md
          - **examples.mdoc**
          - homelab/
            - docker-compose-notes.md
            - troubleshooting.md
        - blog/
          - welcome-to-the-site.md
  - public/
    - favicon.svg
{% /filetree %}

Placeholders And Special Names

Rendered

• Directoryapp/

  • README - recovery.md
  • __init__.py
  • Directorydata/

    • ...

Syntax

{% filetree %}
- app/
  - `README - recovery.md`
  - `__init__.py`
  - data/
    - ...
{% /filetree %}

Markdoc Steps

Rendered

1. Create the service directory.

   mkdir -p /srv/apps/dashboard

2. Add compose.yaml.

3. Start the stack and verify it is healthy.

Syntax

{% steps %}
1. Create the service directory.

   ```bash
   mkdir -p /srv/apps/dashboard
   ```

2. Add `compose.yaml`.

3. Start the stack and verify it is healthy.
{% /steps %}

Markdoc Tabs

Rendered

npm

npm run build

Docker

docker compose up -d

Syntax

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}
```bash
npm run build
```
{% /tabitem %}

{% tabitem label="Docker" %}
```bash
docker compose up -d
```
{% /tabitem %}
{% /tabs %}

Markdoc Cards

Rendered

Backup first

Confirm the latest backup before changing service versions.

Verify after deploy

Run the smoke checks before moving on to the next service.

Syntax

{% cardgrid %}
{% card title="Backup first" icon="seti:folder" %}
Confirm the latest backup before changing service versions.
{% /card %}

{% card title="Verify after deploy" icon="rocket" %}
Run the smoke checks before moving on to the next service.
{% /card %}
{% /cardgrid %}

Link Components

Rendered

Docker Compose Notes Placeholder notes with Markdoc file tree syntax examples.

Back to docs

Syntax

{% linkcard title="Docker Compose Notes" href="/docs/homelab/docker-compose-notes/" description="Placeholder notes with Markdoc file tree syntax examples." /%}

{% linkbutton href="/docs/" variant="secondary" icon="right-arrow" %}
Back to docs
{% /linkbutton %}