Sample Markdown

This page is a working specimen of the article layout. It brings together the elements that appear in technical writing, from a short git status command to wide tables, Kubernetes manifests, terminal output, and nested code blocks. Use the contents navigation to compare sections, then check the same examples in both themes and at narrower widths.

Typography and inline code

A paragraph should be easy to follow without competing with the navigation. Strong text adds emphasis, italic text adds a quieter distinction, and links remain easy to identify. A footnote can carry a useful aside without interrupting the sentence.¹

Inline code such as pnpm run build, config.enabled, and /etc/loader/loader.conf should sit comfortably within the line. Longer identifiers such as a_deliberately_long_configuration_key_that_needs_to_wrap_on_a_small_screen must stay inside the reading column.

Links, emphasis, and punctuation

A link inside a sentence should remain identifiable without overpowering the paragraph. Compare an internal article link, a section link, and a link next to inline_code. Bold with an italic phrase, outdated advice, and a keyboard shortcut such as Ctrl + K should all have a clear place in the text.

Technical prose also includes symbols and punctuation: “quoted text”, an apostrophe in a developer’s note, an en dash in a range (3–5), arrows →, a percentage (99.9%), and an expression such as n². None should change the rhythm of the line.

Third-level heading

Use this level to break a section into related ideas. The spacing should make the hierarchy clear without adding another box around every paragraph.

Fourth-level heading

Smaller headings remain neutral rather than introducing another accent color.

Fifth-level heading

A compact label for a small subdivision.

Sixth-level heading

The final heading level should still be readable without becoming louder than the paragraph around it.

Lists and tasks

• Understand the workflow before changing it.
  • Identify the repeated steps.
  • Write down what a successful run looks like.
• Make the smallest useful automation.
  1. Validate the inputs.
  2. Run the operation.
  3. Report the outcome.
• Leave enough context for the next person.

A checklist is useful when the order matters less than whether each step is complete:

• Keep the reading column comfortable.
• Use the same sharp edges throughout.
• Check the examples on a narrow screen.

Tables

A short table should fill the reading column, with each header aligned to its cells.

Wide tables

This table deliberately has more columns. On a narrow screen, scroll the table rather than the entire page. Numeric columns align to the right.

Tables with code and missing values

Headers, links, and inline code often appear together in real documentation. An empty cell should retain its spacing, and a long identifier should stay inside the table’s scrollable area.

Code blocks

Code uses a neutral surface, distinct syntax colors, and the same monospace family as the interface. Language labels and filenames belong in the header. The copy control copies the code, not the header.

from pathlib import Path
 
 
def collect_notes(directory: Path) -> list[Path]:
    # Return a predictable order for repeatable builds.
    return sorted(directory.glob("*.md"))
 
 
notes = collect_notes(Path("content/posts"))
print(f"Found {len(notes)} notes")

YAML and Kubernetes

YAML is common in infrastructure articles. Keys should be visually distinct from string values; punctuation, comments, numbers, and booleans should remain easy to tell apart. This first example mirrors a practical RBAC manifest, including nested mappings and arrays.

# Allow a reader to inspect pods in one namespace.
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
  labels:
    app.kubernetes.io/part-of: documentation
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs:
      - get
      - list
      - watch

The next configuration exercises scalar values, quoted strings, an empty value, a URL, and a multiline string. YAML uses indentation as structure, so preserving spaces matters as much as choosing colors.²

project: personal-site
enabled: true
retries: 3
timeoutSeconds: 30
ratio: 0.75
optionalOutput: null
endpoint: https://example.com/api/validate
message: "Keep punctuation: and # characters inside the string."
formats: [markdown, mdx]
paths:
  include: content/posts
  exclude:
    - "**/drafts/**"
    - "**/images/**"
summary: |
  Validate content before publishing.
  Report the file and line when something fails.
command: >-
  pnpm exec biome check .
  --diagnostic-level=error

Workflow YAML and expressions

CI configuration adds expressions, environment variables, shell commands, and multiline values. The workflow expression syntax below is literal code, not part of the article renderer.

name: Validate content
on:
  pull_request:
    paths: ["content/**", "src/**"]
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    env:
      CI: true
      BRANCH: ${{ github.head_ref }}
    steps:
      - uses: actions/checkout@v4
      - name: Check generated content
        run: |
          printf 'Validating branch: %s\n' "$BRANCH"
          pnpm run build

Configuration and shell commands

{
  "project": "personal-site",
  "validation": {
    "enabled": true,
    "retries": 2
  },
  "formats": ["markdown", "mdx"]
}

# Run checks before generating the site.
pnpm exec biome check .
mise run typecheck
pnpm run build

TypeScript and JavaScript

Compare type annotations, property names, function calls, strings, and template substitutions. Comments should stay quieter than executable code.

type Entry = {
  title: string
  draft?: boolean
  tags: string[]
}
 
export function describeEntry(entry: Entry): string {
  const visibleTags = entry.tags.filter((tag) => tag.length > 0)
  // Keep the display label separate from the stored title.
  return `${entry.title}: ${visibleTags.join(", ") || "untagged"}`
}
 
const entry: Entry = { title: "A useful automation", draft: false, tags: ["python"] }
console.log(describeEntry(entry))

export async function retry(operation, attempts = 3) {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      return await operation()
    } catch (error) {
      if (attempt === attempts) throw error
      await new Promise((resolve) => setTimeout(resolve, 250 * attempt))
    }
  }
}

Shell scripts and errors

A shell example should distinguish comments, variables, flags, and quoted strings. These are illustrative commands; no script on this page is executed by the browser.

#!/usr/bin/env bash
set -euo pipefail
 
content_dir="${1:-content/posts}"
if [[ ! -d "$content_dir" ]]; then
  printf 'Missing directory: %s\n' "$content_dir" >&2
  exit 1
fi
 
find "$content_dir" -type f -name '*.mdx' -print |
  sort |
  while IFS= read -r file; do
    printf 'Checking %s\n' "$file"
  done

TOML, INI, and Dockerfiles

Configuration is not limited to YAML and JSON. Compare section headers, dotted keys, booleans, arrays, and comments across these formats.

[project]
name = "content-validator"
version = "0.1.0"
 
[validation]
enabled = true
retries = 3
formats = ["markdown", "mdx"]
 
[validation.paths]
source = "content/posts"
output = "dist"

# Example boot loader configuration
[loader]
default = arch.conf
timeout = 3
editor = no

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENV PYTHONUNBUFFERED=1
CMD ["python", "-m", "content_validator"]

SQL and patches

A query mixes keywords, identifiers, string literals, and numeric values. A patch should make additions and removals distinguishable.

SELECT title, published_at, category
FROM articles
WHERE draft = FALSE
  AND category IN ('engineering', 'guides')
ORDER BY published_at DESC
LIMIT 5;

-const visiblePosts = posts.filter((post) => post.featured).slice(0, 6)
+const featured = posts.find((post) => post.featured)
+const visiblePosts = (featured
+  ? [featured, ...posts.filter((post) => post.id !== featured.id)]
+  : posts).slice(0, 5)

Highlighted lines and untitled blocks

Highlighted ranges should fill the code area evenly without introducing extra blank lines. This example has two separate ranges, including a nested block.

def validate(title: str, retries: int) -> bool:
    if not title.strip():
        raise ValueError("A title is required")
 
    for attempt in range(retries):
        print(f"Validation attempt {attempt + 1}")
        return True
    return False

Some snippets do not need a filename. The language label and copy control should still align correctly:

python -m content_validator --dry-run

A single-line block should have the same spacing and border treatment as a longer example:

print("Ready")

Long lines and plain text

Long source lines stay on one line and scroll inside their code block. They should not widen the article or push the contents navigation out of place.

2026-10-15T09:30:00Z INFO workflow=content-validation environment=development source=content/posts result=success message="All published entries passed validation and are ready for the next build."

Terminal output

ANSI colors retain their meaning for successes, warnings, and errors while using the site’s theme colors.

$ pnpm run build
Collecting content and optimizing assets…
✓ Content validated
! Optional preview skipped
✗ Example failure message
✓ Build complete

ANSI palette and text attributes

Compare normal and bright colors, dim output, bold text, and a colored background. Reset sequences should keep one line’s styling from leaking into the next.

Red  Green  Yellow  Blue
Magenta  Cyan  White
Bright red  Bright green  Bright yellow
Bright blue  Bright magenta  Bright cyan
Bold status  Dim diagnostic detail
Dim success message
 WARNING  Inspect the output before continuing.
Normal text after a reset.

Quotes and callouts

A useful tool removes a repeated decision without hiding the reasoning behind it.

This second paragraph demonstrates the spacing inside a longer quotation.

A quotation can also contain a list or a code block:

A nested example

Keep the output simple enough to inspect.

• Show the result.
• Explain what happened.

def report(count: int) -> str:
    return f"Processed {count} entries"

Callout variants

Each supported callout has the same geometry and spacing. Its icon and semantic color distinguish the message, rather than a different card design.

Optional details

Native disclosure elements can hold a longer explanation without interrupting the first reading. Check both the closed and expanded states.

Images and media

Images supplied within an article remain part of the content. They use the same hard edges as tables and code blocks.

An inline image with a short caption.

Definitions and footnotes

Repeatability

The same inputs produce a result that can be checked and understood.

Handoff

The next person has enough context to run, inspect, and change the system.

A separator should divide ideas without adding another surface:

This is the closing paragraph. It includes emphasis, an inline command, and a second reference to the same footnote.¹