just-the-docs /just-the-docs
A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
★ 9,240⑂ 3,776👁 83⑃ 1,004● 506▤ 52
-1
Daily
9,240
stars
3,776
forks
83
watchers
1,004
prs
506
issues
52
releases
README
Just the Docs
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
https://user-images.githubusercontent.com/85418632/211225192-7e5d1116-2f4f-4305-bb9b-437fe47df071.mp4
Installation
Use the template
The [Just 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 do not need to clone or fork the [Just 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 on [GitHub Pages] – the [template README] file explains how to do that, along with other details.
If [Jekyll] is installed on your computer, you can also build and preview the created site locally. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^2] 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 a Gemfile and loads the just-the-docs gem
- uses the [GitHub 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 of just-the-docs and Jekyll it uses, as well as adding further plugins.
Use as a Ruby Gem
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
Add this line to your Jekyll site's Gemfile:
ruby
gem "just-the-docs"
And add this line to your Jekyll site's _config.yml:
yaml
theme: just-the-docs
And then install all relevant dependencies:
shell
$ bundle
Usage
[View the documentation][Just the Docs] for usage information.
Contributing
Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://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 the Contributor Covenant code of conduct.
Submitting code changes:
- Submit an Issue that motivates the changes, using the appropriate template
- Discuss the proposed changes with other users and the maintainers
- Open a Pull Request
- Ensure all CI tests pass
- Provide instructions to check the effect of the changes
- Await code review
Design and development principles of this theme:
1. As few dependencies as possible
2. No build script needed
3. First class mobile experience
4. Make the content shine
Development
To set up your environment to develop this theme: fork this repo, then run bundle install from thTop issues
#234Support system-/browser-level dark mode23 comments · 2019-10-10#728Support versioning of documentation21 comments · 2021-10-22#1223Theme Switching Button14 comments · 2023-04-14#59Multi Language Support13 comments · 2019-01-03#648Feature request: add an option for making table headers sticky (so they don't scroll past the top)11 comments · 2021-05-12#1300List popular sites that use Just the Docs 9 comments · 2023-07-26#1151Generate offline website or PDF version9 comments · 2023-02-01#938Title Logo and Text9 comments · 2022-08-24
Discussions
#1835Is there a new version release planned?1 comments · 2026-07-04#1799Internal links validator script1 comments · 2026-04-10#1763Add support for hierarchical sitemaps0 comments · 2026-01-09#1743Convert site to ebook1 comments · 2025-12-23#1728Gf0 comments · 2025-11-16#1720“Config-Only Customization for Sidebar Footer Text”2 comments · 2025-10-27#1712Mobile search box is not usable0 comments · 2025-10-01#1706Is it possible to override the existing .scss?1 comments · 2025-09-16
Latest release
v0.12.0 v0.12.0 2026-01-23Release v0.12.0 Hi folks, This minor release actually should fix all relevant issues with the placement of .site-footer, first introduced in v0.11.0. I apologize greatly for the delay and the confusion around this issue - the interactions between this component and the many different ways that users overrode different components were more complex than I expected. I've done some more thorough tests and am much more confident that this set of fixes resolves the issue, once necessary migration steps are made. I've written up migration instructions, which may be relevant for - all user