Skip to content

14. Documentation Style Guide

This brief style guide ensures consistency across the docker-mariadb-snapshot documentation.

14.1 Product Naming

Canonical Name: docker-mariadb-snapshot

Use this exact form in all documentation.

14.2 Front Matter

All .md files must include complete YAML front matter:

---
title: Page Title
description: One-sentence summary of the page content
audience: users|operators|developers
doc_type: tutorial|howto|explanation|reference|guide|landing|quickstart
tags: [keyword1, keyword2, keyword3]
lastReviewed: YYYY-MM-DD
version: 1.x
---

Required fields:

  • title: Descriptive page title
  • description: Brief one-sentence summary
  • audience: Target reader (users, operators, or developers)
  • doc_type: Documentation type following Diátaxis framework
  • tags: Array of relevant keywords
  • lastReviewed: ISO date of last review
  • version: Product version (currently 1.x)

14.3 Headings

Capitalization: Use sentence case with key terms capitalized

Examples:

  • ✓ ## Docker Compose Examples
  • ✓ ## Structure-Only Tables
  • ✓ ## MySQL Connection Parameters
  • ✗ ## docker compose examples (too lowercase)
  • ✗ ## DOCKER COMPOSE EXAMPLES (too uppercase)

Hierarchy: Do not skip heading levels (h2 → h4)

14.4 Code Blocks

Always specify the language for syntax highlighting:

```bash
docker run --rm mariadb-snapshot:1.x hourly
```

```yaml
services:
  mariadb-snapshot:
    image: jacobsanford/docker-mariadb-snapshot:1.x
```

```json
{
  "snapshot_time": "2025-11-16T12:00:00Z"
}
```

Supported languages: bash, yaml, json, sql, text

External links: Always use {target="_blank"} to open in new tabs

[Docker](https://www.docker.com){target="_blank"}
[MariaDB](https://mariadb.org){target="_blank"}

Internal links: Use relative paths without {target="_blank"}

[Configuration Reference](configuration.md)
[Quick Start](quickstart.md)

Link text: Use descriptive text, avoid "click here" or bare URLs

  • ✓ See the [Configuration Reference](configuration.md) for details
  • ✗ Click [here](configuration.md) for more information

14.6 Inline Code

Use backticks for:

  • File paths: `/data`, `snapshot.sh`
  • Environment variables: `DB_HOSTNAME`, `RSNAPSHOT_RETAIN_HOURLY`
  • Commands: `docker compose run`
  • Code references: `mariadb-dump`, `rsnapshot`

14.7 Admonitions

Use MkDocs admonitions for important information:

!!! warning "Your Responsibility"
    This package should be considered an example rather than production-ready.

!!! note "Tip"
    Higher compression levels reduce file size but increase CPU usage.

Common types: warning, note, tip, info

14.8 Tables

Use pipe tables with header separators:

| Variable | Description | Default |
|----------|-------------|---------|
| `DB_HOSTNAME` | Database server hostname | `localhost` |
| `DB_PORT` | Database server port | `3306` |

14.9 Tone and Voice

Style: Professional, technical, directive

  • Use active voice: ✓ "Configure the database hostname" vs. ✗ "The database hostname should be configured"
  • Be direct and concise
  • Assume reader has Docker and database familiarity
  • Avoid excessive pleasantries or conversational asides

14.10 File Organization

New pages: 1. Create the .md file in docs/ 2. Add complete front matter 3. Add to navigation in mkdocs.yml 4. Include cross-references to related pages

Images: - Store in docs/images/ - Optimize to <500 KB - Always include descriptive alt text