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.

The theme documentation is also the live demo:

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 get started!

Features:

• 🖥️ Read the Docs responsive design with a collapsible sidebar navigation
• 🐙 Specifically developed to be compatible with GitHub Pages out of the box
  • 📁 Simply create a docs folder with a _config.yml and your markdown files
  • 🔗 Automatic GitHub link, "Edit on GitHub", and commit links (optional)
  • 🏷️ Latest release tag displayed in the sidebar (optional)
• 🌐 External links in the navigation bar
• 🔍 Built-in search functionality via Lunr.js
• 🖍️ Source code highlighting via highlight.js, with a copy-to-clipboard button
• 🧜 Diagram rendering support via Mermaid
• 📢 Admonition callouts via aDOMonitions
• ⚓ Heading anchor links on hover via AnchorJS
• 🔘 Button styling via links with additional attributes
• 🏷 Labels for status, releases, or other metadata
• ⚙️ Configurable with custom options in _config.yml and front matter
• 📣 Social media metadata and preview images
• 🔎 SEO friendly meta tags and canonical URLs
• 🧑‍💻 TODO 🧑‍💻: 🧮 Mathematical expressions rendering

🧑‍💻 Work in Progress!

New features are still being developed but the theme is already usable and v1.4.0 is the latest release 🎉.

Any possible breaking change would be released as a major revision (i.e. v2, v3, etc). A breaking change would be a change in existing config options, or a significant visual style change, while new features and settings will be released a minor revisions (i.e. v1.1, v1.2, etc).

So, it is recommended to lock the theme version in the _config.yml file:

remote_theme: carlosperate/jekyll-theme-rtd@v1.4.0

Missing features are listed in the GitHub issues with the enhancement or new feature labels, and any known issues are listed with the bug label.

Contributions are very welcomed!

👨‍👩‍👧‍👦 Contributing

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

For information about contributing, see the developer documentation.

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

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 to Jekyll can be seen in this diff, and this project is also released under the BSD 2-Clause "Simplified" License.