Add Jekyll config for GitHub Pages doc rendering#151
Conversation
Adds docs/_config.yml with Cayman theme (same as SandGNAT) so all markdown files in docs/ render as styled HTML pages on GitHub Pages. Site quadrant links now use relative paths (tutorials/, how-to/, reference/, explanation/) which Jekyll resolves to the rendered README.md index pages. No front matter needed — Cayman handles it. https://claude.ai/code/session_01H5UbjsuiiGya5n1eUCxoaR
There was a problem hiding this comment.
Pull request overview
Adds a Jekyll configuration under docs/ to enable GitHub Pages rendering with the Cayman theme, and updates the docs landing page to link to section roots intended to be resolved by Jekyll-generated pages.
Changes:
- Add
docs/_config.ymlto configure GitHub Pages/Jekyll (Cayman theme, kramdown settings, include/exclude lists). - Update
docs/index.htmlquadrant links from GitHub “blob” URLs to relative section URLs (tutorials/,how-to/,reference/,explanation/).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/index.html | Switches doc quadrant links to relative section-root paths for Pages routing. |
| docs/_config.yml | Introduces Jekyll/Cayman configuration intended to render markdown docs on GitHub Pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <td><a href="tutorials/">Tutorials</a><br>Guided, newcomer-safe walkthroughs.</td> | ||
| <td><a href="explanation/">Explanation</a><br>Architecture, rationale, and design choices.</td> | ||
| </tr> | ||
| <tr> | ||
| <th>Working</th> | ||
| <td><a href="https://github.com/wrhalpin/GNAT/blob/main/docs/how-to/README.md">How-to guides</a><br>Task-focused procedures and recipes.</td> | ||
| <td><a href="https://github.com/wrhalpin/GNAT/blob/main/docs/reference/README.md">Reference</a><br>Exact technical behavior, config, and interfaces.</td> | ||
| <td><a href="how-to/">How-to guides</a><br>Task-focused procedures and recipes.</td> | ||
| <td><a href="reference/">Reference</a><br>Exact technical behavior, config, and interfaces.</td> |
There was a problem hiding this comment.
These links now point to directory roots (e.g., "tutorials/") but the target directories currently only contain README.md (no index.md/index.html). Unless the Pages build enables README→index behavior, these will 404. Consider adding an explicit index page in each section directory (or otherwise ensuring README.md is published as the directory index) so the links resolve reliably.
| kramdown: | ||
| input: GFM | ||
| syntax_highlighter: rouge | ||
|
|
There was a problem hiding this comment.
If the docs site is expected to render/route section README.md files as landing pages, note that many existing docs link to other sections via paths ending in "README.md" (e.g., ../how-to/README.md). Jekyll typically won’t serve those source .md URLs, so cross-links may break unless you add/link-rewriting support (or standardize links to section directory URLs like "../how-to/").
| plugins: | |
| - jekyll-relative-links | |
| relative_links: | |
| enabled: true | |
| collections: true |
| exclude: | ||
| - README.md | ||
| - Gemfile | ||
| - Gemfile.lock | ||
| - node_modules | ||
| - vendor |
There was a problem hiding this comment.
Excluding "README.md" here prevents docs/README.md from being part of the built site, which conflicts with the goal of having all docs markdown render on Pages. If the intent is only to avoid using docs/README.md as an index, consider removing this exclusion (or narrowing it explicitly) and rely on index.html to control the landing page.
Adds docs/_config.yml with Cayman theme (same as SandGNAT) so all markdown files in docs/ render as styled HTML pages on GitHub Pages. Site quadrant links now use relative paths (tutorials/, how-to/, reference/, explanation/) which Jekyll resolves to the rendered README.md index pages. No front matter needed — Cayman handles it.
https://claude.ai/code/session_01H5UbjsuiiGya5n1eUCxoaR