docs: let contributors preview the documentation site locally

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

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"

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

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

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.