Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • editors
  • open-analysis-update
  • 48-documentation-guide-on-credit
  • new-jekyll-setup
5 results
Search by author
  • Any Author
  • Alberto Lazari Alberto Lazari alazari
  • Anna Guttesen Anna Guttesen nnm329
  • Bernd Taschler Bernd Taschler ndcn1032
  • Cassandra Gould van Praag Cassandra Gould van Praag cassag
  • David Flitney David Flitney flitney
  • Duncan Mortimer Duncan Mortimer duncan
  • Duncan Smith Duncan Smith dsmith
  • Evan Edmond Evan Edmond edmond
  • Fidel Alfaro Almagro Fidel Alfaro Almagro falmagro
  • Gaurav Bhalerao Gaurav Bhalerao mcz502
  • Juju Fars Juju Fars pfr545
  • Kirralise Hansford Kirralise Hansford bcy376
  • Lara Nikel Lara Nikel lara.nikel
  • Laurence Hunt Laurence Hunt lhunt
  • Lilian Weber Lilian Weber psyc1406
  • Lisa Spiering Lisa Spiering wym003
  • Ludovica Griffanti Ludovica Griffanti ludovica
  • Luke Baxter Luke Baxter lbaxter
  • Marieke Martens Marieke Martens mmartens
  • Mark Jenkinson Mark Jenkinson mark
20 authors
  1. Dec 27, 2022
  3. Dec 26, 2022
  5. Dec 22, 2022
  7. Dec 21, 2022
    • Flo's avatar
      Revert "sass: remove all uses of `/` as SASS division" (#1076) · fff8fef1
      Flo authored
      Unverified
      fff8fef1
    • Matt Wang's avatar
      Update CHANGELOG.md · 8f972e59
      Matt Wang authored
      Unverified
      8f972e59
    • Matt Wang's avatar
      vendor: update `jekyll-anchor-headings`, `lunr.js` (#1071) · 197d18d8
      Matt Wang authored 
      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!
      Unverified
      197d18d8
    • Matt Wang's avatar
      Update CHANGELOG.md · 253a65c0
      Matt Wang authored
      Unverified
      253a65c0
    • Matt Wang's avatar
      sass: remove all uses of `/` as SASS division (#1074) · 12ea042b
      Matt Wang authored 
      @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).
      Unverified
      12ea042b
    • Matt Wang's avatar
      deploy: use GitHub Actions Pages workflow (#934) · e26bdd36
      Matt Wang authored 
      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).
      Unverified
      e26bdd36
    • Matt Wang's avatar
      ci: remove `jekyll/jekyll` container (#1072) · 002387bc
      Matt Wang authored 
      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 :)
      Unverified
      002387bc
  9. Dec 18, 2022
  11. Dec 17, 2022
  13. Dec 13, 2022
  15. Dec 08, 2022
  17. Dec 05, 2022
  19. Nov 23, 2022
  21. Nov 15, 2022
  23. Nov 05, 2022
  25. Oct 30, 2022
    • Matt Wang's avatar
      Update CHANGELOG.md · ee2e3245
      Matt Wang authored
      Unverified
      ee2e3245
    • Peter Mosses's avatar
      Fix top-level active link (#1015) · 063acaca
      Peter Mosses authored 
      * 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.
      Unverified
      063acaca
  27. Oct 25, 2022
  29. Oct 24, 2022