When should I use forge-docs?

forge-docs is useful in the following scenarios: • Setting up a comprehensive documentation site for a new software project using the mkdocs-material theme and standardized directory structures. • Standardizing project README files across multiple repositories to ensure clear installation, quick start, and contribution guidelines. • Implementing Architecture Decision Records (ADR) to track and document critical technical design choices and their consequences. • Configuring advanced MkDocs features such as Mermaid diagrams, code block copying, and tabbed navigation through a ready-to-use mkdocs.yml template.

When & Why to Use This Skill

This Claude skill streamlines the creation of professional technical documentation by providing standardized MkDocs structures and mkdocs-material templates. It ensures project documentation is consistent, searchable, and visually appealing by offering pre-configured layouts for READMEs, configuration files, and Architecture Decision Records (ADR).

Use Cases

Setting up a comprehensive documentation site for a new software project using the mkdocs-material theme and standardized directory structures.
Standardizing project README files across multiple repositories to ensure clear installation, quick start, and contribution guidelines.
Implementing Architecture Decision Records (ADR) to track and document critical technical design choices and their consequences.
Configuring advanced MkDocs features such as Mermaid diagrams, code block copying, and tabbed navigation through a ready-to-use mkdocs.yml template.

name	forge-docs
description	MkDocs documentation standards with mkdocs-material theme. Use when creating documentation, README files, or project docs structure.

name

forge-docs

description

MkDocs documentation standards with mkdocs-material theme. Use when creating documentation, README files, or project docs structure.

Documentation Standards

MkDocs Structure

docs/
├── index.md                 # Project overview
├── getting-started.md       # Quick start guide
├── architecture/
│   └── decisions/           # ADR files (0001-*.md)
├── guides/
│   ├── installation.md
│   ├── configuration.md
│   └── deployment.md
└── reference/
    ├── api.md
    └── cli.md

mkdocs.yml Template

site_name: Project Name
theme:
  name: material
  palette:
    primary: indigo
    accent: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - content.code.copy

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Guides:
    - Installation: guides/installation.md
    - Configuration: guides/configuration.md
  - Reference:
    - API: reference/api.md
    - CLI: reference/cli.md
  - Architecture:
    - Decisions: architecture/decisions/

Architecture Decision Records (ADR)

Format: NNNN-title-with-dashes.md

# NNNN: Title

## Status

Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-*.md)

## Context

What is the issue that we're seeing that is motivating this decision?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

## References

- Link to relevant docs
- Link to related ADRs

README.md Template

# Project Name

Brief description of the project.

## Installation

\`\`\`bash
pip install project-name
\`\`\`

## Quick Start

\`\`\`python
from project import main
main()
\`\`\`

## Documentation

Full docs at: https://project.readthedocs.io

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

[MIT](LICENSE)