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
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!
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.
The fastest way to use this theme is with GitHub Pages, check out the Quick Start Guide from the user documentation.
These instructions describe 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 uses the theme documentation as the site content.
Docker provides an easy way to set up the development environment without installing Ruby or any other dependencies on your machine. With two simple commands you can build and serve this project.
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-rtdThis 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, but the built
image still goes triggers a gem installation step every time it is launched,
in case there has been changes. It's recommended to rebuild the image if there
are any changes made to the Gemfile or gemspec dependencies.
This method is meant to replicate how GitHub Pages builds the "docs" folder for https://carlosperate.github.io/jekyll-theme-rtd.
There are two main differences with this method:
- The root directory is the "docs" folder instead of the project root directory, so the navigation hierarchy is different.
- This method uses the
remote_themeJekyll plugin, so it uses the files currently pushed and available in the GitHub repositorymainbranch, 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-rtdAnd, as before, the website is served at http://localhost:4000.
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 8080Bug 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.
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.