9d0ce1c22a
* Fix the nav html and cache it - Remove `active` class from nav html - Add js to insert `active` class on link to selected page - Include attempt to generate page-specific css for same styling when js is off * Refactor nav, breadcrumbs, children_nav Fix #1118 Improve the modularity of building the nav-panel, breadcrumbs, and children-nav by making them independent. This also significantly simplifies the Liquid code. * Manual merge of fix-leakage Also fix order of breadcrumbs * Fix order of breadcrumbs * Revert layout in HTML Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site. * Update breadcrumbs.html Revert inclusion of single breadcrumb for top-level pages. * Update breadcrumbs.html Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site. * Update children_nav.html Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site. * Delete nav_init.html * Update sidebar.html Caches. * Add a comment * Update nav.html - Comment on independence from page. - Remove redundant comment. - Remove superfluous conditionals. * Update just-the-docs.gemspec Revert jekyll version spec change. * Update just-the-docs.gemspec Revert runtime dependency on kramdown-parser-gfm. * Revert inclusion of activation.scss.liquid Inclusion makes HTML of all pages differ from 0.5.1 * Update default.html Restore deleted "<!DOCTYPE html>" * Update children_nav.html Restore line break. * Delete activation.scss.liquid This was merely an example of page-specific CSS for use when JS off. * Remove an unused include parameter `nav.html` does not depend on `include.key`. * Generate page-specific styling for nav links and lists in the side-nav In this PR, the code in `includes/nav.html` is fixed, and none of its elements have class `active`. When JS is enabled, `activateNav()` adds the class `active` to all nav-list-items that enclose the nav-list-link to the current page, so the navigation works as usual. Unobtrusive JS requires the same behaviour when JS is disabled. - Add `_includes/css/activation.scss.liquid` to compute the indices in the enclosing nav-lists of the nav-list-link to the current page, and generate page-specific styling. - Insert Liquid code in `_includes/head.html` to include the CSS generated by `_includes/css/activation.scss.liquid` (which depends on `site.color_scheme`). - Update the toggling in `initNav()` to allow also contraction of enclosing levels when JS is enabled. Caveat: When JS is enabled, buttons can be used to switch the colour scheme dynamically. The page-specific styling of the site-nav is generated statically, and doesn't change, so the background-image of the nav-list-link to the current page is incorrect. (I guess that could be fixed by generating a style element for each available colour scheme, and using JS to reorder the stylesheets in the DOM.) A further issue is that the `@import` rules used in `_includes/head.html` cause duplication. Replacing them by `@use` rules would avoid duplication, but that is out of scope for this PR. * Fix activation for collections - Adjust generated selectors to pages in collections. - Expand all folded collections when JS is disabled. This PR should now make unobtrusive use of JS: - When JS is disabled, the navigation panel shows links to the top pages in all collections (in contrast to the current version of the theme). - When JS is enabled, folded collections remain folded until their pages are selected. * Respect `child_nav_order` - Assumes reverse order when set to any truthy value. * Suppress liquid line breaks * Cache the search for favicon.ico - Move the code for finding the favicon.ico file to `_includes/favicon.html`. - Replace that code in `_includes.html` by a cached include of `favicon.html`. * Add "jekyll-include-cache" in fixtures Needed when CI ignores the gemspec. * Add gem "jekyll-include-cache" in fixtures Needed when CI ignores the gemspec. * Update head.html - Avoid duplication of color_scheme CSS in `style` element. - Avoid generation of whitespace by Liquid code. * Update sorted_pages.html - Minor optimisation. - Minor improvements to layout of Liquid code. * Ensure split is not at start of rules generated by css/activation.scss.liquid A custom color scheme might not import any highlighting style rules, so we should not assume that there is anything before the first occurrence of `.site-nav`. * Update head.html - Add implicit import of light color scheme. - Revert to previous Liquid code for removing color scheme rules. * Manual resolution of merge conflicts with v0.5.2 - Copied replacement of links on nav expanders by buttons. - Removed (page-dependent) conditions associated with `active`. * Manual resolution of merge conflict with v0.5.2 If previously "" (neither active nor passive), then `active && passive` is true, and the target is now "active". If previously only "active", then the target is now just "passive". If previously only "passive", then the target is now just "active". The state "active passive" is never used. The value of `active` is true just when the target is left "active". * Update fixtures/Gemfile-github-pages Co-authored-by: Matt Wang <matt@matthewwang.me> * Update head.html The result of `activation.scss.liquid` is "" for pages with no `title` or with `nav_exclude`. This update stops `head.html` including a `style` element with an invalid body on such pages. Note that when the result of `scssify` doesn't contain `.site-nav`, `split` produces a one-element array, so `shift` produces an empty array, and `join` then produces an empty string. * Fix omitted `.site-nav` Restore the previous prepending of `.site-nav`, which was dropped when suppressing the generation of an incorrect `<style>` element for pages excluded from the navigation. * Add a footnote about `.site-nav` * Make setTheme remove background images from nav links With a fixed nav panel, a <style> in the <head> sets a background image to highlight the nav list link to the current page. The image color depends on site.color_scheme. Ideally, setTheme(theme) would change the image color to match the theme/scheme. Here, for simplicity, we merely remove the image. * Explain `nav_fold` in collections. * Refactor Attempt at cleaning up the duplicated nav links code and simplifying removal of the background image: * Add function `navLink()` * Replace `removeNavBackgroundImages()` by `removeNavBackgroundImage()` * Replace var `siteNav` by `document.getElementById('site-nav')` * Replace code in `scrollNav` and `activateNav` by `navLink()` * Replace a (non-local!) reference to `siteNav` by `document` * Disable the page-specific stylesheet when JS is enabled The page-specific `<style>` in the `<head>` is needed only when JS is disabled. Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). The page-specific stylesheet is assumed to have index 1 in the list of stylesheets. It would be safer to select it by `id`, but adding an `id` can break existing sites. * Avoid constraint on use of `.site-nav`, and refactor Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored. Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`. Remove the footnote about `.site-nav` in `docs/customization.md`. Test the styling with JS disabled, since the resulting style element is disabled by JS. * Revert "Avoid constraint on use of `.site-nav`, and refactor" This reverts commit 5284892a7486ef9d2af9929c8a509b89731bb233. * Avoid constraint on use of `.site-nav`, and refactor (This corrects a bug in the previous reverted commit for excluded pages such as 404.html.) Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored. Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`. Remove the footnote about `.site-nav` in `docs/customization.md`. Test the styling with JS disabled, since the resulting style element is disabled by JS. * Update comment * Fix duplicate plugins setting @mattxwang noticed that the second `plugins` setting was apparently overriding the first, leading to a missing plugin when using `fixtures/Gemfile-github-pages`. * Avoid double inclusion of activation file The previous changes to remove the constraint re ".site-nav" duplicated the inclusion of `css/activation.scss.liquid`. That caused significant extra build time, which the current changes to `head_nav.html` avoid (without affecting the built site). * Clarify collection configuration docs * Update and clarify the CHANGELOG --------- Co-authored-by: Matt Wang <matt@matthewwang.me>
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.
A video walkthrough of various Just the Docs features
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.1 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
Gemfileand loads thejust-the-docsgem - 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 RubyGems
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
Add this line to your Jekyll site's Gemfile:
gem "just-the-docs"
And add this line to your Jekyll site's _config.yml:
theme: just-the-docs
And then execute:
$ bundle
Or install it yourself as:
$ gem install just-the-docs
Alternatively, you can run it inside Docker while developing your site
$ docker-compose up
Usage
View the documentation 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:
- As few dependencies as possible
- No build script needed
- First class mobile experience
- Make the content shine
Development
To set up your environment to develop this theme: fork this repo, the run bundle install from the root directory.
A modern devcontainer configuration for VSCode is included.
Your theme is set up just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://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.
License
The theme is available as open source under the terms of the MIT License.