undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

<!-- docs/guide/admonitions.md -->

undefined

<!-- docs/guide/code-blocks.md -->

def hello_world():
    print("Hello, World!")

def hello_world():
    print("Hello, World!")

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

def process_data(data):
    validated = validate(data)  # highlighted
    transformed = transform(validated)
    return save(transformed)  # highlighted

undefined

undefined

def calculate_area(radius: float) -> float:  # (1)!
    """Calculate the area of a circle."""
    import math  # (2)!
    return math.pi * radius ** 2  # (3)!

undefined

<!-- docs/guide/diagrams.md -->

flowchart TD
    A[Start] --> B{Is it valid?}
    B -->|Yes| C[Process Data]
    B -->|No| D[Show Error]
    C --> E[Save Results]
    D --> F[Log Error]
    E --> G[End]
    F --> G

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database

    U->>A: POST /api/data
    A->>A: Validate request
    A->>D: INSERT data
    D-->>A: Success
    A-->>U: 201 Created

classDiagram
    class Document {
        +String title
        +String content
        +Date created
        +save()
        +delete()
    }
    class Page {
        +int pageNumber
        +String markdown
        +render()
    }
    class Navigation {
        +List~Page~ pages
        +addPage()
        +removePage()
    }
    Document "1" --> "*" Page
    Navigation "1" --> "*" Page

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Accept
    Review --> Draft: Request Changes
    Approved --> Published: Publish
    Published --> [*]

erDiagram
    USER ||--o{ POST : creates
    USER ||--o{ COMMENT : writes
    POST ||--|{ COMMENT : contains
    POST }|..|{ TAG : has

gantt
    title Documentation Project
    dateFormat  YYYY-MM-DD
    section Phase 1
    Research           :a1, 2024-01-01, 7d
    Outline            :a2, after a1, 3d
    section Phase 2
    Writing            :b1, after a2, 14d
    Review             :b2, after b1, 7d
    section Phase 3
    Publishing         :c1, after b2, 3d

undefined

undefined

undefined

undefined

```yaml

undefined

undefined

```css
/* docs/stylesheets/extra.css */

/* Custom color scheme */
:root {
  --md-primary-fg-color: #6200ea;
  --md-primary-fg-color--light: #9d46ff;
  --md-primary-fg-color--dark: #0a00b6;
  --md-accent-fg-color: #ff6d00;
}

/* Custom admonition */
:root {
  --md-admonition-icon--custom: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/></svg>');
}

.md-typeset .admonition.custom,
.md-typeset details.custom {
  border-color: #6200ea;
}

.md-typeset .custom > .admonition-title,
.md-typeset .custom > summary {
  background-color: rgba(98, 0, 234, 0.1);
}

.md-typeset .custom > .admonition-title::before,
.md-typeset .custom > summary::before {
  background-color: #6200ea;
  -webkit-mask-image: var(--md-admonition-icon--custom);
  mask-image: var(--md-admonition-icon--custom);
}

/* Code block styling */
.md-typeset code {
  border-radius: 4px;
}

/* Navigation tweaks */
.md-nav__link {
  font-size: 0.75rem;
}

/* Table styling */
.md-typeset table:not([class]) {
  font-size: 0.8rem;
}

.md-typeset table:not([class]) th {
  background-color: var(--md-primary-fg-color);
  color: white;
}

// docs/javascripts/extra.js

// Add copy button feedback
document.addEventListener('DOMContentLoaded', function() {
  document.querySelectorAll('.md-clipboard').forEach(function(button) {
    button.addEventListener('click', function() {
      const originalText = this.getAttribute('data-clipboard-text');
      console.log('Copied:', originalText.substring(0, 50) + '...');
    });
  });
});

// Custom analytics event
function trackDocSection(section) {
  if (typeof gtag !== 'undefined') {
    gtag('event', 'view_section', {
      'section_name': section
    });
  }
}

// Smooth scroll enhancement
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
  anchor.addEventListener('click', function(e) {
    e.preventDefault();
    document.querySelector(this.getAttribute('href')).scrollIntoView({
      behavior: 'smooth'
    });
  });
});

undefined

  - name: Setup Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.11'

  - name: Cache dependencies
    uses: actions/cache@v4
    with:
      path: ~/.cache/pip
      key: ${{ runner.os }}-pip-${{ hashFiles('requirements-docs.txt') }}
      restore-keys: |
        ${{ runner.os }}-pip-

  - name: Install dependencies
    run: |
      pip install -r requirements-docs.txt

  - name: Build documentation
    run: mkdocs build --strict

  - name: Deploy to GitHub Pages
    uses: peaceiris/actions-gh-pages@v4
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}
      publish_dir: ./site
      cname: docs.example.com  # Optional custom domain

```text

undefined

undefined

  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'

  - name: Install dependencies
    run: pip install -r requirements-docs.txt

  - name: Configure Git
    run: |
      git config user.name "github-actions[bot]"
      git config user.email "github-actions[bot]@users.noreply.github.com"

  - name: Get version from tag
    id: version
    run: |
      if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
        echo "VERSION=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
        echo "ALIAS=${{ github.event.inputs.alias }}" >> $GITHUB_OUTPUT
      else
        VERSION=${GITHUB_REF#refs/tags/v}
        MAJOR_MINOR=$(echo $VERSION | cut -d. -f1,2)
        echo "VERSION=$MAJOR_MINOR" >> $GITHUB_OUTPUT
        echo "ALIAS=latest" >> $GITHUB_OUTPUT
      fi

  - name: Deploy with mike
    run: |
      mike deploy --push --update-aliases \
        ${{ steps.version.outputs.VERSION }} \
        ${{ steps.version.outputs.ALIAS }}
      mike set-default --push latest

undefined

my-python-package/
├── src/
│   └── mypackage/
│       ├── __init__.py
│       └── core.py
├── docs/
│   ├── index.md
│   ├── getting-started/
│   ├── api/
│   └── assets/
├── tests/
├── mkdocs.yml
├── pyproject.toml
└── README.md

undefined

undefined

undefined

undefined

undefined

  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'

  - name: Install dependencies
    run: pip install -r requirements-docs.txt

  - name: Build documentation (strict mode)
    run: mkdocs build --strict

  - name: Check links
    run: |
      pip install linkchecker
      mkdocs serve &
      sleep 5
      linkchecker http://127.0.0.1:8000 --check-extern

  - name: Lint Markdown
    run: |
      npm install -g markdownlint-cli
      markdownlint docs/**/*.md

undefined

docs/
├── index.md                    # Landing page
├── getting-started/
│   ├── index.md               # Section overview
│   ├── installation.md
│   ├── quickstart.md
│   └── configuration.md
├── user-guide/
│   ├── index.md
│   ├── concepts.md
│   ├── tutorials/
│   │   ├── basic.md
│   │   └── advanced.md
│   └── best-practices.md
├── api/
│   ├── index.md
│   └── reference.md
├── contributing/
│   ├── index.md
│   ├── development.md
│   └── style-guide.md
├── changelog.md
├── assets/
│   ├── images/
│   ├── stylesheets/
│   └── javascripts/
└── includes/                   # Reusable snippets
    └── abbreviations.md

---
title: Page Title
description: Brief description for SEO and social sharing
---

undefined

<!-- docs/includes/abbreviations.md -->
*[HTML]: Hyper Text Markup Language
*[API]: Application Programming Interface
*[CLI]: Command Line Interface
*[CSS]: Cascading Style Sheets
*[JSON]: JavaScript Object Notation
*[YAML]: YAML Ain't Markup Language
*[REST]: Representational State Transfer
*[SDK]: Software Development Kit
*[URL]: Uniform Resource Locator
*[CI]: Continuous Integration
*[CD]: Continuous Deployment

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined