docs: let contributors preview the documentation site locally - #1501
Open
masiarek wants to merge 2 commits into
Open
docs: let contributors preview the documentation site locally#1501masiarek wants to merge 2 commits into
masiarek wants to merge 2 commits into
Conversation
Editing docs today means pushing and waiting for GitHub Pages to rebuild --
"Adding Documentation" only describes the GitHub web-UI flow. This adds a
one-command local preview so writers can see a page before they open a PR.
The docs aren't part of docker-compose.yml (that runs the app: backend,
database, Keycloak). GitHub Pages builds them straight from docs/, so previewing
means running Jekyll. One `docker run` is enough:
docker run --rm -v "$PWD":/site -w /site -p 4000:4000 ruby:2.7 \
sh -c "bundle install && bundle exec jekyll serve --host 0.0.0.0 --port 4000"
Changes:
- docs/Gemfile -- installs the github-pages gem, the same one Pages runs, so a
local build matches production. ffi is pinned < 1.17 because newer versions
require Ruby >= 3.0 and won't resolve against the Ruby 2.7 that
github-pages' Jekyll 3.9 expects.
- docs/_config.yml -- adds `repository:`. jekyll-github-metadata refuses to
build without knowing which repo it is, and normally reads that from the
origin remote; the command above mounts only docs/, so .git sits outside the
container. Setting it in config makes the preview work with no env var.
Inert in production -- Pages already knows the repo, and site.github isn't
referenced anywhere in these templates.
- docs/.gitignore -- keeps _site/, .jekyll-cache/ and Gemfile.lock out of the
repo.
- 4_adding_documentation.md -- a "Previewing your changes locally" section with
the command, a named-volume variant so gem installs are cached between runs,
and troubleshooting for the three errors you actually hit (the missing repo
name, the ffi/Ruby conflict, and the unmaintained jekyll/jekyll images whose
tags no longer exist).
Verified: full site builds and serves at localhost:4000 with the theme, logo,
colour scheme, search and nav intact, and every existing page returning 200.
The "Bold" example on Updating Website Text renders as
voting_end: '**Voting ends on **'
on the live site -- the {{datetime, datetime}} is missing. Jekyll runs Liquid
over page source before Markdown, and that happens inside fenced code blocks
too, so Liquid parses the {{...}} as an output tag, fails on the comma, and
substitutes nothing. The page teaching contributors how templated text works is
the one place the example really has to survive.
The same page already handles this correctly in its other two examples (lines 31
and 38), which are wrapped in {% raw %}. This applies the same wrapper to the
third, which was missed.
Surfaced by the local preview added in the previous commit -- Jekyll prints
"Liquid Warning: Liquid syntax error (line 62): Expected end_of_string but found
comma" on every build, which nobody sees when editing through the GitHub web UI.
✅ Deploy Preview for bettervoting ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (5)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe documentation site now includes Bundler and GitHub Pages configuration. Jekyll artifacts and Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
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.
Editing through the GitHub web UI stays the right default for most doc changes — a typo, a sentence, a link fix. Nothing here changes that flow, and Adding Documentation still leads with it.
This adds a second option for the larger cases: creating new pages, or moving things around. There, three things aren't visible in the browser:
parent:has to match the parent page'stitle:character-for-character, emoji included — the guide already warns "Make sure this matches exactly otherwise your file won't be accessbile!" You currently find out by pushing and waiting for Pages.So: a one-command local preview, for when you want it.
Then open http://localhost:4000. Edits rebuild automatically.
Worth noting the docs aren't part of
docker-compose.yml— that runs the app (backend, database, Keycloak). Pages builds these straight fromdocs/, so previewing them means running Jekyll separately.What's here
docs/Gemfile— installs thegithub-pagesgem, the same one Pages runs, so a local build matches production.ffiis pinned< 1.17because newer versions require Ruby >= 3.0 and won't resolve against the Ruby 2.7 thatgithub-pages' Jekyll 3.9 expects.docs/_config.yml— addsrepository:.jekyll-github-metadatarefuses to build without knowing which repo it is, and normally reads that from theoriginremote; the command above mounts onlydocs/, so.gitsits outside the container. Setting it in config makes the preview work with no env var. Inert in production — Pages already knows the repo, andsite.githubisn't referenced anywhere in these templates. (Happy to drop this and document-e PAGES_REPO_NWO=...on the command instead, if you'd rather keep published config untouched.)docs/.gitignore— keeps_site/,.jekyll-cache/andGemfile.lockout of the repo.4_adding_documentation.md— a "Previewing your changes locally" section, added after the existing guidance rather than replacing it: the command, a named-volume variant that caches gems between runs, and troubleshooting for the three errors you actually hit (the missing repo name, theffi/Ruby conflict, and the unmaintainedjekyll/jekyllimages whose expected tags no longer exist).Second commit: a small bug this turned up
The "Bold" example on Updating Website Text currently renders on the live site as:
The
{{datetime, datetime}}is missing. Jekyll runs Liquid over page source before Markdown, and that happens inside fenced code blocks too — so Liquid parses the{{...}}as an output tag, fails on the comma, and substitutes nothing. Since that page is what teaches contributors how templated text works, the example is worth having survive.The same page already handles this correctly in its other two examples (lines 31 and 38), which are wrapped in
{% raw %}— this applies the same wrapper to the third. Jekyll printsLiquid Warning: Liquid syntax error (line 62): Expected end_of_string but found commaon every build.Split into its own commit in case you'd prefer it as a separate PR.
Verified
Full site builds and serves at
localhost:4000with the theme, logo, colour scheme, search and nav intact, and every existing page returning 200. Cold start installs the gem set (a few minutes); with the named-volume cache, rebuilds are ~7 seconds.