Hi there!

Thank you for the great theme! I am a happy user and was delighted to see that mermaid support has landed.

In some cases the usage of jsDelivr might not be possible for technical or compliance reasons.

This commit adds a second way to include the mermaid lib by specifying a path in the mermaid config. This way a local version of the lib can be used.

It should be fully backwards compatible, not requiring any action by users that already include the lib from the CDN.

I already added some documentation, but I am also happy to extend this, if this change is generally well-received.

Cheers,
Christian

This is an alternative PR that resolves #1011. Unlike #1013, this PR defines a *new* SASS file, `_sass/custom/setup.scss`, specifically designed for new custom variables (and other SASS-only constructs). It's imported after our `support` SASS files are (functions, variables), but otherwise is imported before all other files (ex, when CSS is emitted).

So, custom callout colors can now be defined in this file. I also move the custom callout colors present in `custom.scss` to the right location.

I've added some docs that briefly explain how to use the feature. Feedback is welcome!

---

As an aside, I chose not to add a `_includes/css` file that imports this, and then import that file. I think that's only necessary if we're trying to render liquid somehow in the SASS file; since we're not trying to do that for `setup.scss`, I've opted to not include it. If we think this is relevant, I can re-add it.

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>

This is a prototype for review and discussion. My use and testing of this PR is on top of 6d9d4135. The changes are trival to rebase to `main` and I'm happy to do so if this prototype moves forward.


* Feature request details in linked issue, fixes just-the-docs/just-the-docs#1067
* I welcome feedback and all discussion
* A draft doc site of mine using this PR is at https://docs.hidale.com/

To use the prototype, the two include files need to be customized. Here are mine from the draft website https://github.com/diablodale/dp.docs/commit/9c0d836408af2e72dbce115a01ce6627137e66dd



Co-authored-by: Matt Wang <matt@matthewwang.me>

This PR simply fixes a few spacing and comment nits I found.

Hi everyone, this is a large refactoring PR that looks to **modularize site components** following the discussion in #959. At the top-level, it:

- moves icons, the sidebar, header (navbar, search, aux links), footer, and mermaid components of the `default` layout into their own `_includes`
- creates a new `minimal` layout that does not render the header or sidebar as a proof-of-concept for the composability of components
- documents all existing and new layouts (including vendor code) in the "Customization" section 

An important goal of this PR is for it to be **just code motion and flexibility**: there should be **zero impact** on the average end user that only consumes the `default` theme.

The next few sections go in-depth on each of the listed changes.

### new components

The `default` layout contains a "list" of all relevant components. Importantly, some of these components have sub-components:

- the header is split into the search bar, custom code, and aux links
- the icons include imports different icon components, some of which are conditionally imported by feature guards

There are also candidates for future splits and joins:

- the sidebar could be split into navigation, collections, external link, and header/footer code
- the "search footer" could be joined with other search code, which would make it easier to "include search" in one go; *however, this is a markup change*
- @kevinlin1 has pointed out that there is some leakage between the sidebar (which computes parents/grandparents) and the breadcrumbs (which needs them to render). He's graciously added a bandaid fix to `minimal` (which does not render the sidebar). However, in the long term, we should either:
    - calculate this in a parent and pass the information to both components
    - change how this works entirely (which may happen with multi-level navigation)

@pdmosses has done a great job outlining this and more in his [Modular Layouts test site](https://pdmosses.github.io/modular-layouts/docs/main/).

### minimal layout

Based on @kevinlin1's use-case in just-the-class (see: his [Winter 2023 CSE 373 site](https://courses.cs.washington.edu/courses/cse373/23wi/)), we've created a first-class `minimal` layout that does not render the sidebar or header.

In a [comment](https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057015039), Kevin has indicated that we can re-add the search bar in the minimal layout; however, it seems like this would be a code change. I think we should punt this to a future issue/PR.

@pdmosses has also discussed the confusion of `minimal` as a layout and its meaning in inheritance. I've added a note in documentation to clarify the (lack of) inheritance relationship.

### documentation

I've written documentation in the "Customization" page / [Custom layouts and includes](https://deploy-preview-1058--just-the-docs.netlify.app/docs/customization/#custom-layouts-and-includes) section explaining:

- generally, that we use includes/layouts (and pointing to docs)
- the `default` layout and its constituent components (with a warning about name collisions)
- creating alternative layouts with `minimal` as an example
- the inheritance chain of layouts and the vendor layouts that we consume

I've also created (and linked to) a [minimal layout test](https://deploy-preview-1058--just-the-docs.netlify.app/docs/minimal-test/) that is currently a copy of the markdown kitchen sink but with the minimal layout. I think there's room to improve this in the future.

### future work

I think there's a lot we can do. Let me break this into various sections.

Potential follow-ups before `v0.4.0`:

- re-including search in `minimal` (anticipating a minor code change)
- fixing the leakage of parent/grandparent information between the sidebar and breadcrumbs (anticipating no end-user code change, but good to evaluate separately and discuss)
- heavily document this in the migration guide (#1059) and in our RC4 release docs
- improve semantic markup for components (ex `main`, `nav`)

Related work in later minor versions:

- split up components into smaller components
- allow users to easily customize new layouts using frontmatter (see @kevinlin1's [comment in #959](https://github.com/just-the-docs/just-the-docs/issues/959#issuecomment-1249755249))

Related work for `v1.0` (i.e. a major breaking change):

- rename and better categorize existing includes
    - standardizing the "custom" includes
    - moving other components to the `components/` folder (ex `head`, `nav`)
    - potentially: less confusing naming for various components
- potentially separate the search and header as components, so that they are completely independent 

Tangentially related work:

- more flexible grid (see @JPrevost's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1363314610))
- a formal [feature model](https://en.wikipedia.org/wiki/Feature_model) of JTD, documenting feature dependence (see @pdmosses's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1365414023))
- better annotate new features (motivated by writing these docs)
    - we should add "New" to new features :) 
    - we should note when a feature was introduced (I think this is a core part of most software documentation)
    - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge


--- 

Closes #959.

Avoid the need to add a link to favicon,ico when editing `_includes/head_custom.html`, and avoid creating an invalid favicon link

- Remove the content of `_includes/head_custom.html`
- Add code to `_includes/head.html` to create a link to an existing favicon,ico
- Add an explanation of favicon_ico to docs/configuration.md
- Remove the example of `includes/head_custom.html` and add an explanation of what the `<head>` element automatically includes

Avoid Liquid failure when no pages with titles

Fix issue #1085

The user's config specified collections (incorrectly). Trying to build the site resulted in Jekyll failing due to a Liquid error. The error report did not suggest the cause of the error.

Liquid fails with division by 0 when title_pages_size is 0. This fix guards that code by checking that title_pages is non-empty.

To test:

1.  Specify a Jekyll collection with no pages, and specify it as a JTD collection.
2. Build the site.
3. Check that the specified collection has no nav links to pages.

Hello everyone, this is my implementation for the copy button on the snippet (requested in #924)

The implementation is made 100% javascript as with or without a jekyll template modification you still have to execute some javascript code, and I consider it the best choice.

the button only appears if the mouse is over it, to allow the entire line to be read

the important CSS changes were made to make the copy button work even in the long code situation:


![image](https://user-images.githubusercontent.com/26844016/187731472-d4bf7828-2356-4d94-9c2d-9db863228f5f.png)

to avoid this:

![image](https://user-images.githubusercontent.com/26844016/183292313-d7f73d7d-58c0-4c7b-b5ba-e08bd285514b.png

)

Co-authored-by: Matt Wang <matt@matthewwang.me>

Closes #1070.

This PR:

- updates `jekyll-anchor-headings` to `1.0.12`; this was a simple copy-paste
- updates `lunr.js` to `2.3.9`; this was a bit more involved:
    - I didn't see a minified build in the repo, so I ran it through [DigitalOcean's minifier](https://www.digitalocean.com/community/tools/minify)
    - copyright notices weren't properly included in the previous minified build, so I:
        - include an actual copy of the original MIT License for `lunr.js`
        - includes proper attribution for other functions, which include derivative works

There's a tiny bundle size increase in `lunr.js` due to the comments, but I think that's reasonable given that it's related to licensing; still trivial in the grand scheme of things.

As an aside: it would be neat if we could include minification as part of the build pipeline instead!  

* 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>

In case 'just-the-docs' is used as a theme, and a user does not
eplicitly include 'jekyll-seo-tag' inside the plugins list in
_config.yml, two 'title' elements were rendered. Since
jekyll-seo-tag is always available, because it's set in the plugins
list of the theme itself, the 'seo' tag will aways work, making
the seperate title and description elements obsolete.

Fixes #1008

Fix #1020

- Move the display of nav external links from `_includes/nav.html` to `_layouts/default.html`.
- Replace ` unless include.key` by `if site.nav_external_links`.
- Wrap the body of `if site.nav_external_links` in `<ul class="nav-list">…</ul>`.

To test this PR:

1.  Add to `_config.yml`:
    ```yaml
    defaults:
      -
        scope: {path: ""}
        values: {nav_exclude: true}
    ```

2.  Check that the only link to appear in the nav panel is external.

Co-authored-by: Matt Wang <matt@matthewwang.me>

* Fix top-level active link

Fixes #1014

1.  Reverse the order of `page.parent == node.title or page.grand_parent == node.title`. This makes no difference.
2.  Replace `page.parent == node.title` by `page.parent == node.title  and page.grand_parent == nil`. The condition is evaluated first because it is rightmost.
    We have `node in first_level_pages`.
    The old condition holds not only when `page` is a child of `node`,
    but also when `page` is a grandchild of a *different* top-level page and its parent happens to have the same title as `node`.
    The new condition never holds for a grandchild.

This change has been tested locally: in v0.4.0.rc3, when the 3rd-level page `G` was selected, the link to the top-level page `F` was active, and the link to its child `G` was shown; after making the change, it is no longer active, so the link to its child `G` is not shown.

* Update nav.html

Add a comment to clarify just when top-level nodes are active.

This way, custom styles are able to override the callout styles, which were previously included last.

The regression tests in https://just-the-docs.github.io/just-the-docs-tests/navigation/grandparent/index/ include a section "A grandchild with the same parent title as a child or top-level page". Its last item fails, as can currently be seen at https://just-the-docs.github.io/just-the-docs-tests/navigation/grandparent/f/ : the first occurrence of `G` links to the grandchild of `E`., and shouldn't be included.

The regression can be fixed by changing `where: "grand_parent", page.parent` to `where_exp: "item", "item.grand_parent == page.parent"`. This should be apparent  when running the regressions tests with this PR branch as remote theme.

The two filters give the same results in Jekyll 4, but not in Jekyll 3. It seems that this was overlooked because the sanity-testing of v0.4.0.rc3 was inadvertently using Jekyll 4.2.2.

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>

Closes #961. Replays a previous attempt.

Closes #963.

- redundant `role="navigation"` on nav elements
- redundant `type="text/javascript"` on script tags
- misplaced mermaid script tag

Note that [running the validator on the deploy preview](https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-964--just-the-docs.netlify.app%2F) has no errors now!

An occurrence of `grandchild` was miss-spelled `grand_child` (!).
That caused omission of the `active` class in the link in the nav panel for all grandchildren.

This bug was discovered using `diff` to compare the generated sites built using v0.4.0.rc1 and commit  4396b6b1c836f354bb7aa7edc1a06a49f137d615 on the fix-nav-performance PR branch.

Fix #863.

The current Liquid code to generate the navigation panel involves the inefficient extraction of a list of pages from a list of page groups (identified by @captn3m0 in his original [explanation of the performance issue](https://github.com/just-the-docs/just-the-docs/issues/863)). 

The optimisation implemented by this PR generates navigation links directly from the list of page groups, thereby avoiding the extraction of a list of pages from it. The Liquid code is now a bit tedious, but I don't see a simpler solution. 

The need for grouping pages arises because Jekyll doesn't provide a filter to sort a list of pages on the value of an arbitrary expression.

Using Jekyll v4.2.2 (macOS 12.5, M2 MacBook Air, 16 GB memory), building https://github.com/endoflife-date/endoflife.date using https://github.com/pdmosses/just-the-docs/blob/fix-nav-performance/_includes/nav.html produced the following profile extract:

Filename                                                    | Count |    Bytes |   Time
------------------------------------------------------------|-------|----------|-------
| just-the-docs-0.4.0.rc1/_layouts/default.html                    |   130 |  3792.04K |  5.160 |
| _includes/nav.html                                               |   130 |  1405.20K |  4.054 |
| just-the-docs-0.4.0.rc1/_includes/head.html                      |   130 |   617.82K |  0.495 |
| _layouts/product.html                                            |   127 |  1014.38K |  0.413 |
| _includes/head_custom.html                                       |   130 |   427.83K |  0.393 |
| assets/js/zzzz-search-data.json                                  |     1 |   149.31K |  0.050 |

@nathancarter has tried adding the new `nav.html` to [a site with over 300 pages](https://nathancarter.github.io/how2data/site/), and reported that it improved the build time of more than 3 minutes to about 30 seconds.

Further optimisation of navigation might be possible (e.g., using [Jekyll include caching](https://github.com/benbalter/jekyll-include-cache)), but the current optimisation should be sufficient for v0.4.0.

To test that this PR does not appear to affect the navigation panel generated by v0.3.3:

1. Clone https://github.com/just-the-docs/just-the-docs-tests.
2. Update `_config.yml` and `Gemfile` to use this PR branch.
3. Run `bundle update`.
4. Inspect the rendering of the entire collection of navigation tests.

(Many of the differences reported in the GitHub visualisation of the changes are due to shifting much of the code 2 spaces to the left, in connection with moving the first `ul` element to be close to its first item.)

Adds accessible nav elements for nested pages

Why are these changes being introduced:

* The current links to show/hide the nested pages use a visual only
  svg image with no accessible affordance provided so screenreaders
  will not be able to provide appropriate context for users as to what
  they should expect when clicking these links
* You can see the problem by running a tool like ANDI on the current
  main branch of this repository and then running it again on this
  branch. ANDI shows what a screenreader would read.
* You can also use a tool like Voiceover to hear the importance of what
  this introduces to users that use that technology. Before this change,
  Voiceover would read all of these navigation links as
  "link image just-the-docs" but with this change it will read
  `link image toggle links in <categoryName> category`

Relevant ticket(s):

* This was discussed as part of the larger WCAG compliance ticket
  https://github.com/just-the-docs/just-the-docs/issues/566

How does this address that need:

* This adds an `aria-label` to the link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label

Document any side effects to this change:

It appears it might be prefereable to use `aria-labelledby` whenever
possible, but from what I can tell these links are just the visual cue
of the svg with no other affordance given to users to understand what
they'll do so there is nothing to point `aria-labelledby` at.

An `svg` title was considered, but in reading more about it it seemed
like `aria-label` was more appropriate as it puts the label on the `a`
rather than the `svg` which feels more accurate.

* https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title
* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby



Co-authored-by: Matt Wang <matt@matthewwang.me>

`mermaid`: refactor config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` (#909)

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!

- add an extra filter to children-list to fix #854
- strengthen condition for assignment to first_level_url

Tested with Jekyll 3.9.2 and 4.2.2

Note: Jekyll 3.9.2 doesn't support `| where: "grand_parent:  nil"`

Based on #238, resolves #66.

Closes #825


Co-authored-by: Matt Wang <matt@matthewwang.me>

**Rationale**
I would like to customize the site footer content without needing to override the entire default layout. Ideally, I'd like to shorten the attribution to something like "Built with Just the Docs"

**Implementation**
Create a new `site_footer.html` include that users can override.

**Possible changes**
I debated whether or not the `<footer class="site-footer">` should be in/out of the include. I opted for placing it inside the include so I have the option of disabling the footer entirely by creating an empty site_footer file in my site.

Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>

Set `child_nav_order` to `desc` to reverse the sort order for a child section.

Co-authored-by: Matt Wang <matt@matthewwang.me>

* implements search placeholder configuration

* changes implementation approach to use search_placeholder_custom

Thanks to @pdmosses for the suggestion!

* strips whitespace and HTML for both placeholder and aria-label

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.

Correction needed for use of collections.

Co-authored-by: Kevin Lin <kevinl@cs.uw.edu>

Fixed conversion of numeric titles to strings.

Indentation adjusted