Skip to content

Latest commit

 

History

History
81 lines (56 loc) · 2.94 KB

local_previews.md

File metadata and controls

81 lines (56 loc) · 2.94 KB
Raw

Working with the repo locally

Content-only changes can often be done directly on the GitHub website. Changes affecting the function or structure of the site should be previewed fully locally before being submitted via PR.

Jekyll

To preview the site locally, clone it.

Then you'll need to install jekyll.

Then go to the root of the site and issue (just once):

$ bundle install

which will install the necessary Ruby gems (the info for this is included in the repo files).

And then (also in the top level directory of your forked repository) to be able to see the rendered website, run

$ jekyll serve
# or
$ bundle exec jekyll serve

and open your browser to http://localhost:4000. If you are having trouble try rm -rf _site, followed by bundle update, then bundle exec jekyll serve.

Container-based development

You can build and run a Docker container to preview the site locally and support a local development workflow. If you do not already have Docker installed, please visit https://docs.docker.com/get-docker/ and follow the links to get started with Docker on your operating system.

These instructions also work with the Podman container management tool simply by substituting podman for docker in the commands below. This can either be done manually, by creating a shell alias (e.g., alias podman=docker), or by installing a package such as podman-docker to automatically handle this translation.

Build the container image:

docker build -t us-rse-website:latest .

Run the container to access the website at the URL http://127.0.0.1:4000/

$ docker run --rm -it -p 4000:4000 us-rse-website:latest
Configuration file: /srv/jekyll/_config.yml
            Source: /srv/jekyll
       Destination: /srv/jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
       Jekyll Feed: Generating feed for posts
                    done in 6.215 seconds.
 Auto-regeneration: enabled for '/srv/jekyll'
LiveReload address: http://0.0.0.0:35729
    Server address: http://0.0.0.0:4000/
  Server running... press ctrl-c to stop.

To develop the website, launch the container using the following command, where the source files are mounted into the container:

docker run --rm -it -p 4000:4000 \
    -u $(id -u):$(id -g) \
    -v $(pwd):/srv/jekyll:Z \
    us-rse-website:latest

or, if using Podman in a rootless environment:

podman run --rm -it -p 4000:4000 \
    --userns=keep-id \
    -v $(pwd):/srv/jekyll:Z \
    us-rse-website:latest

If these commands fail, you may need to address any discrepancies between the user/group mapping in your container runtime and the permissions on the directory where the volume mount resides.

Edit a source file and save the changes. You will see Jekyll automatically regenerate the site, after which you can reload the page in your browser to see the rendered changes.