docs: migrate documentation from Jekyll to mdBook#50
Merged
Conversation
Closes #47. Replaces the Jekyll-based docs site with mdBook for cleaner navigation, built-in search, and faster builds. - Add book.toml (src = ".", light/navy themes, repo URL) - Add SUMMARY.md grouping pages into Getting Started, Guides, Reference - Strip Jekyll frontmatter (layout/title/nav_order) from all 13 doc pages - Rewrite internal links from bare slugs to .md extensions for mdBook - Add theme/head.hbs to wire favicon.ico and Open Graph / Twitter Card meta tags (mdBook does not emit these natively); og:image points at the absolute https://blogat.to/og_preview.jpeg URL for social scrapers - Replace Jekyll with mdBook in the GitHub Pages deploy workflow (peaceiris/actions-mdbook@v2 -> upload-pages-artifact -> deploy-pages) - Remove _config.yml and _includes/ - Preserve CNAME (blogat.to), favicon.ico, logo.png, og_preview.jpeg (auto-copied by mdBook from src to book/) - Gitignore docs/book/ - Document the new structure, the SUMMARY.md registration rule, and the theme/head.hbs conventions in CLAUDE.md
|
✔️ 75a3c60 - Conventional commits check succeeded. |
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
peaceiris/actions-mdbook->upload-pages-artifact->deploy-pages. Triggers on push tomainfordocs/**and on manual dispatch.docs/theme/head.hbsto wire the existingfavicon.icoand Open Graph / Twitter Card meta tags, which mdBook does not emit natively.Changes
docs/book.toml: mdBook config (src = ".", light/navy themes, repo URL).docs/SUMMARY.md: sidebar/TOC grouping the existing pages into Getting Started, Guides, Reference.(getting-started)) to.mdextensions (e.g.(getting-started.md)) so mdBook resolves them.docs/theme/head.hbs: injects<link rel="icon" href="favicon.ico">(resolved viapath_to_root) plusog:title/og:description/og:image/og:url/og:typeand matching Twitter Card tags.og:imageuses the absolutehttps://blogat.to/og_preview.jpegURL (required by social scrapers)._config.ymland_includes/.CNAME(blogat.to),favicon.ico,logo.png,og_preview.jpeg— mdBook auto-copies non-.mdfiles from src tobook/..gitignore: ignoredocs/book/.CLAUDE.md: new Documentation section documenting the structure, the SUMMARY.md registration rule, the.mdlink convention, thetheme/head.hbshead injection, and local preview commands.Test plan
mdbook build docsruns cleanly with no warnings.<link rel="icon" href="favicon.ico">and OG/Twitter meta tags appear inbook/index.html.og:titleincludeschapter_title(e.g.Getting started · Blogatto).path_to_rootresolves correctly on subpages.CNAME,favicon.ico,logo.png,og_preview.jpegare copied tobook/.blogat.toserves the new mdBook site.