docs: migrate from Docsify to MkDocs Material for SEO/AEO#181
Merged
Conversation
The docs site was 100% client-side rendered (Docsify): crawlers received an empty "Loading..." shell, and hash routing (/#/page) meant the entire site was a single indexable URL even for JS-executing crawlers. AI crawlers (which don't execute JS) saw nothing at all. Now docs.gizmosql.com is pre-rendered static HTML built with MkDocs Material: - Real per-page URLs (/quickstart/ instead of /#/quickstart) with full HTML content, per-page <title>, and a generated sitemap.xml - robots.txt pointing at the sitemap - Raw Markdown sources published alongside the HTML (e.g. /quickstart.md) and indexed in a new llms.txt for answer engines - Legacy /#/page and /#/page?id=anchor links redirected client-side to the new URLs (docs/js/hash-redirect.js) - documentation.md renamed to index.md (the homepage) - CI builds with "mkdocs build --strict", which fails on broken internal links/anchors - it already caught one genuinely broken link in integrations.md that Docsify served silently - update_docs_version.sh publish-time version sync works unchanged - mkdocs-material pinned <10 (Material team has flagged MkDocs 2.0 as backward-incompatible) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
Summary
Migrates docs.gizmosql.com from client-side-rendered Docsify to pre-rendered MkDocs Material, fixing SEO and AEO:
<div id="app">Loading...</div>; AI crawlers (no JS execution) saw nothing, and Docsify's hash routing (/#/page) made the whole site one indexable URL even for Google./quickstart/), per-page<title>, generatedsitemap.xml, androbots.txt.Changes
mkdocs.yml— Material theme config; nav translated 1:1 from_sidebar.md(light/dark toggle, search, code copy, edit-on-GitHub)deploy-docs.yml— builds withmkdocs build --strict(fails on broken internal links/anchors) and deployssite/; the publish-timeupdate_docs_version.shQuick Start version sync is unchanged/quickstart.md) and indexed in a newllms.txtfor answer enginesdocs/js/hash-redirect.jsredirects legacy/#/pageand/#/page?id=anchorlinks to the new URLs (mapping logic unit-tested)documentation.md→index.md(homepage); removedindex.html,_sidebar.md,_navbar.mdintegrations.mdthat was already broken under Docsify and caught by strict validationmkdocs-materialpinned>=9,<10(Material team has flagged MkDocs 2.0 as backward-incompatible — revisit on Material 10)Test plan
mkdocs build --strictpasses locally (no warnings)CNAME,llms.txt,robots.txt,sitemap.xmlpresent in built site#configuration-environment-variables) verified in built HTML?id=anchors anddocumentation→ home)VIEW_DOCS_LOCALLY.md,websocket-migration-plan.md) absent from outputmkdocs serve/#/link🤖 Generated with Claude Code