This is a PR with three key changes:
1. Consolidate two identical CI files, `ci.yml` and `ci-master.yml` into one file
2. Consolidate two almost-identical jobs (`jekyll-build-*`) into one job with a strategy matrix
3. Update various dependencies/platforms
* Node: `12.x` -> `16.x` (only in CI); `12.x` has been EOL for a while
* Ruby: `2.6` -> `2.7`; `2.6` just reached EOL
* `actions/checkout` -> `v2` -> `v3`
* switches `jekyll/builder` to `jekyll/jekyll`, since we don't actually use any of the features in `jekyll/builder`
## on our CI philosophy
In working on this, I have a couple of questions:
1. We don't actually use our `Dockerfile` that we provide. Does this make sense? Should we be running CI with this instead?
2. Is there a specific reason that we're using `jekyll/jekyll`? Notably, this isn't an official package, but a community-driven one. Does it match what's used by GitHub Pages?
3. Do we have to use any docker image at all? For example, what if we just rely on the `setup-ruby` action?
* one advantage of this is that it's much easier for us to test across multiple OS versions; we just need to have a strategy matrix for OS and do windows, macos, ubuntu, etc.
* another advantage is that we can easily test different ruby versions in conjunction with different jekyll versions
Eventually, I would like to see us test across:
* different Jekyll versions
* different OSes
* different Ruby versions
but perhaps that might be too aggressive. Happy for any feedback on this PR or those questions!
I have a site whose content is written in AsciiDoc, using the [jekyll-asciidoc][] plugin.
Just the Docs works great, but there are just two minor styling glitches I've noticed:
The first is that Just the Docs' CSS doesn't understand the code block markup jekyll-asciidoc produces. It's not too different though, so it's very easily fixed.
The second is that jekyll-asciidoc generates `div.sect(𝑛 − 1)` elements around headings of type `h𝑛`, that enclose all the heading and all the content after it until the next heading of greater or equal rank.
This means that headings are _always_ first children in AsciiDoc output, which meant the wrong margins were applied to most headings. To fix this, we need to only reduce the margin of first-child headings nested directly below the .main-content element, and headings nested directly below AsciiDoc `.sect𝑛` elements that are themselves first children.
With these two small changes, my site looks perfect, and the styles look exactly the same as on Just the Docs' own documentation.
[jekyll-asciidoc]: https://github.com/asciidoctor/jekyll-asciidoc
**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>
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>
* 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
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>
Bumps [lodash](https://github.com/lodash/lodash) from 4.17.19 to 4.17.21. **This update includes a security fix.**
- [Release notes](https://github.com/lodash/lodash/releases)
- [Commits](https://github.com/lodash/lodash/compare/4.17.19...4.17.21)
Signed-off-by: dependabot-preview[bot] <support@dependabot.com>
Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
Co-authored-by: Matt Wang <matt@matthewwang.me>
