Skip to content

Make docs/ a pure Markdown content directory - #4583

Merged
kyleconroy merged 1 commit into
mainfrom
claude/docs-website-alternatives-naaa6t
Aug 26, 2026
Merged

Make docs/ a pure Markdown content directory#4583
kyleconroy merged 1 commit into
mainfrom
claude/docs-website-alternatives-naaa6t

Conversation

@kyleconroy

Copy link
Copy Markdown
Collaborator

First step toward moving the documentation site off Read the Docs: docs/ becomes a plain Markdown content directory with no rendering toolchain in this repo. A separate repo will consume it and build the website.

Changes

  • Remove all Read the Docs / Sphinx configuration: .readthedocs.yaml, docs/conf.py, docs/requirements.txt, docs/Makefile, the RTD theme templates in docs/_templates/, and docs/_static/. Also removes the pip ecosystem for /docs from dependabot and the .readthedocs.yaml entries from workflow paths-ignore lists.
  • Port the three remaining .rst files to Markdown: index.rstindex.md, reference/language-support.rst.md (rst grid tables → GFM tables), guides/using-go-and-pgx.rst.md. Admonitions use GitHub alert syntax (> [!NOTE]), which renders natively on github.com and stays a plain blockquote for any CommonMark parser. The three tutorial links that pointed at language-support.rst now point at the .md file.
  • Add docs/toc.yaml: the navigation order previously encoded in index.rst's toctree directives. Every page appears exactly once — in a titled section, or in unlisted (published but not in the sidebar, matching the three migration guides' current behavior). Verified 1:1 against the 41 files on disk.

Follow-ups (not in this PR)

  • A Go-based linter (goldmark) run from go test that validates the content contract: links resolve, every page is in toc.yaml, no raw HTML/MDX.
  • The consuming repo that builds and deploys the site.
  • The remaining MyST admonitions (:::{note} etc.) in a few howto pages can be converted to GitHub alert syntax when the linter lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq


Generated by Claude Code

Remove the Read the Docs and Sphinx configuration (.readthedocs.yaml,
conf.py, requirements.txt, Makefile, theme templates and static assets)
along with the docs pip ecosystem in dependabot and the .readthedocs.yaml
entries in workflow paths-ignore lists.

Port the three remaining reStructuredText files to Markdown:
index.rst becomes index.md, and language-support and using-go-and-pgx
are now GitHub-flavored Markdown using alert-style admonitions. Links
that pointed at .rst files now point at their .md replacements.

Add docs/toc.yaml, which declares the navigation order previously held
in index.rst's toctree directives: every page appears exactly once,
either in a titled section or in the unlisted set. This file is the
contract a docs site consumer reads, and a future Go-based linter will
enforce it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq
@kyleconroy
kyleconroy merged commit fbf130e into main Aug 26, 2026
13 checks passed
@kyleconroy
kyleconroy deleted the claude/docs-website-alternatives-naaa6t branch August 26, 2026 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants