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