* Allow unlimited multi-level navigation
This PR supersedes #462.
The only user-level difference from #462 is that disambiguation of parent pages has to use either `grand_parent` or `ancestor` titles: the somewhat unnatural `section_id` and `in_section` fields are not supported.
The implementation has been significantly simplified by the changes introduced in v0.7.0 of the theme.
* Detect cyclic parenthood
A page should not have a parent or ancestor with the same title. If it does, the location of the repeated link is marked by ∞, to facilitate debugging the navigation (and an unbounded loop leading to a build exception is avoided).
* Add nav_error_report warning in main navigation
When activated by `nav_error_report: true` in `_config.yml`, displays warnings about pages with the same title as their parent page or an ancestral page.
* Cache site-nav with links to all pages
The extra cached site-nav is used for determining breadcrumbs and children navigation, which may involve pages that are excluded from the main navigation.
* Replace code for determining children by inclusion of components/nav/children.html
* Update CHANGELOG.md
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Add nav_enabled variables for site/layout/page-level control
* _sass: Add a space around `+` operator
* assets: Do not compile based on site.nav_enabled
* _config.yml: nav_enabled can be selectively enabled
* CHANGELOG.md: Add nav_enabled feature and docs
* docs: Prefer em dash in describing minimal layout
* docs: Add section on Selectively hiding or showing the sidebar
* _layouts: Display sidebar based on variable importance
* docs: Update documentation on the minimal layout
* docs: Document site.nav_enabled configuration variable
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR is motivated from https://github.com/just-the-docs/just-the-docs/pull/1259#issuecomment-1655899503. It adds a new workflow (`CI / Validate HTML (3.1)`) that validates the output of `bundle exec jekyll build`. It does this with two separate tools:
1. The [`html5validator-action`](https://github.com/Cyb3r-Jak3/html5validator-action), which is a wrapper (Docker image + argument forwarding) around the [Nu HTML checker](https://github.com/validator/validator), which is what is used by the [W3C markup validation service](https://validator.w3.org/)
2. [`html-proofer`](https://github.com/gjtorikian/html-proofer), which performs auxiliary checks on the validity of script, image, and link *values*, but not the markup itself
- note: prior versions of `html-proofer` did use nokogiri to also validate HTML, but the author has elected to remove that feature in versions 4+
I then fix a few issues that are flagged by these tools. I'll split this into,
**changes affecting users**:
- strictly incorrect: in `_layouts/minimal.html`, a `<div>` had duplicate `id`s. I've removed the incorrect one, which is related to...
- semantically wrong (but not technically incorrect): in both `minimal` and `default` layouts, we had two `<div>` tags with `id="main-content-wrap"`. These don't do anything; the associated styling is with the *class* `main-content-wrap`. I've elected to remove these `id`s to avoid confusion and keep the layouts in sync; however, **this is technically a breaking change**
- observe that `#main-content` is used for the "skip to main content" feature, which I missed in an earlier iteration of this PR
**changes affecting only our documentation**
- a broken link to mermaid docs (I've changed it to a valid one)
- an incorrectly-specified `aux_link` to our own repository
- various links that point to the bare URL `another-page`, which is clearly invalid; I've changed these to point to our homepage
- an incorrect header link
- various links to `http://example.com`, which I've changed to point to our homepage
- an incorrect link to `@flyx`'s profile for the AsciiDoctor gist
- a handful of (otherwise-valid) `http` links that should be `https`: the lunr docs, and patrick's personal website
The commit history shows the Nu validator flagging issues in CI properly in commits [4128b23](4128b23ef2) and [3527220](35272203ba).
## relevant configuration
- I exclude `github.com` URLs from external link checks with `html-proofer`. This is because GitHub does not like it when we ping too frequently, and rate limits us, which in turn provides many false positives. This is aligned with their documentation, which uses this ignore.
- I've pinned the hash for the 3rd-party action that wraps the W3C markup validation service. This aligns with #1148, but means that we'll have to keep an eye on it for updates.
This PR fixes several Axe errors I found while working on https://viewcomponent.org/. I did not see any visual regressions on my deploy, but I'd encourage testing with other sites.
---------
Co-authored-by: Lindsey Wild <35239154+lindseywild@users.noreply.github.com>
* Refactor nav, breadcrumbs, children_nav
Fix#1118
Improve the modularity of building the nav-panel, breadcrumbs, and children-nav
by making them independent. This also significantly simplifies the Liquid code.
* Fix order of breadcrumbs
* Update breadcrumbs.html
Revert inclusion of single breadcrumb for top-level pages.
* Update breadcrumbs.html
* Update children_nav.html
Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.
* Update minimal.html
Remove the previously required workaround involving `nav.html`.
* Add docs pages about layouts
The aim of the initial version of these docs pages is to illustrate the difference between the default and minimal layouts.
* Update CHANGELOG.md
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.
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>
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!
**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>
* 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.
