Theme Development

Table of contents

1. Clone the Git Repository
2. Serve the Jekyll Site Locally
   1. Docker
   2. Ruby
3. Test Content
4. _config.yml vs docs/_config.yml
5. Tips
   1. Reloading _config.yml
   2. jekyll serve Command Flags
   3. GitHub Pages Dependencies

Clone the Git Repository

git clone https://github.com/inpsyde/jekyll-syde-theme

Serve the Jekyll Site Locally

This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme’s contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When the theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be released.

Docker

cd <repo-root>

# If they exist
rm Gemfile Gemfile.lock gems.rb gems.locked

docker run --rm -it \
  --volume "$PWD:/srv/jekyll" \
  --publish 4000:4000 \
  jekyll/minimal:pages \
  jekyll serve -c docs/_config.yml,_config.yml

Open your browser at http://localhost:4000/jekyll-syde-theme/.

Ruby

cd <repo-root>

# If they exist
rm Gemfile Gemfile.lock gems.rb gems.locked

bundle init
bundle add --group=jekyll_plugins --version='>= 0' github-pages

bundle exec jekyll serve -c docs/_config.yml,_config.yml

Open your browser at http://localhost:4000/jekyll-syde-theme/.

Test Content

Test content at docs/tests are excluded by default. If you wish to use them during development:

First, comment out this line in _config.yml at repo root:

  # _config.yml

  exclude:
    # Comment out the following line for local development
-   - "docs/tests/"
+   # - "docs/tests/"

Then, restart the Jekyll server.

Test content is avaible at http://localhost:4000/jekyll-syde-theme/tests/

_config.yml vs docs/_config.yml

docs/_config.yml is for generating https://inpsyde.github.io/jekyll-inpsyde-theme on GitHub Pages.

_config.yml at repo root is for generating http://localhost:4000/jekyll-inpsyde-theme/docs for local development.

Whenever duplicated, _config.yml at repo root takes priority.

Similarly, the local site might contains /docs/ in the URLs. This is because Jekyll translates the file paths into permalinks. The /docs/ part will be stripped away on https://inpsyde.github.io/jekyll-syde-theme.

Tips

Reloading _config.yml

For technical reasons, _config.yml and docs/_config.yml are not reloaded automatically when you use jekyll serve. If you change those files, please restart the server process.

jekyll serve Command Flags

Run jekyll serve --help for information about option flags. Notably:

GitHub Pages Dependencies

We rely on GitHub Pages to generate and host the Jekyll sites to avoid maintenance overheads. Thus, only GitHub Pages allowed dependencies can be used.