GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Make docs/ a pure Markdown content directory by kyleconroy · Pull Request #4583 · sqlc-dev/sqlc

Conversation

@kyleconroy

@kyleconroy kyleconroy commented Aug 26, 2026

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.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 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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@claude
Make docs/ a pure Markdown content directory
1638aa5
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 <[email protected]>
Claude-Session: https://claude.ai/code/session_013XDcHxZk9UzfzMLayG66Zq
@kyleconroy
kyleconroy merged commit fbf130e into main Aug 26, 2026
13 checks passed

Uh oh!

There was an error while loading. Please reload this page.

@kyleconroy
kyleconroy deleted the claude/docs-website-alternatives-naaa6t branch August 26, 2026 20:28
@kyleconroy kyleconroy mentioned this pull request Aug 26, 2026
Add a Go linter for the docs/ content contract #4584
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

2 participants

@kyleconroy @claude
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.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.