Read The Docs Theme for Jekyll and GitHub Pages

Port of the Read the Docs theme to Jekyll that can be used with GitHub Pages.

You can preview it in the user documentation:

The original Read The Docs theme was created for Sphinx, and so it is designed specifically for documentation.

Combined with GitHub Pages it's a great and easy way to document your projects!

Check out the quick start guide to see how easy it is to

🚧 Warning!

This theme is currently a Work-In-Progress but, while some things might be broken, it should be already usable.

Missing features are listed in the GitHub issues with the to-do label, and any known issues are listed with the bug label.

Contributions are very welcomed!

🗂️ Readme Contents

This README contains mostly the developer documentation to edit this theme.

To learn how to use this theme for your own website or docs check out the user documentation.

• 🚀 Using this theme with GitHub Pages
• 👩‍💻 Developer Documentation
  • Run in a virtual machine with Vagrant
  • Run locally with Ruby
  • Build the docs using the remote theme
  • Build the docs with MkDocs for comparison
• 👨‍👩‍👧‍👦 Contributing
• ⚖️ License

🚀 Using this theme with GitHub Pages

The fastest way to use this theme is with GitHub Pages, check out the Quick Start Guide from the user documentation.

👩‍💻 Developer Documentation

These instructions describe two different ways to to set up your environment to develop or edit this theme.

The theme is developed like a normal Jekyll site, and it can serve the documentation using the theme source code located here.

Run in a virtual machine with Vagrant

Vagrant provides an easy way to set up and manage a Virtual Machine with VirtualBox. With a single command you can automatically create the VM with all the dependencies required to build and sever this project.

There is a Vagrantfile included to run an Ubuntu VM with Ruby and Jekyll. To set-up everything and serve the website run:

$ vagrant up

The first time you run this command it will take a bit longer, as it downloads and installs everything. Subsequent runs will be much quicker.

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

Other Vagrant commands

To stop the virtual machine first press Ctrl+C to end the Jekyll process and execute in your terminal:

$ vagrant halt

You can also SSH into the virtual machine with:

$ vagrant ssh

Run locally with Ruby

This website has been developed using Ruby v2.5. You can install the dependencies with:

$ gem install bundler
$ bundle install

Build the docs using the remote theme

The Jekyll project here is configured with the root of this repository as the root of the website, so when it is built locally it will see all pages as being inside a "docs" folder, and therefore in the "docs" category in the left navigation bar and page URLs.

On the other hand the root of the website built and served with GitHub Pages is the "docs" folder, so the left navigation bar will show the child folder as categories and the URLs will be different.

For updating the theme documentation it can be useful to build and sever the docs folder with the same configuration as GitHub Pages. Of course, this would mean that the theme used will be the current snapshot of master on GitHub instead of the local files, but that is not important to just preview the docs.

To do this, add the following lines to the docs/_config.yml file:

plugins:
  - jekyll-remote-theme

Then execute Jekyll from the docs folder:

$ vagrant up --no-provision
$ vagrant ssh
(ssh session) $ cd /vagrant/docs
(ssh session) $ bundle exec jekyll serve --host 0.0.0.0 --watch --force_polling

Build the docs with MkDocs for comparison

As this theme has been ported from the MkDocs port, it can be useful to run MkDocs on the documentation markdown file and compare its output to the Jekyll output. A mkdocs.yml file is included to configure the project.

Pipenv has been used to manage Python dependencies:

$ pip install pipenv
$ pipenv install
$ pipenv run mkdocs build
$ cd _site_mkdocs
$ pipenv run python -m http.server 8080

👨‍👩‍👧‍👦 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

The original theme is from Read The Docs. Copyright © 2013-2018 Dave Snider, Read the Docs, Inc. & contributors, and released under the MIT License.

This theme is based on the MkDocs readthedocs port. Copyright © 2014, Tom Christie, all rights reserved, and released under the BSD 2-Clause "Simplified" License.

The theme modifications to port it Jekyll can be seen here. This and all new features are released under the BSD 2-Clause "Simplified" License.