diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..3eab9ad1f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,10 @@ +# Local Jekyll preview artifacts — see contributions/writers/4_adding_documentation.md +_site/ +.jekyll-cache/ +.jekyll-metadata +vendor/ + +# Not committed on purpose: the lockfile resolves differently per platform and +# Ruby version, and GitHub Pages ignores it anyway (it builds with its own +# pinned gem set). Leaving it out keeps contributors from fighting over it. +Gemfile.lock diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 000000000..a666ad7e6 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,10 @@ +source "https://rubygems.org" + +# The same gem GitHub Pages runs, so a local preview matches production. +# It pins Jekyll 3.9 and bundles the plugins Pages enables by default, +# including jekyll-remote-theme (needed for `remote_theme:` in _config.yml). +gem "github-pages", group: :jekyll_plugins + +# ffi >= 1.17 requires Ruby >= 3.0, which conflicts with the Ruby 2.7 that +# github-pages' Jekyll 3.9 expects. Without this pin bundler fails to resolve. +gem "ffi", "< 1.17" diff --git a/docs/_config.yml b/docs/_config.yml index 9c2c2e8b8..5dbcc1dbf 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,6 +2,12 @@ remote_theme: just-the-docs/just-the-docs color_scheme: custom logo: images/logo.png +# Lets the Pages plugins identify the repo without inspecting a git remote, so a +# local preview works when only the docs/ folder is mounted (see +# contributions/writers/4_adding_documentation.md). No effect on the published +# site, which already knows which repo it is building. +repository: Equal-Vote/bettervoting + # https://github.com/just-the-docs/just-the-docs/discussions/1583 callouts_level: quiet # or loud diff --git a/docs/contributions/writers/2_updating_website_text.md b/docs/contributions/writers/2_updating_website_text.md index d0f64a8a0..725810ffc 100644 --- a/docs/contributions/writers/2_updating_website_text.md +++ b/docs/contributions/writers/2_updating_website_text.md @@ -66,7 +66,7 @@ You can use the ``[ text ]( url )`` pattern whenever you want to include hyperli ### Bold ``` -voting_end: '**Voting ends on {{datetime, datetime}}**' +voting_end: '**Voting ends on {% raw %}{{datetime, datetime}}{% endraw %}**' ``` The above example bolds the text by adding ``** ... **`` around it diff --git a/docs/contributions/writers/4_adding_documentation.md b/docs/contributions/writers/4_adding_documentation.md index 0e980f4ed..079efcf09 100644 --- a/docs/contributions/writers/4_adding_documentation.md +++ b/docs/contributions/writers/4_adding_documentation.md @@ -40,6 +40,36 @@ These variables indicate the title of the document as well as where it's located * ``parent: ✍️Writers`` is the title field from the parent document. Make sure this matches exactly otherwise your file won't be accessbile! * ``has_children: true`` is an optional field that should be added to documents that should be a folder for other documents +## Previewing your changes locally + +For a typo or a quick wording change, editing on GitHub as described above is the easiest way — you don't need any of this. + +It's more useful when you're **adding a new page or moving things around**. GitHub's preview shows you Markdown, but not this site: it won't show where your page lands in the sidebar, and it won't tell you whether the ``parent:`` in your header matched. If you have Docker, you can run the whole documentation site on your own machine and see exactly what gets published. + +Note that the docs are **not** part of the app's ``docker-compose.yml`` — that runs the website itself (backend, database, Keycloak), not this site. These pages are built by GitHub Pages straight from the ``docs/`` folder, so previewing them means running Jekyll yourself. + +From inside the ``docs/`` directory, run: + +```bash +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" +``` + +Then open [http://localhost:4000](http://localhost:4000). Edit any ``.md`` file and Jekyll rebuilds it automatically — just refresh the page. Press ``Ctrl+C`` to stop the server. + +The first run downloads and installs the gems, which takes a few minutes. To keep them between runs so later starts are quick, add a named volume: + +```bash +docker run --rm -v "$PWD":/site -w /site -v bvdocs-gems:/usr/local/bundle -p 4000:4000 ruby:2.7 sh -c "bundle install && bundle exec jekyll serve --host 0.0.0.0 --port 4000" +``` + +The ``Gemfile`` in this directory installs the ``github-pages`` gem, which is the same gem GitHub Pages runs. That way what you see locally matches what gets published. + +### Troubleshooting + +* **"No repo name found. Specify using PAGES_REPO_NWO..."** — one of the Pages plugins needs to know which repository it's building. It usually reads that from your ``origin`` git remote, but the command above only mounts the ``docs/`` folder, and ``.git`` lives a level up outside the container. That's why ``_config.yml`` sets ``repository: Equal-Vote/bettervoting``. If you've removed that line or you're building a copy of this folder somewhere else, add ``-e PAGES_REPO_NWO=Equal-Vote/bettervoting`` to the ``docker run`` command instead. +* **Bundler says ``ffi`` is incompatible with your Ruby version** — make sure you're using ``ruby:2.7`` as shown above. The ``Gemfile`` pins ``ffi`` for exactly this reason, but a newer Ruby image will still pull in other gems that don't match Jekyll 3.9. +* **Don't use the ``jekyll/jekyll`` Docker images** — they're no longer maintained, and the tags you'd expect (like ``3.9``) don't exist anymore. The ``ruby:2.7`` image plus the ``github-pages`` gem is what this site actually builds with. + ## Tips After you've added new documentation pages, it could be good to link to it from info bubbles so that your page will be more discoverable. Follow [the steps at 'updating website text'](2_updating_website_text#tips-and-info-bubbles) to learn more. \ No newline at end of file