Set up MkDocs (Material) + Read the Docs with versioned public docs and strict CI docs checks

.github/workflows/ci.yml

@@ -46,6 +46,43 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: cargo test --features telemetry-otel -- --include-ignored --skip jira_ --skip bitbucket_
 
+  docs:
+    name: Docs
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Detect docs-related changes
+        id: changes
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - 'mkdocs.yml'
+              - '.readthedocs.yml'
+
+      - name: Set up Python
+        if: steps.changes.outputs.docs == 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install docs dependencies
+        if: steps.changes.outputs.docs == 'true'
+        run: pip install -r docs/requirements.txt
+
+      - name: Docs build (strict)
+        if: steps.changes.outputs.docs == 'true'
+        run: mkdocs build --strict
+
+      - name: Skip docs build (no docs changes)
+        if: steps.changes.outputs.docs != 'true'
+        run: echo "No docs-related changes detected; skipping docs build."
+
   test_no_telemetry:
     name: Test (no telemetry feature)
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'

.gitignore

@@ -2,8 +2,7 @@
 /target
 
 # Private docs (see docs/ for publishing and deployment guides)
-/docs/npm-publishing.md
-/docs/deployment.md
+/docs/internal
 plan/
 issue/
 

.readthedocs.yml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+versions:
+  only:
+    - main
+    - stable
+    - /^v\d+\.\d+\.\d+$/

README.md

@@ -1,6 +1,7 @@
 # 99problems
 
 [![CI](https://github.com/mbe24/99problems/actions/workflows/ci.yml/badge.svg)](https://github.com/mbe24/99problems/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/99problems/badge/?version=latest)](https://99problems.readthedocs.io/en/latest/)
 [![npm](https://img.shields.io/npm/v/@mbe24/99problems?color=7C3AED&label=npm)](https://www.npmjs.com/package/@mbe24/99problems)
 [![crates.io](https://img.shields.io/crates/v/problems99?color=7C3AED&label=crates.io)](https://crates.io/crates/problems99)
 ![platforms](https://img.shields.io/badge/platforms-win%20%7C%20linux%20%7C%20macos-7C3AED)
@@ -142,20 +143,6 @@ Note that telemetry export requires a build with the telemetry-otel feature enab
 - Default builds include it.
 - Use `--no-default-features` for telemetry-free release binaries.
 
-## Man Pages
-
-Generate and print root man page:
-
-```bash
-99problems man
-```
-
-Generate all pages to disk:
-
-```bash
-99problems man --output docs/man --section 1
-```
-
 ## Output Modes
 
 `get` supports two orthogonal controls:
@@ -199,6 +186,26 @@ Use user scope by overriding path:
 99problems skill init --path ~/.agents/skills
 ```
 
+## Documentation
+
+Project documentation is available at [99problems.readthedocs.io](https://99problems.readthedocs.io/).
+
+Public docs source lives in [`docs/`](docs/). Internal-only notes belong in [`docs/internal/`](docs/internal/) and are excluded from the published site.
+
+### Man Pages
+
+Generate and print root man page:
+
+```bash
+99problems man
+```
+
+Generate all pages to disk:
+
+```bash
+99problems man --output docs/man --section 1
+```
+
 ## Support this project
 
 If 99problems saves you time, you can support ongoing maintenance via [GitHub Sponsors](https://github.com/sponsors/mbe24) or [Ko-fi](https://ko-fi.com/mbe24).

docs/configuration.md

@@ -0,0 +1,25 @@
+# Configuration
+
+`99problems` reads instance-based TOML configuration from:
+
+- `~/.99problems`
+- `./.99problems`
+
+Minimal example:
+
+```toml
+[instances.github]
+platform = "github"
+repo = "owner/repo"
+token = "ghp_your_token"
+```
+
+See the [README configuration section](https://github.com/mbe24/99problems/blob/main/README.md#configuration) for the complete configuration reference.
+
+## Configuration behavior
+
+- `--instance` selects an explicit configured instance
+- If exactly one instance exists, it is auto-selected
+- If multiple instances exist, `default_instance` is used when set
+
+Keep credentials in local config files and avoid committing tokens into version control.

docs/getting-started.md

@@ -0,0 +1,27 @@
+# Getting Started
+
+Install `99problems`:
+
+```bash
+npm install -g @mbe24/99problems
+# or
+cargo install problems99
+```
+
+Fetch a GitHub issue:
+
+```bash
+99problems get --repo schemaorg/schemaorg --id 1842
+```
+
+Search GitLab issues:
+
+```bash
+99problems get --platform gitlab -q "repo:veloren/veloren is:issue state:closed terrain"
+```
+
+Common next steps:
+
+- Configure a default instance in `~/.99problems` for fewer CLI flags
+- Use `--format jsonl --output-mode stream` for automation pipelines
+- Use the Read the Docs version selector to browse `latest`, `stable`, or a tagged release

docs/index.md

@@ -0,0 +1,21 @@
+# 99problems Documentation
+
+`99problems` is an AI-native CLI for retrieving issue and pull request context across GitHub, GitLab, Jira, and Bitbucket.
+
+Use this site for task-focused docs, and the repository README for the full project overview.
+
+## What you can find here
+
+- Setup and day-one usage in [Getting Started](getting-started.md)
+- Runtime and instance configuration in [Configuration](configuration.md)
+- Versioned documentation on Read the Docs (`latest`, `stable`, and release tags)
+
+## Documentation boundaries
+
+Public documentation is built from `docs/` and published on Read the Docs.
+Internal notes should stay under `docs/internal/`; they are intentionally excluded from public navigation and output.
+
+For complete project details and contributor workflows:
+
+- [Project README](https://github.com/mbe24/99problems/blob/main/README.md)
+- [Contributing Guide](https://github.com/mbe24/99problems/blob/main/CONTRIBUTING.md)

docs/internal/README.md

@@ -0,0 +1,5 @@
+# Internal Documentation
+
+This directory is for non-public documentation.
+
+Content under `docs/internal/` is intentionally excluded from the published MkDocs navigation and output.

docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs==1.6.1
+mkdocs-material==9.6.12

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: 99problems
+site_description: Documentation for the 99problems CLI
+site_url: https://99problems.readthedocs.io/
+repo_url: https://github.com/mbe24/99problems
+repo_name: mbe24/99problems
+edit_uri: edit/main/docs/
+docs_dir: docs
+strict: true
+
+exclude_docs: internal/**
+
+theme:
+  name: material
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md