Create documentation site for yunjin #41

New issue

Open

opened 2026-09-13 02:14:40 +00:00 by agent-pi · 1 comment

agent-pi commented 2026-09-13 02:14:40 +00:00

Collaborator

Copy link

Problem

Yunjin has no documentation beyond the README. Installation, configuration (environment variables), the CLI commands, reader features (keyboard shortcuts, display settings, ignore rules, full text and featured images), and deployment are all undocumented — every answer lives in issue threads or chat history.

Goal

A Material-for-MkDocs documentation site modelled on cang's: versioned via mike, published to a pages branch, covering installation, configuration, CLI, the web reader, and container deployment.

## Problem Yunjin has no documentation beyond the README. Installation, configuration (environment variables), the CLI commands, reader features (keyboard shortcuts, display settings, ignore rules, full text and featured images), and deployment are all undocumented — every answer lives in issue threads or chat history. ## Goal A Material-for-MkDocs documentation site modelled on cang's: versioned via mike, published to a `pages` branch, covering installation, configuration, CLI, the web reader, and container deployment.

agent-pi commented 2026-09-13 02:15:02 +00:00

Author

Collaborator

Copy link

Findings

• cang's template: mkdocs.yml with Material theme (light/dark toggle, nav tabs/sections, search, copy-code), mike plugin for versioned docs (latest canonical), docs/ split by concern (index, install, config, web-ui, container, setup) plus assets, a pymdownx extension suite, and publishing via CI: uv run mike deploy --branch pages --push --update-aliases "$TAG_NAME" latest on release.
• yunjin's pyproject.toml dev group already ships the whole toolchain (mkdocs, mkdocs-material, mike, mkdocstrings + mkdocstrings-python, mkdocs-git-revision-date-localized-plugin, pymdown-extensions) — inherited when the dev group was assembled. Only mkdocs.yml, the docs/ content, and a publish step are missing.
• Docs site URL would follow cang's pattern (docs label/subdomain), with repo_url pointing at the forge.

Plan of attack

1. mkdocs.yml + skeleton: Material theme tuned to yunjin's identity (deuteranopia-safe palette), nav: Home / Installation / Configuration / CLI / Reader (shortcuts, display settings, ignore rules, full text, featured images) / Container.
2. Content pass: document the environment configuration (YUNJIN_LLM_*, YUNJIN_SECRET_KEY, YUNJIN_HTTP_USER_AGENT), every CLI command, and the reader features.
3. Publish step in CI: mike deploy --branch pages on tags (adapted from cang's ci.yml release job).
4. Optional: mkdocstrings API reference (toolchain already present).

Container docs depend on #40 landing first — the container page can be written concurrently but linked last.

Branch

feat/docs-site

Commits

1. :book: Add mkdocs skeleton with Material theme
2. :book: Document installation, configuration and CLI
3. :construction_worker: Publish versioned docs to the pages branch

## Findings - cang's template: `mkdocs.yml` with Material theme (light/dark toggle, nav tabs/sections, search, copy-code), `mike` plugin for versioned docs (`latest` canonical), `docs/` split by concern (index, install, config, web-ui, container, setup) plus assets, a pymdownx extension suite, and publishing via CI: `uv run mike deploy --branch pages --push --update-aliases "$TAG_NAME" latest` on release. - yunjin's `pyproject.toml` dev group **already ships the whole toolchain** (mkdocs, mkdocs-material, mike, mkdocstrings + mkdocstrings-python, mkdocs-git-revision-date-localized-plugin, pymdown-extensions) — inherited when the dev group was assembled. Only `mkdocs.yml`, the `docs/` content, and a publish step are missing. - Docs site URL would follow cang's pattern (`docs label`/subdomain), with `repo_url` pointing at the forge. ## Plan of attack 1. `mkdocs.yml` + skeleton: Material theme tuned to yunjin's identity (deuteranopia-safe palette), nav: Home / Installation / Configuration / CLI / Reader (shortcuts, display settings, ignore rules, full text, featured images) / Container. 2. Content pass: document the environment configuration (`YUNJIN_LLM_*`, `YUNJIN_SECRET_KEY`, `YUNJIN_HTTP_USER_AGENT`), every CLI command, and the reader features. 3. Publish step in CI: `mike deploy --branch pages` on tags (adapted from cang's `ci.yml` release job). 4. Optional: mkdocstrings API reference (toolchain already present). Container docs depend on #40 landing first — the container page can be written concurrently but linked last. ## Branch `feat/docs-site` ## Commits 1. `:book: Add mkdocs skeleton with Material theme` 2. `:book: Document installation, configuration and CLI` 3. `:construction_worker: Publish versioned docs to the pages branch`

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

0.4.0

0.3.0

0.2.0

0.1.0

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference

marvin8/yunjin#41

No description provided.