Repository files navigation

A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.
Easily hosted on GitHub Pages with few dependencies.

See it in action!

A video walkthrough of various Just the Docs features

TheJust the Docs Template provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "use the template"!

Note: To use the theme, you donot need to clone or fork theJust the Docs repo! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.

You can easily set the site created by the template to be published onGitHub Pages – thetemplate README file explains how to do that, along with other details.

IfJekyll is installed on your computer, you can also build and preview the created sitelocally. This lets you test changes before committing them, and avoids waiting for GitHub Pages.¹ And you will be able to deploy your local build to a different platform than GitHub Pages.

More specifically, the created site:

• uses a gem-based approach, i.e. uses aGemfile and loads thejust-the-docs gem
• uses theGitHub Pages / Actions workflow to build and publish the site on GitHub Pages

Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions ofjust-the-docs and Jekyll it uses, as well as adding further plugins.

Alternatively, you can install the theme as a Ruby Gem, without creating a new site.

Add this line to your Jekyll site'sGemfile:

gem"just-the-docs"

And add this line to your Jekyll site's_config.yml:

theme:just-the-docs

And then install all relevant dependencies:

$ bundle

View the documentation for usage information.

Bug reports, proposals of new features, and pull requests are welcome on GitHub athttps://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to theContributor Covenant code of conduct.

• Submit anIssue that motivates the changes, using the appropriate template
• Discuss the proposed changes with other users and the maintainers
• Open aPull Request
• Ensure all CI tests pass
• Provide instructions to check the effect of the changes
• Await code review

1. As few dependencies as possible
2. No build script needed
3. First class mobile experience
4. Make the content shine

To set up your environment to develop this theme: fork this repo, the runbundle install from the root directory.

A moderndevcontainer configuration for VSCode is included.

Your theme is set up just like a normal Jekyll site! To test your theme, runbundle exec jekyll serve and open your browser athttp://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When this theme is released, only the files in_layouts,_includes, and_sass tracked with Git will be included in the gem.

The theme is available as open source under the terms of theMIT License.