setup-docs-site

TODAY=!date +%Y-%m-%d

Setup Docs Site

Scaffolds a MkDocs documentation site with the Material theme, creates the initial content structure under docs/, and adds a GitHub Actions workflow to build and deploy to GitHub Pages.

Does not overwrite existing files. If mkdocs.yml or docs/ already exist, reports what is present and skips or offers to update.

Prerequisites

• Python project with pyproject.toml (for uv add), or willingness to install MkDocs via pip
• Git repository with a GitHub remote (for the GHA workflow)
• uv available in PATH (preferred) or pip
• Read any files present under .sdlc/context/ for project-level context to populate docs content

Steps

1. Determine the project root

Use $1 if provided, otherwise use the current working directory. Verify it is a git repository:

git rev-parse --is-inside-work-tree

Check for a GitHub remote:

gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null

If no GitHub remote, skip the GHA workflow creation and report the limitation.

2. Check existing documentation infrastructure

Check for existing files:

ls mkdocs.yml docs/ README.md .github/workflows/pages*.yml .github/workflows/pages*.yaml 2>/dev/null

If mkdocs.yml exists, report it and skip to Step 5 (content structure). If docs/ exists, report it and merge content rather than overwrite.

3. Install MkDocs dependencies

Detect the package manager and install:

For uv projects (preferred):

uv add --dev mkdocs "mkdocs-material[imaging]"

The [imaging] extra pulls in cairosvg/pillow, which are required by the social plugin to generate social/OpenGraph cards.

For pip projects:

pip install mkdocs "mkdocs-material[imaging]"

Record what was installed.

4. Create mkdocs.yml

Create mkdocs.yml in the project root with the following structure. Derive site_name, site_description, and repo_url from the codebase:

site_name: <project name>
site_description: <one sentence from README or pyproject.toml>
site_url: ""
repo_url: <github remote url>
repo_name: <owner/repo>
edit_uri: edit/main/docs/

extra:
  social:
    - icon: fontawesome/brands/github
      link: <github remote url>

theme:
  name: material
  font:
    text: Open Sans
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      accent: green
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: green
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - search.share
    - content.action.edit
    - content.action.view
    - content.code.copy
    - content.code.annotate

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Reference: reference/
  - Changelog: changelog.md

markdown_extensions:
  - admonition
  - attr_list
  - footnotes
  - md_in_html
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - toc:
      permalink: true

plugins:
  - search
  - social