Developer Documentation

This page is meant for developers who want to contribute to the development of this theme or build their own customisations.

The theme is developed like a normal Jekyll site, and it uses the docs folder in the GitHub repository as the markdown content to generate the documentation website.

Single repository with all the theme source code and docs: https://github.com/carlosperate/jekyll-theme-rtd

🚀 Run with Docker

Docker provides an easy way to set up the development environment without installing Ruby or any other dependencies on your machine.

A Dockerfile is included to run an environment with Ruby and Jekyll. First, build the Docker image:

$ docker build -t jekyll-theme-rtd .

And then serve the website:

$ docker run --rm -p 4000:4000 -p 35729:35729 -v $(pwd):/srv/jekyll jekyll-theme-rtd

The Docker image includes an inline entrypoint script in the Dockerfile that supports multiple commands. By default, the container runs serve.

Build only (no local server):

$ docker run --rm -v $(pwd):/srv/jekyll jekyll-theme-rtd build

Serve with custom Jekyll CLI options:

$ docker run --rm -p 4000:4000 -p 35729:35729 -v $(pwd):/srv/jekyll jekyll-theme-rtd serve --drafts --future

This will serve the website at http://localhost:4000 with live-reload enabled, so any changes made on these files will trigger a rebuild and automatically refresh the browser.

Building the docker image pre-installs the required Ruby Gems. On launch, the container runs bundle check and only installs gems when needed (for example, if dependencies changed). It’s recommended to rebuild the image if there are any changes made to the Gemfile, Gemfile.lock, or gemspec dependencies. In fresh clones where Gemfile.lock is not present, bundler resolves versions from the Gemfile and generates the lockfile during install.

Build the docs using the remote theme

This method replicates how GitHub Pages builds the docs folder for the https://carlosperate.github.io/jekyll-theme-rtd site.

It uses the remote_theme Jekyll plugin, so fetches the files directly from the GitHub repository main branch, not the local files from your machine.

To do this, we add the -w /srv/jekyll/docs to the docker command:

$ docker run --rm -p 4000:4000 -p 35729:35729 -v $(pwd):/srv/jekyll -w /srv/jekyll/docs jekyll-theme-rtd

In this mode, the generated site is written to docs/_site. As before, the website is served at http://localhost:4000.

🐛 Debug Config

A debug utility page is included in the docs/ folder that prints all Jekyll, Liquid, and GitHub Pages variables at build time. It is very useful for inspecting site.github.* metadata and troubleshooting configuration issues during development.

See the Debug Config docs page for full details, usage instructions, and security considerations.

The source file is at repository docs/debug.html file.

🆚 Build the docs with MkDocs for comparison

As this theme is a port from the MkDocs port, it can be useful to run MkDocs to build the docs and compare the original MkDocs theme vs this Jekyll port. A mkdocs.yml file is included to configure the project.

We recommend using a virtual environment to run the following steps:

$ pip install mkdocs==1.6.1
$ mkdocs serve

👨‍👩‍👧‍👦 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/carlosperate/jekyll-theme-rtd.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

⚖️ License

Information about the license can be found in the repository README file.