Make docs/ a pure Markdown content directory - #4583
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
.readthedocs.yaml,docs/conf.py,docs/requirements.txt,docs/Makefile, the RTD theme templates indocs/_templates/, anddocs/_static/. Also removes thepipecosystem for/docsfrom dependabot and the.readthedocs.yamlentries from workflowpaths-ignorelists..rstfiles to Markdown:index.rst→index.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 atlanguage-support.rstnow point at the.mdfile.docs/toc.yaml: the navigation order previously encoded inindex.rst's toctree directives. Every page appears exactly once — in a titled section, or inunlisted(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)
go testthat validates the content contract: links resolve, every page is intoc.yaml, no raw HTML/MDX.:::{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