project-bootstrap

# Project Bootstrap

Bootstrap open-source projects with professional documentation, CI/CD, and polish.

## Components

| Component | What it does |
|-----------|--------------|
| **MkDocs** | Material theme docs with tabs, code copy, dark mode |
| **GitHub Actions** | Auto-deploy docs on push to main |
| **Giscus** | GitHub Discussions-based comments on docs |
| **README** | Polished README with badges, tables, examples |
| **Funding** | Ko-fi badge, GitHub Sponsors |

## Quick Reference

### MkDocs Setup

Create `mkdocs.yml`:

```yaml
site_name: Project Name
site_url: https://ninyawee.github.io/REPO
repo_url: https://github.com/ninyawee/REPO

theme:
  name: material
  custom_dir: docs/overrides
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - content.code.copy
    - navigation.sections
    - navigation.expand

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - admonition
  - pymdownx.details

nav:
  - Home: index.md
  - Getting Started: getting-started.md
```

Add mise task:

```toml
[tasks."docs:serve"]
run = "uv run --with mkdocs-material mkdocs serve"

[tasks."docs:build"]
run = "uv run --with mkdocs-material mkdocs build"
```

### GitHub Actions - Docs Deploy

Create `.github/workflows/docs.yml`:

```yaml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml', '.github/workflows/docs.yml']
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs mkdocs-material
      - run: mkdocs gh-deploy