Skip to content

Contributing to Appcircle Internal Docs (MkDocs)

This guide explains how to add or update content in Appcircle Internal Docs.

Where the documentation lives

All documentation pages are stored under the docs/ directory.

  • Add new pages as Markdown (.md) files.
  • Place the page under the most relevant category/folder.

Example structure:

repo-root/
├─ docs/
│  ├─ records/
│  │  ├─ adr/
│  │  └─ ir/
│  ├─ development/
│  ├─ devops/
│  └─ ...
└─ mkdocs.yml

This documentation site uses two navigation levels:

  1. Top-level sections (shown in the site header)
  2. Sub-pages (shown in the left sidebar)

In MkDocs Material, this typically corresponds to enabling navigation tabs (top-level nav entries become header tabs), while nested entries appear in the sidebar.

Adding a new page

  1. Create a new .md file under docs/ in the correct category.
  2. Write content using Markdown (use headings in a clear hierarchy).
  3. Register the page in mkdocs.yml so it appears in the navigation.
  • Use exactly one H1 (# Title) per page.
  • Use H2 (##) for main sections.
  • Use H3 (###) and deeper levels only when necessary.

Example:

# Page Title

## Purpose

## How it works

### Details

Updating mkdocs.yml navigation

Navigation is controlled from the project root mkdocs.yml file.

  • Top-level items under nav: appear in the header.
  • Nested items appear in the sidebar.

Example:

nav:
  - Architecture:
      - Overview: development/architecture/overview.md
      - Hexagonal Architecture: development/architecture/hexagonal-architecture.md
  - DevOps:
      - Git Branching Strategy: devops/git-branching-strategy.md
      - Conventional Commits: devops/conventional-commit.md

Tip: Keep naming consistent across the repo. Use clear titles (what the user should see in the menu), and stable file paths.

Admonitions (Notes, Warnings, Tips)

We use MkDocs Material admonitions to highlight important information such as notes and warnings.

Basic syntax

An admonition starts with !!! <type> and its content must be indented (recommended: 4 spaces).

!!! note
    This is a note.

Common types:

  • note
  • info
  • tip
  • warning
  • danger
  • success

Example:

!!! warning
    This action cannot be undone.

Custom title

You can override the default title:

!!! warning "Breaking change"
    This page describes a behavior that changed after vX.Y.

Collapsible admonitions

For expandable/collapsible blocks, use ??? instead of !!!:

??? tip "Click to expand"
    Extra details live here.

Code blocks inside an admonition

Indent the fenced code block under the admonition (keep the fence aligned with the text indentation):

!!! example "Local preview"
    ```bash
    mkdocs serve
    ```

Indentation rules (important)

  • The content under !!! / ??? must be indented.
  • Avoid tabs; use spaces.
  • For nested lists, keep indentation consistent.

Required MkDocs extensions

If admonitions do not render, ensure these are enabled in mkdocs.yml:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Adding images and other resources

If your page requires images or other assets (diagrams, exports, attachments), store them in a files/ directory next to the page.

Example:

docs/
└─ development/
   └─ architecture/
      ├─ overview.md
      └─ files/
         ├─ system-diagram.png
         └─ sequence.excalidraw

Reference assets with relative paths:

![System Diagram](./files/system-diagram.png)

Linking between pages

Prefer relative links for internal pages so links remain stable across environments:

See also: [Git Branching Strategy](../../devops/git-branching-strategy.md)

Before pushing changes, preview locally to ensure navigation and links work.

Typical commands:

mkdocs serve

Then open the local URL printed in the terminal.

Contribution workflow (suggested)

  1. Create a branch for your change.
  2. Add/edit Markdown files under docs/.
  3. Update mkdocs.yml navigation (if you added/moved pages).
  4. Preview locally.
  5. Open a pull request and request review.

Content quality checklist

  • Titles and headings are consistent and easy to scan.
  • Paths in mkdocs.yml are correct.
  • Images load correctly and are placed under files/.
  • Links work (no broken relative links).
  • The page is placed in the correct category.