Our front end development uses the templating engine Jekyll. This tool lets you write page content in Markdown, and use simple logic to convert this into HTML. It’s also the tool used by Github Pages, a free web hosting option that is part of Github, and so is a useful tool to be familiar with for anyone that works with code in Github.
gem install jekyllfrom your terminal
cd docsto change into the
jekyll serve --incrementalto build a copy of the website and view it through a local server. The
--incrementalflag tells Jekyll that when you save a file it should regenerate just the part of the website affected by the save. You should see something like this (there may be some additional lines):
Generating... done in 2.877 seconds. Auto-regeneration: enabled for '.../housing-insights/docs' Server address: http://127.0.0.1:4000 Server running... press ctrl-c to stop.
Server address:output above - in this example it is
http://127.0.0.1:4000. This will show you a copy of the website using the current code on your computer.
Every time you save a file in the
docs folder, Jekyll will rebuild the website using your changes. Keep the command prompt running where you entered the above commands - every time you save a file, you should see a message like this:
Regenerating: 1 file(s) changed at 2017-09-05 11:01:47 ...done in 2.7698 seconds. Regenerating: 1 file(s) changed at 2017-09-05 11:05:09 ...done in 2.227318 seconds. Regenerating: 1 file(s) changed at 2017-09-05 11:05:12 ...done in 2.497031 seconds.
When you make a change to the code, you can see the change in your browser by doing a hard refresh of the page; however, it will take a few seconds for the changes to be reflected - be sure to watch the command prompt and wait for the
...done in XXX seconds. part of the message to appear before refreshing the page.
If you’re on Mac and you get a “bundler” error while running
jekyll server --incremental:
core_ext/kernel_require.rb:55:in `require': cannot load such file -- bundler (LoadError)
You may need to force the correct package versions. This is straightforward.
gem install bundlerfrom your terminal
jekyll serve --incrementalagain
The Docker installation used for back-end development includes a copy of Jekyll. Running
docker-compose up -d will start the website; as with a direct install of Jekyll, editing and saving any file in the
docs/ folder will re-generate the website with those changes. Unfortunately, depending on which operating system you’re using and which version of Docker you have, Docker is often much slower to recognize changes to files and execute the rebuild. This can make it much more inefficient to use Docker for day-to-day development.
If you do want to use Docker for viewing the website, either because of problems installing Jekyll or if you’re just editing the website occasionally, follow these steps.
docker-compose up -d.
docker psto view a list of the currently running containers. You should see something like this:
CONTAINER ID IMAGE ... PORTS NAMES b14b87646f52 sosedoff/pgweb ... 0.0.0.0:8081->8081/tcp housinginsights_web_1 6767fbc67457 housinginsights_jekyll ... 0.0.0.0:4000->4000/tcp housinginsights_jekyll_1 f5c2e0978683 codefordc2/housing-insights-postgres ... 0.0.0.0:5432->5432/tcp housinginsights_postgres_1 c59b7bfb0ebc housinginsights_sandbox ... 0.0.0.0:5000->5000/tcp housinginsights_sandbox_1
docker logs -f housinginsights_jekyll_1to view the realtime output of the container.
<your-docker-ip>:/4000in your web browser, where
<your-docker-ip>is the ip address of the docker container (see docker instructions)
done in XX seconds.portion of the message is shown.
ctrl+cin the terminal window.