Website

[feloy]

Implements a static documentation website using MkDocs that automatically
splits README.md into multiple pages based on level 2 headings. The site
is deployed to GitHub Pages via GitHub Actions on every merge to main.

Closes #95

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a MkDocs-based documentation site with a hook that splits README.md into pages, supporting files and config, and a GitHub Actions workflow that builds and deploys the generated site to GitHub Pages.

Changes

Cohort / File(s)	Summary
GitHub Actions Deployment \.github/workflows/deploy-docs.yml	New workflow deploy-docs triggered on pushes to main (README.md, website/**, workflow file) and manual runs; two jobs: build (Ubuntu runner, checkout, Python 3.12, pip cache, install website/requirements.txt, mkdocs build --strict --verbose, upload ./website/site artifact) and deploy (depends on build, deploys artifact to GitHub Pages via actions/deploy-pages, exposes page URL).
MkDocs Configuration & Requirements website/mkdocs.yml, website/requirements.txt, website/WEBSITE.md	Adds MkDocs site config (Material theme, plugins, Markdown extensions, docs/site dirs, hook reference), pinned Python deps for MkDocs/material/minify and image libs, and WEBSITE.md describing generation, local preview, and deployment behavior.
README-to-pages Hook website/hooks.py	New MkDocs hook that splits repository README.md into an initial Home section and one page per ## heading; writes temporary <slug>.md files into docs_dir, injects File objects into MkDocs build, rebuilds nav with generated pages, and removes generated files in on_post_build.
Repo housekeeping & placeholders .gitignore, website/docs/.gitkeep	Adds ignore rule for website/site/ and website/docs/*.md; adds .gitkeep in website/docs/ documenting that Markdown files are generated from README.md.

Sequence Diagram(s)

sequenceDiagram
  participant Dev as Developer (push / workflow_dispatch)
  participant GH as GitHub Actions Runner
  participant Repo as Repository
  participant Build as Build job (ubuntu-24.04)
  participant Artifact as Actions Upload Artifact
  participant Deploy as Deploy job (actions/deploy-pages)
  participant Pages as GitHub Pages

  Dev->>GH: trigger workflow
  GH->>Repo: checkout
  GH->>Build: start build job
  Build->>Repo: read README.md, website/hooks.py, website/mkdocs.yml
  Build->>Build: setup Python 3.12, install deps
  Build->>Build: mkdocs build --strict --verbose (hooks split README -> docs/*.md)
  Build->>Artifact: upload ./website/site artifact
  Artifact->>Deploy: artifact available
  GH->>Deploy: start deploy job (env: github-pages)
  Deploy->>Pages: actions/deploy-pages -> publish artifact
  Pages-->>Dev: pages URL (deployment output)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Website' is vague and generic, lacking specificity about the main change (MkDocs documentation setup and GitHub Pages deployment).	Consider a more descriptive title like 'Add MkDocs documentation site with GitHub Pages deployment' to clearly convey the primary change.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	All requirements from issue #95 are addressed: MkDocs usage [#95], README splitting at level 2 headings [#95], GitHub Pages deployment via GitHub Actions [#95], and SEO optimization through Material theme [#95].
Out of Scope Changes check	✅ Passed	All changes are directly related to the issue objectives: MkDocs configuration, README splitting hook, GitHub Pages deployment workflow, and dependency management for the documentation site.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description accurately describes the implementation of a static documentation website using MkDocs with automatic README splitting and GitHub Pages deployment, matching the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

website/mkdocs.yml (1)

26-26: Consider removing or adjusting edit_uri for generated content.

Since documentation pages are dynamically generated from README.md by hooks.py, the edit links will point to non-existent files (e.g., edit/main/installation.md). Consider either:

• Removing edit_uri to disable edit links, or
• Setting it to point to the README: edit_uri: blob/main/README.md

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@website/mkdocs.yml` at line 26, The mkdocs configuration sets edit_uri:
edit/main/ which creates edit links for generated pages that don't exist; update
mkdocs.yml to either remove the edit_uri entry entirely to disable edit links,
or change it to point to the actual source README used by hooks.py (e.g., set
edit_uri to blob/main/README.md) so generated pages resolve to README.md; check
hooks.py and the generated filenames (like installation.md) to ensure the chosen
edit_uri maps to a real repo path.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@website/hooks.py`:
- Around line 160-164: The README lookup in on_nav uses a different path
calculation than on_files, causing misses for relative docs_dir; update the
readme_path calculation in the on_nav function to mirror on_files by resolving
the docs_dir before walking up directories (e.g., use
Path(config['docs_dir']).resolve().parent.parent / 'README.md' instead of
Path(config['docs_dir']).parent / 'README.md') so readme_path consistently
points to the repository root README.md and preserves the existing not-exists
early return.
- Around line 76-86: When building sections in hooks.py (inside the block that
creates current_section using title = line[3:].strip() and slug =
slugify(title)), detect duplicate slugs by tracking seen slugs (e.g., a set or
dict keyed by slug) and if a slug is already present, append a numeric suffix
(slug-2, slug-3, etc.) to produce a unique slug before assigning
current_section['slug'] and appending to sections; update the tracker for each
generated unique slug so subsequent duplicates get incremented suffixes.

In `@website/requirements.txt`:
- Around line 27-28: The requirements file pins vulnerable versions of pillow
and cairosvg; update the entries for pillow and cairosvg in
website/requirements.txt by changing the pinned versions from pillow==11.1.0 to
pillow==12.1.1 and from cairosvg==2.7.1 to cairosvg==2.9.0, then run your
dependency installer/lock regen (e.g., pip install -r requirements.txt / update
lockfile) and run tests to ensure nothing breaks.

---

Nitpick comments:
In `@website/mkdocs.yml`:
- Line 26: The mkdocs configuration sets edit_uri: edit/main/ which creates edit
links for generated pages that don't exist; update mkdocs.yml to either remove
the edit_uri entry entirely to disable edit links, or change it to point to the
actual source README used by hooks.py (e.g., set edit_uri to
blob/main/README.md) so generated pages resolve to README.md; check hooks.py and
the generated filenames (like installation.md) to ensure the chosen edit_uri
maps to a real repo path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7730efe8-4bff-4c99-a0f0-846cfb33f771

📥 Commits

Reviewing files that changed from the base of the PR and between ab7f5f2 and b4efcac.

📒 Files selected for processing (7)

• .github/workflows/deploy-docs.yml
• .gitignore
• website/WEBSITE.md
• website/docs/.gitkeep
• website/hooks.py
• website/mkdocs.yml
• website/requirements.txt