Fix two bugs in customization docs
- custom favicon docs were not wrapped in `{% raw %}` tags
- the "new" annotation for color schemes had an extra whitespace, and so the CSS class was not applied
* Issue #1023 - note that GA4 properties are supported
* Issue #1023 - parameterize Google Analytics property script
* Issue #1023 - support a list of multiple Google Analytics tracking IDs in config
* Issue #1023 - update Google Analytics configuration doc
* Fix configuration of multiple Google Analytics properties and simplify type checking
* simplify unnecessary code repetition
* tweak Google Analytics config documentation wording
* Add 'reversed' as the preferred keyword, with 'desc' as a deprecated alternate
* Doc updates
* Add the test for 'reversed' to the toc_list
Add also a comment about this.
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
* Removes `favicon.html`, shifts content to `head_custom.html`
* explicit callout for custom favicon in customization docs
* Cleaner and more consistent documentation (review from @pdmosses)
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Fix external links and collections
The navigation should only display the external links once, after the links to pages that are not in collections.
The test for PR #876 at https://just-the-docs.github.io/just-the-docs-tests/navigation/external-links fails with v0.4.0.rc3,
and succeeds when the updated `nav.html` is added locally.
The docs need updating to clarify how the interaction between the collections feature and the external links feature is resolved.
* 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>
* Fix default highlighting in custom schemes
Fix#982
The variable settings for highlighting in the default `light` scheme are currently (v0.4.0.rc2`) in `_sass/color_schemes/light.scss`.
This PR ensures that custom schemes are based on the `light` scheme.
It also adds a note explaining the default to the customization docs,
and gives an example of how to define a custom scheme based on the `dark` scheme
* Prettier
* Deleted test file
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Add toc heading custom include
Closes#961.
* Revert "Add toc heading custom include"
This reverts commit 49813c341973e313db0a21f075a60ebf2120989e.
* Update code highlighting with line numbers
- Add the example of code highlighting with line numbers explained in the [Jekyll docs](https://jekyllrb.com/docs/liquid/tags/#line-numbers).
- Fix the styling of narrow code with line numbers, which floats to the centre without this CSS adjustment. (The line numbers column expands as needed with larger numbers of lines, despite using `width`; using `min-width` doesn't work.)
To apply HTML compression, I removed `vendor` from `exclude`; that change is left to a different PR.
This PR updates the home page and the CHANGELOG to refer to v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.
It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.
As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)
This PR has a bit of scope creep! This PR now:
- changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857
- changes the behaviour of mermaid configuration
- instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js`
- the include is loaded directly into the contents of `mermaid_initialize`
- by default, it is an empty object (i.e. `{}`), triggering the defaults
- updates docs
- adds an example to the markdown kitchen sink
It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward!
Looking at how the variables are defined in _variables.scss, with various dependencies between them aimed at ensuring a consistent color scheme, one might expect that redefining a given variable would affect the remaining styles that depend on it.
This is not the case, however, due to the order in which the files are processed. This PR edits the documentation to mention the non-propagating behavior of redefined variables, to better guide users that wish to customize the site using custom themes, and call their attention to the need to redefine the dependency relations as well.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
Fix#517
Users expect nested task lists to have the same indentation as other lists.
Fix the styling in `_sass/content.scss` to do that.
Add examples in `docs/index-test.md` to test.
As is, this is invalid and will not cause the TOC to be rendered. The collapsing example is fine.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
These docs outline some of the custom includes that are provided by the theme and can be modified by the user.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
This PR combines (and resolves conflicts between) #448, #463, #466, #494, #495, #496, #498, and #572.
The main aim is to facilitate use of several of the implemented features _together_, when using the fork as a remote theme. It should also simplify merging the included PRs into a future release.
The branch [combination-rec-nav](https://github.com/pdmosses/just-the-docs/tree/combination-rec-nav) adds [multi-level navigation](https://github.com/pmarsceill/just-the-docs/pull/462) and (NEW:) [sibling links](https://github.com/pmarsceill/just-the-docs/pull/394) to the branch used for this PR. It includes updated [documentation for the navigation structure](https://pdmosses.github.io/just-the-docs/docs/navigation-structure/), and reorganised and extended [navigation tests](https://pdmosses.github.io/just-the-docs/tests/navigation/). The documentation and the tests can be browsed at the (temporary) [website published from the combination-rec-nav branch](https://pdmosses.github.io/just-the-docs/).
_Caveat:_ The changes to v0.3.3 in this PR and #462 have not yet been reviewed or approved, and may need updating before merging into a release of the theme. If you use a branch from a PR as a remote theme, there is a risk of such updates affecting your website. Moreover, these branches are likely to be deleted after they have been merged. To avoid such problems, you could copy the branch that you want to use to your own fork of the theme.
Co-authored-by: Matt Wang <matt@matthewwang.me>
- Limit the effect of `nav_exclude: true` to the main navigation.
- Include links to excluded pages in auto-generating lists of child pages
and in breadcrumbs.
- Refactor implementation by moving assignment of `first_level_url` and `second_level_url` from `_includes/nav.html` to `_layouts/default.html`.
- Clarify the effect of `nav_exclude` in the documentation.
