Context: #1074, #1076. I think the problem is likely with `@use "sass:math";`; the stock pages image doesn't contain an up-to-date enough version of SASS. I've instead replaced just that instance with a runtime `calc()` operation, which *should* get optimized away by the compiler (see: [SASS docs](https://sass-lang.com/documentation/breaking-changes/slash-div#transition-period)).
---
Original PR body:
> @pdmosses noticed that we have deprecation warnings on some of our SASS code. After testing locally, all of them have to do with using / as division in SASS, which is [deprecated](https://sass-lang.com/documentation/breaking-changes/slash-div) (since there's some lexical ambiguity).
>
> SASS has a nifty [migrator tool](https://github.com/sass/migrator). I used the migrator piecewise on each deprecation warning (since the global usage fails on some liquid code). Upon manual inspection, I think there are no false positives. Running bundle exec jekyll serve after a fresh install and bundle update no longer emits any warnings.
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!
@pdmosses noticed that we have deprecation warnings on some of our SASS code. After testing locally, all of them have to do with using `/` as division in SASS, which is [deprecated](https://sass-lang.com/documentation/breaking-changes/slash-div) (since there's some lexical ambiguity).
SASS has a nifty [migrator tool](https://github.com/sass/migrator). I used the migrator piecewise on each deprecation warning (since the global usage fails on some liquid code). Upon manual inspection, I think there are no false positives. Running `bundle exec jekyll serve` after a fresh install and `bundle update` no longer emits any warnings.
Closes#1073; blocked by #1072 (CI failure).
This PR adds a `deploy.yml` to match [what's in our template repository](https://github.com/just-the-docs/just-the-docs-tests). I think it would be a great idea for us to match parity, especially:
- so that it's easier for us to help users & debug
- so that if we move to Jekyll 4 (likely soon), the transition is seamless
- so that we can explore adding custom items to the build step
Before merging this, we'll also need to change the source of the Pages deploy to actions (from the current branch deploy).
tl;dr:
- replaces `jekyll/jekyll` with actions-native container
- changes Jekyll version targets to be explicit: `[3.9, 4.3]`
- fixes CI bug from today
I've **temporarily changed the branch protection rules** so we can merge this PR in.
## Motivations
A handful of motivations for me doing this:
- immediately: in writing #1071, I noticed that our CI is broken; this is due to an issue with the `jekyll/jekyll` container (see below)
- generally: I would like to make our CI as close to what our users would be using; I think the vast majority of our users use pages or actions, rather than the container itself
- nit: building `3.8.5` is *really slow* (takes ~ 3 minutes), and now each matrix strategy takes ~ 30 seconds with no cache!
More on each of those points now!
### Immediate Problem: `sass-embedded`
Starting today, CI fails on `main`. #1071 has one example ([CI log](https://github.com/just-the-docs/just-the-docs/actions/runs/3752287338/jobs/6374267086)), and I was able to repro this on a whitespace change with the `README`.
Several notes:
- building locally, with pages, or with Netlify does not fail; for example, the deploy preview for #1071 still works
- the error has to do with native extensions (of which `sass-embedded` is one of them) not being built properly for musl c linux; changing the pinned version of `sass-embedded` to a previous version does *not* resolve this problem
- it's not transparent what has changed: the `jekyll/jekyll` image itself has not been updated in over a month, but, something in the container (which was not pinned) must have changed and forced an error with compilation
Given that *our users* won't encounter this problem, this reads easily as a CI problem to me - we should resolve our pipeline (and not change user code/artifacts).
### Bigger Picture: `jekyll/jekyll`
Disclaimer: I have never really liked that we use `jekyll/jekyll` as part of our CI pipeline. Let me outline why and why I think this change is a good idea.
Broadly, our CI should closely match how our users use just the docs. After fielding support requests, looking at our big players, etc., I think the most common deployment methods are:
1. using native GitHub Pages. Recently, [GitHub has moved this to use GitHub Actions and their containers](https://github.blog/2022-08-10-github-pages-now-uses-actions-by-default)
2. using GitHub Actions explicitly, like what's provided in our template
3. "out-of-the-box" CD from providers like Netlify, Vercel, or Fly
In contrast, I have met few users using the `jekyll/jekyll` or `jekyll/builder` containers; of course, this is still anecdotal.
Thus, I think our CI should match the common denominator in the vast majority of our user base, which is *not* using the community container, but instead a standard linux container + bolting on Ruby tooling. Given that GitHub Pages is likely our biggest userbase, I think we should match it - which means, using Actions-specific containers (what's in this PR).
Furthermore, I think it's more likely that a user who wants a container is more knowledgeable about deployment and can resolve problems not caught by CI by themselves and/or submit an issue to GitHub, so switching off of this is fine; now, our CI will better match users who are less familiar with CD (and are likely to just use Pages out of the box).
I also will point out that `jekyll/jekyll` is **not a first-party container**, even though the namespace makes it seem like it is; it's maintained by [envygeeks](https://github.com/envygeeks/jekyll-docker). While this is very kind of them, it adds an external dependency that I would prefer to avoid.
### Build Time and `3.8.5`
This is short, but `3.8.5` isn't the latest `3` release; it's not even the latest minor patch. Since it's a "stale" container, pulling it takes a really long time (upwards of 3 minutes).
Bumping to the latest minor shouldn't affect downstream users, and has faster CI for us - which means quicker dev turnaround :)
* 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>
* Update the theme home page
Major update:
- Refer to `just-the-docs-template` for getting started.
- Avoid duplication of details provided in the template docs.
- Distinguish between theme users and theme developers.
- Update the callouts.
- Make the marked-up text easier to read and edit by using short-cut link references.
* Update index.md
- Add a reference to the theme README for using the theme as a gem.
- Add a footnote separator line.
* Update README.md
Major update:
- Refer to `just-the-docs-template` for getting started.
- Avoid duplication of details provided in the template README.
- Distinguish between theme users and theme developers.
- Augment the items for submitting code changes
- Make the marked-up text easier to read and edit by using short-cut link references.
(Not yet checked on GitHub.)
* Restore docs for using JTD as a gem
* 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.
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>
