Reinstated the collapsible TOC at the top, to support the reference to it right at the end of the file. (The `TOC` feature can only be used once per page, so this is the only way of illustrating the rendering of the collapsible TOC in the docs.)
Apparetnly Jekyll's `include` config option cannot be used to override an `exclude`, so activating `docs/tests/` requires commenting-out that line in the `exclude` list.
The values of `title` and `nav_order` can be numbers or strings.
Jekyll gives build failures when sorting on mixtures of different types,
so numbers and strings need to be sorted separately.
Here, numbers are sorted by their values, and come before all strings.
An omitted `nav_order` value is equivalent to the page's `title` value
(except that a numerical `title` value is treated as a string).
The case-sensitivity of string sorting is determined by `site.nav_sort`.
Pages with `nav_exclude: true` were included when sorting on `title` or `nav_order`. That could cause build failures when the type of value of the field differs from that on other pages, as reported in https://github.com/pmarsceill/just-the-docs/issues/406.
Pages with `nav_exclude: true` or no `title` are never displayed in the navigation, so removing them from `pages_list` cannot break existing sites. This change also allows the removal of some tests in the code. (The indentation of the code should now be adjusted, but that has been deferred, to restrict the size of the diff for review.)
For testing, the title of `404.html` has been changed to the number `404`, the page `docs/untitled-test.md` has been added, and `nav_sort_order` has been set to `case_sensitive`. Those updates give build failures with the current version of `_includes/nav.html`, but not after the suggested changes.
It will still be possible for build failures to occur due to sorting fields of *non-excluded* pages with differing types of values (e.g., `nav_order`a mixture of numbers and strings). To make the code completely safe will require relatively complicated changes,.
The additions to `_config.yml` go together with the changes to `code.scss`,
to facilitate adjusttments by users. See `docs/linenos-test` for the details.
The CSS code has been significantly refactored and simplified,
and seems to produce sensible results (at least on Safari and Firefox).
Makes the TOC at the top of the page collapsible.
Adds an explanation of the markup used to produce a collapsible TOC.
Adds a comment about the possibility of using an unordered list for the TOC,
and about using TOC only once per page.
Added a configuration option to determine whether the sort order is case-sensitive.
The default is case-insensitive.
To test:
- open `/just-the-docs/docs/utilities/` in the browser,
and check that the navigation links in `Utilities` are sorted alphabetically;
- in `docs/utilities/layout.md', change the preamble to `title: layout`,
and check that the links in `Utilities` are still sorted alphabetically;
- add `nav_sort: case_sensitive` in the configuration file,
and check that the link to `layout` is now listed last under `Utilities`.
Patrick Marsceill
PLanCompS
Phillip Cutter
Henrique Vianna
Silvio Giebl
Patrick Marsceill
Matt Wang
PLanCompS