b4b951fe5d
* Optimize simple navigation cases Fix inefficiency reported in feedback on v0.4.0.rc2 (see discussion #958). This PR: * essentially reverts `_includes/nav.html` to v0.4.0.rc1 * preserves the ARIA labels added by #950 * adds a test to optimize builds of sites that rely on `title` fields to order pages. Building the `endoflife.date` site (130 pages) now takes only about 7 seconds. Building the `machinetranslate.org` site ( 350 pages) takes about 7 minutes. (Without the added test, it takes just over 5 minutes: the condition of the test is merely to compare the size of two arrays, but that is apparently enough to prevent Jekyll from applying some optimization). A warning is added to the docs about the need for numbers to be in quotes when used as title values. * Update navigation-structure.md A clarification is added to the docs about the need for numbers to be in quotes when used as title values. * Simplify the control and data flow - Defer concatenation of `string_order_pages` with `title_order_pages` until needed. - Replace tests on size with tests for `empty`. - Rename variables accordingly. * Fix child nav order This PR started from the navigation in RC1. Some cosmetic improvements had been made in RC2. This commit adds some of those changes to this PR. It also fixes a bug (revealed by a new regression test) due to a reference to `node.child_nav_order` instead of `child.child_nav_order`, which prevented reversal of the order in children of children. Presumably a top-level reversal should apply only to direct children, and not to grandchildren. The latter interpretation would be very confusing in a deep multi-level hierarchy. * Allow pages with numeric titles An omitted `nav_order` value should default to the `title` value, regardless of its type. Jekyll 3 gives build errors when numbers and strings are sorted together. This commit drops the assumption that `title` values are always strings – a 404 page naturally has a numeric title. It updates the docs page accordingly. The extra code does not affect the build time for the `endoflife.date` site (7 seconds). For the `machinetranslate` site, changing the title of the 404 page to a number increases the build time from 7 minutes to 9 minutes – the `nav_order` numbers on that site are program-generated in the range 1..1000, which might be atypical. This commit has not yet been checked using the regression tests. The gemspec used for testing specifies `spec.add_runtime_dependency "jekyll", "~> 3.8.5"`, and `Gemfile.lock` shows `jekyll (3.8.7)`. * Update nav.html Add comment about an optimization that will be possible in Jekyll 4. * Update nav.html - Update the comment about optimization possibility. - TEMPORARILY add Jekyll 3 code for conditionally optimizing. * Update nav.html Minor improvements and cosmetic changes. * Major revision This update is based on extensive experimentation and profiling with alternative versions of the Liquid code used to build the main navigation panel. Due to the fragility of Jekyll's optimizations, combining alternative approaches with conditionals turned out to be too expensive: merely adding a condition to check whether some array of pages is empty can add about 20% to the build time! The current code avoids sorting pages on `nav_order` and `title` fields together. The standard way of doing that in Jekyll is to use the `group_by` filter; but extracting the sorted pages from the groups turned out to be too inefficient (as seen in RC1), as was generating links directly from the groups (in RC2). Making all pages with `nav_order` values come before all those ordered by their `title` values is not ideal (it doesn't support tweaking the relative order of two pages in a list of pages ordered by their titles) but it appears to be necessary for efficient builds on large sites. This version has not yet been fully tested for regression, but otherwise seems to give the expected navigation on the endoflife.date and machinetranslate websites. (I'm unable to install the Python-based how2data repository on my laptop, due to package version issues on Apple silicon). Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
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.
Installation
via GitHub Pages remote theme
The quickiest way to use Just The Docs is to use GitHub pages remote theme feature in your _config.yml file:
remote_theme: just-the-docs/just-the-docs
via RubyGems:
Alternatively you can install it as a Ruby Gem.
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 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:
- Open a Pull Request
- Ensure all CI tests pass
- Await code review
- Bump the version number in
just-the-docs.gemspecandpackage.jsonaccording to semantic versioning.
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, run bundle install.
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 the theme is released, only the files in _layouts, _includes, and _sass tracked with Git will be released.
License
The theme is available as open source under the terms of the MIT License.