In #1058, I noted:

> Tangentially related work:
> ...
> - 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
> 

This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later.

This PR is me doing that. I:

- have added a headings-level "New" label to every new heading introduced since `v0.3`
- added, when possible, inline YAML comments when new configuration options have been introduced

I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation.

I may have also missed any new features, so some double-checking would be helpful!

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>

In touching up the migration guide, I noticed that many of our documentation site links are broken! For example, on the homepage, this link:

<img width="782" alt="screenshot of homepage; code snippet is in next block" src="https://user-images.githubusercontent.com/14893287/210462690-31aa7bf5-dd79-4e8f-a3c5-1213e73771c4.png">

which has the following href

```code
<a href="/just-the-docs/just-the-docs/CHANGELOG/">the CHANGELOG</a>
```

duplicates the `baseurl` twice. There are 14 such broken links across the site. Each link duplicates the `baseurl` and `link` tags, which has since been resolved with links being relative by default (there's a set of PRs that document this - I can't find the exact paper trail right now).

To resolve this, I:

- find and replace site-wide `{{ site.baseurl }}{% link` with `{% link`
- tested each link, which now works properly locally *and* on the deploy preview

I'm surprised we didn't catch this earlier! I also could be missing something else, in which case feedback on this PR is certainly welcome.

The typography utilities page has been moved sopme time ago, but the button URL was not updated. This commit fixes the broken link.

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

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

* docs(collections): Add warning about mandatory `_`-prefix

* Apply recommended wording

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>

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

Closes #961. Replays a previous attempt.

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.)

Follow-up to #613. Relatively self-explanatory!

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

Added a missing `{: .no_toc }`, to avoid a 3rd-level item in the displayed TOC at the top of the page.

Short and sweet PR that addresses the follow-up in #909: enabling `mermaid` on our docs site, but making it clear that users still need to opt-in to use it. I've also added an example in-action.

To test: [see the Netlify deploy](https://deploy-preview-935--just-the-docs.netlify.app/docs/ui-components/code/#mermaid-diagram-code-blocks).

`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!

Closes #899 (or at least, the immediate concern).

Fix #734.

- Remove `white-space: nowrap;` in `_sass/content.scss`.
- Add an example testing wrapping in`docs/index-test.md`.

Fixes a problem where multiple labels right after a heading are vertically misaligned.

Closes #751.

Based on #238, resolves #66.

Closes #825


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

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

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

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

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>

* Show how to break an ol

Close #750

The theme uses CSS counters for ordered lists.
So to continue the numbering of an ordered list after a break,
use `style="counter-reset:none"` instead of `start="42"`.
Add the example from #750 to `docs/index-test.md` to test.

* Show how to start from 42

Close #750

The theme uses CSS counters for ordered lists.
To start the numbering of an ordered list with 42,
use `{:style="counter-reset:step-counter 41"}` instead of `start="42"`.

Add the example from #750 to `docs/index-test.md` to test.

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>

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