Overview:

The Read The Docs Theme for Jekyll and GitHub Pages is a port of the Read the Docs theme to Jekyll, allowing it to be used with GitHub Pages. The original Read The Docs theme was designed specifically for documentation and, when combined with GitHub Pages, provides a simple and effective way to document projects. Although still a work-in-progress, the theme is already usable, with any missing features and known issues being listed on the GitHub issues page. Contributions to the theme are welcomed.

Features:

• Port of the Read the Docs theme to Jekyll
• Designed specifically for documentation
• Works seamlessly with GitHub Pages

Installation:

To use this theme with GitHub Pages, follow the Quick Start Guide in the user documentation.

Developer Documentation:

There are two ways to set up your environment to develop or edit this theme:

Run in a virtual machine with Vagrant:

1. Install Vagrant and VirtualBox on your machine.
2. Clone the theme repository.
3. In your terminal, navigate to the cloned theme repository.
4. Run the following command:

vagrant up

5. Wait for the command to complete. Subsequent runs will be quicker.
6. Access the website at http://localhost:4000 to view and make changes.

Run locally with Ruby:

1. Install Ruby v2.5 on your machine.
2. Clone the theme repository.
3. In your terminal, navigate to the cloned theme repository.
4. Run the following command to install dependencies:

bundle

5. Access the website at http://localhost:4000 to view and make changes.

Build the docs using the remote theme:

1. The Jekyll project is configured to use the root of the repository as the root of the website.
2. When built locally, the website will see all pages as being inside a “docs” folder.
3. When built and served with GitHub Pages, the root of the website is the “docs” folder, resulting in different URLs and navigation bar categories.
4. To update the theme documentation, build it accordingly.

Summary:

The Read The Docs Theme for Jekyll and GitHub Pages is a convenient and compatible theme for documenting projects using Jekyll and GitHub Pages. It provides a user-friendly interface and easy installation process, with options for both virtual machine and local development. Although still being developed, the theme is already usable and welcomes contributions.