# Just the Docs: a Jekyll theme for documentation sites with built-in search > Just the Docs is an MIT-licensed Jekyll theme aimed at engineers who want a documentation site with search and no build script. The template path is the fastest route; the gem path matters when you already have a Jekyll site. **just-the-docs/just-the-docs** — A modern, high customizable, responsive Jekyll theme for documentation with built-in search. - Repository: https://github.com/just-the-docs/just-the-docs - Website: https://just-the-docs.com - Stars: 9,190 · Forks: 3,787 - Language: SCSS - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/just-the-docs-just-the-docs ## What Just the Docs solves, and who it is for Jekyll ships with a default theme that is fine for a blog and awkward for reference documentation. Navigation is shallow, search is absent unless you add a plugin, and the mobile layout is an afterthought. Just the Docs is a replacement theme that targets that gap: the README describes it as a modern, highly customizable, responsive Jekyll theme for documentation with built-in search, and it is easily hosted on GitHub Pages with few dependencies. The audience is narrow and specific. You are writing Markdown, you already build with Jekyll or you are willing to let GitHub Pages build for you, and you want the site to be searchable without wiring up an external search service. The theme's own design principles, listed in the README, are as few dependencies as possible, no build script needed, first class mobile experience, and make the content shine. That last one is a design constraint as much as a slogan: the theme deliberately does not give you a component library for marketing pages. If your documentation is generated from source code comments, or lives in a wiki, or needs to render an interactive API console, this is the wrong starting point. It renders Markdown pages and their navigation. That is the whole job. ## How the theme is structured and where search comes from The repository layout tells you most of what you need. There are _layouts, _includes, and _sass directories, plus assets, lib, and a just-the-docs.gemspec. The README states that when the theme is released, only the files in _layouts, _includes, and _sass tracked with Git are included in the gem. That is the packaging boundary: layouts control page structure, includes hold the reusable fragments such as the navigation and search UI, and _sass holds the styles. Search is described as built-in rather than delegated to an external service, which is why the dependency count stays low. The practical consequence is that search runs against your site's own content after the Jekyll build, so there is no index to host and no API key to rotate. It also means search quality is bounded by what your Markdown exposes as page titles and headings. The SCSS is the primary language of the project, and the package.json shows how it is kept in shape: stylelint with stylelint-config-standard-scss, prettier for formatting, and an npm test script that runs the lint task. Several stylelint rules are explicitly disabled in package.json, including no-descending-specificity and scss/no-global-function-names, and the three theme entry stylesheets under assets/css are excluded from linting entirely. That is a reasonable trade for a theme that has to override its own variables, but it does mean the stylesheet layer is less uniformly checked than the layouts. ## Installing Just the Docs and building a first page There are two documented routes. The README recommends the Just the Docs Template as the simplest and quickest way to create a new site: you click use the template, and the resulting repository uses a Gemfile that loads the just-the-docs gem and a GitHub Pages Actions workflow to build and publish. The README is explicit that you do not need to clone or fork the theme repository itself unless you are browsing the docs locally, contributing, or building a new theme on top of it. The second route is installing the theme as a Ruby gem into a Jekyll site you already have. Add the gem to your Gemfile: ```ruby gem "just-the-docs" ``` Then set the theme in _config.yml: ```yaml theme: just-the-docs ``` And install the dependencies: ```shell $ bundle ``` After that, the README points you to the documentation site for usage information rather than repeating it in the repository README. To preview locally you need Jekyll installed; the README notes that building locally lets you test changes before committing and avoids waiting for GitHub Pages, which it says can take up to 10 minutes to publish after a push. Running bundle exec jekyll serve starts the server on http://localhost:4000, and the site regenerates as you edit content and the theme. One thing to watch: package.json in the repository lists version 0.3.3 while the most recent release is v0.12.0. The npm metadata is about the linting toolchain, not the theme gem, but it is a reminder to pin the gem version you actually intend to use rather than assuming every version string in the repository moves together. ## The upgrade path and what MIGRATION.md implies The repository carries a CHANGELOG.md and a MIGRATION.md at the top level. The presence of a migration file is the honest signal here: this theme has had breaking changes across its release line, and the maintainers document them rather than leaving users to discover them by diffing rendered pages. That matters because a Jekyll theme is not a library you call. It is a set of layouts and stylesheets that your content sits inside. When a layout changes, your overrides can break silently. If you have copied theme files into your own repository instead of using the gem, you will not receive fixes at all, and the README's packaging note tells you exactly which directories are versioned in the gem, so those are the ones to avoid forking by hand. The last push to the repository was on 2026-09-17, and the most recent releases are v0.12.0 and v0.11.2, both dated 2026-01-23, with v0.11.1 on 2026-01-03. The gap between the January releases and the September push suggests the project moves in bursts rather than continuously. Plan upgrades around releases, and read MIGRATION.md before bumping the gem, not after your build fails. ## Where Just the Docs is the wrong tool The theme's own constraint is the first limitation: no build script needed also means no build step in which to transform content. If you need to pull API references from OpenAPI files, generate pages per code symbol, or run a documentation pipeline with custom plugins, you are fighting the design. Jekyll plugins can be added, but the GitHub Pages build path is more restrictive than a local Jekyll build, and the README's framing of GitHub Pages as the easy hosting target is the reason. The second limitation is scale. Just the Docs is built around a single documentation set with a navigation hierarchy. It does not describe a mechanism for versioned documentation, multiple product lines with separate sidebars, or per-version search scoping. Teams that need those features usually end up maintaining several sites or moving to a tool built around versioning from the start. The third is customization depth. The theme is described as highly customizable, and the _sass layer supports that, but customization happens through SCSS variables and overrides. If your design system expects component-level overrides in a templating language, or if you need a layout the theme does not provide, you will be writing Liquid and SCSS rather than configuring options. The stylelint exclusions in package.json hint at how much of the stylesheet layer is bespoke. Finally, search is built in but not described in the README as configurable to an external index. If you need faceted search, analytics on query terms, or synonym handling, the built-in option is unlikely to satisfy that, and the README does not document an extension point for it. ## How it compares with MkDocs and Read the Docs The most common comparison is with MkDocs, and the difference is the toolchain rather than the output. MkDocs is a Python static site generator with a documentation-specific plugin ecosystem, and its Material theme is the usual point of reference. Just the Docs is a theme for Jekyll, which means your build runs through Ruby and Bundler, and your hosting path of least resistance is GitHub Pages. That has a practical consequence. If your repository is already a Jekyll site, or your team already publishes on GitHub Pages, Just the Docs drops in with a Gemfile line and a _config.yml key. If your team is Python-first and wants a plugin for API docs generation, MkDocs gives you that ecosystem and Just the Docs does not, because the theme's stated principle is as few dependencies as possible. Read the Docs is a different kind of comparison: it is a hosting and build service rather than a theme, so choosing it is a decision about where documentation is built and served, not about how a page looks. A team can use Jekyll and Just the Docs and still host elsewhere; the README notes that a local build can be deployed to a platform other than GitHub Pages. The two are not mutually exclusive in the way the search phrasing suggests. ## Licence, contribution and what to check before adopting The theme is available under the MIT License, with LICENSE.txt at the repository root. That is permissive and compatible with commercial documentation sites, but the licence covers the theme code, not your content or any third-party assets you add. Nothing here is legal advice; read LICENSE.txt yourself if the distinction matters to your organisation. Contribution follows a conventional flow documented in the README: open an issue that motivates the change using the appropriate template, discuss it, open a pull request, ensure CI passes, provide instructions to check the effect of the changes, and await review. There is a CODE_OF_CONDUCT.md and the README states contributors are expected to adhere to the Contributor Covenant. If you plan to maintain a fork, that process is the one you inherit. The maintainer-side cost is the same as any theme dependency: you own your overrides and you own the upgrade. The repository's own tooling, a Rakefile, a spec directory, .rspec, and the npm lint scripts, exists so the theme can be tested before release. You get the benefit of that only if you consume the gem rather than copying files. Before adopting, check which release you are pinning, confirm the theme key in _config.yml matches the gem version in your Gemfile, and read MIGRATION.md for the versions between your starting point and your target. ## Conclusion Adopt Just the Docs if your docs already live in Markdown and you want a Jekyll or GitHub Pages site with search and no build script, and if you accept that the theme's own documentation is the real manual. Do not adopt it if you need a non-Jekyll toolchain, a plugin that GitHub Pages will not build, or a versioned multi-product documentation portal. Before committing, check the CHANGELOG for the release you intend to pin, confirm your Gemfile and _config.yml point at the same version, and decide whether you want the template repository or a gem install into an existing site. ## FAQ ### Is Just the Docs free to use? Yes. The theme is available as open source under the terms of the MIT License, with LICENSE.txt in the repository root. The licence covers the theme code, not content you add to your site. ### What is Just the Docs? It is a Jekyll theme for documentation sites, described in the README as modern, highly customizable and responsive, with built-in search. It is designed to be hosted easily on GitHub Pages with few dependencies. ### How does Just the Docs compare with MkDocs? MkDocs is a Python static site generator with its own documentation plugin ecosystem, while Just the Docs is a theme for Jekyll and runs through Ruby and Bundler. The README lists as few dependencies as possible as a design principle, so the theme does not aim to match a plugin ecosystem. ### What are the alternatives to Just the Docs? The README points to the Just the Docs Template for new sites and to Jekyll itself for local builds. Read the Docs is a hosting and build service rather than a theme, so it is a different kind of choice, and MkDocs is the usual comparison when the toolchain is Python rather than Ruby. ## Sources - [just-the-docs/just-the-docs on GitHub](https://github.com/just-the-docs/just-the-docs) - [License: MIT](https://github.com/just-the-docs/just-the-docs/blob/main/LICENSE) - [Project website](https://just-the-docs.com) - [README](https://github.com/just-the-docs/just-the-docs/blob/main/README.md) - [Releases](https://github.com/just-the-docs/just-the-docs/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/just-the-docs-just-the-docs