Sortie Documentation

Source for docs.sortie-ai.com

Sortie turns issue tracker tickets into autonomous coding agent sessions. This repository contains all the source code and content for the Sortie documentation site.

Read the Docs · Report an Issue · Main Repository

---

About Sortie

Sortie is an autonomous coding agent orchestrator. Engineers manage work at the ticket level — Sortie handles the rest: isolated workspaces, retry logic, state reconciliation, tracker integration, and cost tracking. Single binary, zero dependencies, SQLite persistence.

For a full overview, see the product documentation.

Tech Stack

Component	Details
Static site generator	MkDocs 1.6.1
Theme	mkdocs-shadcn 0.10.2 (Tailwind CSS)
Markdown extensions	pymdownx (highlight, superfences, tabbed, details, arithmatex), admonition, footnotes, tables, toc
Plugins	search, git-revision-date-localized
Deployment	Cloudflare Workers (static assets)
Analytics	Google Analytics GA4 with GDPR-compliant cookie consent
Python	≥ 3.13, managed via uv

Prerequisites

• Python ≥ 3.13
• uv — fast Python package manager
• Git — required for git-revision-date-localized plugin

Local Development

Clone the repository and start the dev server:

git clone https://github.com/sortie-ai/sortie-docs.git
cd sortie-docs

asdf install        # install Python (skip if Python ≥3.13 is already available)
uv sync             # install all dependencies from pyproject.toml
uv run mkdocs serve # start dev server at http://127.0.0.1:8000

Open http://127.0.0.1:8000 in your browser. MkDocs watches for file changes and reloads automatically.

Build for Production

uv run mkdocs build   # outputs to site/

The generated static site in site/ is deployed to Cloudflare Workers via Wrangler:

npx wrangler deploy

Repository Structure

sortie-docs/
├── docs/                        # All documentation content (Markdown)
│   ├── index.md                 # Homepage
│   ├── changelog.md             # Release history
│   ├── getting-started/         # Installation, Quick Start, Jira Integration, End-to-End
│   ├── guides/                  # How-to guides (SSH scaling, monitoring, hooks, etc.)
│   ├── reference/               # CLI, Workflow config, API, Prometheus metrics, errors
│   ├── downloads/               # Downloadable assets (Grafana dashboard JSON)
│   ├── img/                     # Images, favicons, OG image
│   ├── stylesheets/             # Custom CSS (cookieconsent, overrides)
│   └── javascripts/             # Custom JS (feedback widget, cookie consent, mermaid)
├── overrides/                   # MkDocs theme overrides (Jinja2 templates)
│   ├── main.html                # Root template (fonts, head, conditional assets)
│   ├── components/icon.html     # Custom logo (dark/light mode)
│   └── templates/
│       ├── seo.html             # JSON-LD structured data, OG/Twitter meta
│       └── page.html            # Page layout
├── hooks/
│   └── sitemap_dates.py         # MkDocs hook: git dates → sitemap <lastmod>
├── mkdocs.yml                   # MkDocs configuration (nav, theme, plugins, extensions)
├── pyproject.toml               # Python project metadata and dependencies
├── requirements.txt             # Pinned dependencies (auto-generated by uv)
├── wrangler.toml                # Cloudflare Workers deployment config
└── package.json                 # Node.js deps (Wrangler)

Contributing

We welcome contributions from the community — whether it's fixing a typo, improving a guide, or adding new content.

Quick Edits

For small fixes (typos, broken links, wording improvements), edit the file directly on GitHub and open a Pull Request.

Adding a Page

1. Create a new .md file in the appropriate docs/ subdirectory.
2. Add the page to the nav section in mkdocs.yml.
3. Preview locally with uv run mkdocs serve.
4. Push your branch — Cloudflare deploys automatically on merge to main.

Adding a Plugin

uv add <plugin-name>
uv export --no-hashes --no-dev -o requirements.txt
# Then add the plugin to the plugins section in mkdocs.yml

Content Guidelines

• Documentation follows the Diátaxis framework — tutorials, how-to guides, reference, and explanation are kept separate by intent.
• Write in clear, concise English aimed at senior engineers and DevOps practitioners.
• Use admonitions for warnings, tips, and notes.
• Include cross-links to related pages (installation → quick start → reference).
• Every page should have title, description, and keywords in its front matter.

Related

Link	Description
sortie-ai/sortie	Main project — the Sortie orchestrator binary
sortie-ai/homebrew-tap	Homebrew Tap for Sortie
Architecture spec	Internal engineering reference

License

Documentation text is licensed under CC BY 4.0. Code examples and configuration samples are licensed under Apache 2.0.

See LICENSE for full details.