From 534d38788cdce5e51e0ed059f025c376adf12500 Mon Sep 17 00:00:00 2001 From: Haris Zafeiropoulos Date: Fri, 22 Sep 2023 03:45:55 +0200 Subject: [PATCH] init synced version of jeckyll --- 404.html | 2 +- CHANGELOG.md | 1601 +++ CODE_OF_CONDUCT.md | 128 +- Dockerfile | 3 +- Gemfile | 7 +- Gemfile.lock | 150 + MIGRATION.md | 493 + README.md | 102 +- _config.yml | 145 +- _sass/support/_functions.scss | 9 - assets/images/just-the-docs.png | Bin 20992 -> 0 bytes assets/images/search.svg | 1 - components/aux_nav.html | 15 - components/breadcrumbs.html | 43 - components/children_nav.html | 33 - components/footer.html | 34 - components/header.html | 11 - components/mermaid.html | 45 - components/search_footer.html | 7 - components/search_header.html | 9 - components/sidebar.html | 83 - docs/api.md | 116 - docs/configuration.md | 330 + docs/customization.md | 406 + docs/cytoApp.md | 22 - docs/index-test.md | 326 + docs/layout/layout.md | 40 + docs/layout/minimal/default-child.md | 8 + docs/layout/minimal/minimal-child.md | 8 + docs/layout/minimal/minimal.md | 12 + docs/minimal-test.md | 9 + docs/modules.md | 133 - docs/navigation-structure.md | 316 + docs/search.md | 167 + docs/tests/index.md | 22 - docs/tests/navigation/disambiguation/a.md | 14 - docs/tests/navigation/disambiguation/b.md | 14 - docs/tests/navigation/disambiguation/ca.md | 16 - docs/tests/navigation/disambiguation/cb.md | 16 - docs/tests/navigation/disambiguation/dca.md | 16 - docs/tests/navigation/disambiguation/dcb.md | 16 - docs/tests/navigation/disambiguation/index.md | 14 - docs/tests/navigation/exclusion/0.md | 13 - docs/tests/navigation/exclusion/00.md | 15 - docs/tests/navigation/exclusion/000.md | 17 - docs/tests/navigation/exclusion/001.md | 17 - docs/tests/navigation/exclusion/01.md | 15 - docs/tests/navigation/exclusion/010.md | 17 - docs/tests/navigation/exclusion/011.md | 17 - docs/tests/navigation/exclusion/1.md | 13 - docs/tests/navigation/exclusion/10.md | 15 - docs/tests/navigation/exclusion/100.md | 17 - docs/tests/navigation/exclusion/101.md | 17 - docs/tests/navigation/exclusion/11.md | 15 - docs/tests/navigation/exclusion/110.md | 17 - docs/tests/navigation/exclusion/111.md | 17 - docs/tests/navigation/exclusion/excluded.md | 11 - docs/tests/navigation/exclusion/index.md | 36 - docs/tests/navigation/exclusion/untitled.md | 6 - docs/tests/navigation/index.md | 8 - docs/tests/navigation/order/default/10.md | 14 - docs/tests/navigation/order/default/2.md | 14 - docs/tests/navigation/order/default/a.md | 14 - .../navigation/order/default/aa-lower.md | 14 - docs/tests/navigation/order/default/aa.md | 14 - docs/tests/navigation/order/default/index.md | 15 - docs/tests/navigation/order/floats/-1.1.md | 16 - docs/tests/navigation/order/floats/0.0.md | 16 - docs/tests/navigation/order/floats/10.0.md | 16 - docs/tests/navigation/order/floats/2.2222.md | 16 - docs/tests/navigation/order/floats/index.md | 13 - docs/tests/navigation/order/index.md | 16 - docs/tests/navigation/order/integers/-1.md | 16 - docs/tests/navigation/order/integers/0.md | 16 - docs/tests/navigation/order/integers/10.md | 16 - docs/tests/navigation/order/integers/2.md | 16 - docs/tests/navigation/order/integers/index.md | 13 - docs/tests/navigation/order/mixture/-1.1.md | 16 - docs/tests/navigation/order/mixture/-1.md | 16 - docs/tests/navigation/order/mixture/0.0.md | 16 - docs/tests/navigation/order/mixture/0.md | 16 - docs/tests/navigation/order/mixture/10.0.md | 16 - docs/tests/navigation/order/mixture/10.md | 14 - docs/tests/navigation/order/mixture/2.2222.md | 16 - docs/tests/navigation/order/mixture/2.md | 14 - docs/tests/navigation/order/mixture/a.md | 14 - .../navigation/order/mixture/aa-lower.md | 16 - docs/tests/navigation/order/mixture/aa.md | 16 - docs/tests/navigation/order/mixture/index.md | 11 - docs/tests/navigation/order/order.md | 7 - docs/tests/navigation/order/strings/10.md | 16 - docs/tests/navigation/order/strings/2.md | 16 - docs/tests/navigation/order/strings/a.md | 16 - .../navigation/order/strings/aa-lower.md | 16 - docs/tests/navigation/order/strings/aa.md | 16 - docs/tests/navigation/order/strings/index.md | 13 - docs/tests/styling/dl.md | 83 - docs/tests/styling/index.md | 8 - docs/tests/styling/ol.md | 65 - docs/tests/styling/ul.md | 65 - docs/ui-components/buttons.md | 97 + docs/ui-components/callouts.md | 161 + docs/ui-components/code.md | 205 + docs/ui-components/labels.md | 49 + docs/ui-components/line-nos.md | 129 + docs/ui-components/lists.md | 99 + docs/ui-components/tables.md | 29 + docs/ui-components/typography.md | 114 + docs/ui-components/ui-components.md | 12 + docs/utilities/color.md | 82 + docs/utilities/layout.md | 127 + docs/utilities/responsive-modifiers.md | 18 + docs/utilities/typography.md | 156 + docs/utilities/utilities.md | 13 + favicon.ico | Bin 245054 -> 32988 bytes index.md | 114 +- just-the-docs.gemspec | 26 +- package-lock.json | 9580 +++++++---------- package.json | 48 +- script/build | 8 - 120 files changed, 9574 insertions(+), 7475 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 Gemfile.lock create mode 100644 MIGRATION.md delete mode 100644 _sass/support/_functions.scss delete mode 100644 assets/images/just-the-docs.png delete mode 100644 assets/images/search.svg delete mode 100644 components/aux_nav.html delete mode 100644 components/breadcrumbs.html delete mode 100644 components/children_nav.html delete mode 100644 components/footer.html delete mode 100644 components/header.html delete mode 100644 components/mermaid.html delete mode 100644 components/search_footer.html delete mode 100644 components/search_header.html delete mode 100644 components/sidebar.html delete mode 100644 docs/api.md create mode 100644 docs/configuration.md create mode 100644 docs/customization.md delete mode 100644 docs/cytoApp.md create mode 100644 docs/index-test.md create mode 100644 docs/layout/layout.md create mode 100644 docs/layout/minimal/default-child.md create mode 100644 docs/layout/minimal/minimal-child.md create mode 100644 docs/layout/minimal/minimal.md create mode 100644 docs/minimal-test.md delete mode 100644 docs/modules.md create mode 100644 docs/navigation-structure.md create mode 100644 docs/search.md delete mode 100644 docs/tests/index.md delete mode 100644 docs/tests/navigation/disambiguation/a.md delete mode 100644 docs/tests/navigation/disambiguation/b.md delete mode 100644 docs/tests/navigation/disambiguation/ca.md delete mode 100644 docs/tests/navigation/disambiguation/cb.md delete mode 100644 docs/tests/navigation/disambiguation/dca.md delete mode 100644 docs/tests/navigation/disambiguation/dcb.md delete mode 100644 docs/tests/navigation/disambiguation/index.md delete mode 100644 docs/tests/navigation/exclusion/0.md delete mode 100644 docs/tests/navigation/exclusion/00.md delete mode 100644 docs/tests/navigation/exclusion/000.md delete mode 100644 docs/tests/navigation/exclusion/001.md delete mode 100644 docs/tests/navigation/exclusion/01.md delete mode 100644 docs/tests/navigation/exclusion/010.md delete mode 100644 docs/tests/navigation/exclusion/011.md delete mode 100644 docs/tests/navigation/exclusion/1.md delete mode 100644 docs/tests/navigation/exclusion/10.md delete mode 100644 docs/tests/navigation/exclusion/100.md delete mode 100644 docs/tests/navigation/exclusion/101.md delete mode 100644 docs/tests/navigation/exclusion/11.md delete mode 100644 docs/tests/navigation/exclusion/110.md delete mode 100644 docs/tests/navigation/exclusion/111.md delete mode 100644 docs/tests/navigation/exclusion/excluded.md delete mode 100644 docs/tests/navigation/exclusion/index.md delete mode 100644 docs/tests/navigation/exclusion/untitled.md delete mode 100644 docs/tests/navigation/index.md delete mode 100644 docs/tests/navigation/order/default/10.md delete mode 100644 docs/tests/navigation/order/default/2.md delete mode 100644 docs/tests/navigation/order/default/a.md delete mode 100644 docs/tests/navigation/order/default/aa-lower.md delete mode 100644 docs/tests/navigation/order/default/aa.md delete mode 100644 docs/tests/navigation/order/default/index.md delete mode 100644 docs/tests/navigation/order/floats/-1.1.md delete mode 100644 docs/tests/navigation/order/floats/0.0.md delete mode 100644 docs/tests/navigation/order/floats/10.0.md delete mode 100644 docs/tests/navigation/order/floats/2.2222.md delete mode 100644 docs/tests/navigation/order/floats/index.md delete mode 100644 docs/tests/navigation/order/index.md delete mode 100644 docs/tests/navigation/order/integers/-1.md delete mode 100644 docs/tests/navigation/order/integers/0.md delete mode 100644 docs/tests/navigation/order/integers/10.md delete mode 100644 docs/tests/navigation/order/integers/2.md delete mode 100644 docs/tests/navigation/order/integers/index.md delete mode 100644 docs/tests/navigation/order/mixture/-1.1.md delete mode 100644 docs/tests/navigation/order/mixture/-1.md delete mode 100644 docs/tests/navigation/order/mixture/0.0.md delete mode 100644 docs/tests/navigation/order/mixture/0.md delete mode 100644 docs/tests/navigation/order/mixture/10.0.md delete mode 100644 docs/tests/navigation/order/mixture/10.md delete mode 100644 docs/tests/navigation/order/mixture/2.2222.md delete mode 100644 docs/tests/navigation/order/mixture/2.md delete mode 100644 docs/tests/navigation/order/mixture/a.md delete mode 100644 docs/tests/navigation/order/mixture/aa-lower.md delete mode 100644 docs/tests/navigation/order/mixture/aa.md delete mode 100644 docs/tests/navigation/order/mixture/index.md delete mode 100644 docs/tests/navigation/order/order.md delete mode 100644 docs/tests/navigation/order/strings/10.md delete mode 100644 docs/tests/navigation/order/strings/2.md delete mode 100644 docs/tests/navigation/order/strings/a.md delete mode 100644 docs/tests/navigation/order/strings/aa-lower.md delete mode 100644 docs/tests/navigation/order/strings/aa.md delete mode 100644 docs/tests/navigation/order/strings/index.md delete mode 100644 docs/tests/styling/dl.md delete mode 100644 docs/tests/styling/index.md delete mode 100644 docs/tests/styling/ol.md delete mode 100644 docs/tests/styling/ul.md create mode 100644 docs/ui-components/buttons.md create mode 100644 docs/ui-components/callouts.md create mode 100644 docs/ui-components/code.md create mode 100644 docs/ui-components/labels.md create mode 100644 docs/ui-components/line-nos.md create mode 100644 docs/ui-components/lists.md create mode 100644 docs/ui-components/tables.md create mode 100644 docs/ui-components/typography.md create mode 100644 docs/ui-components/ui-components.md create mode 100644 docs/utilities/color.md create mode 100644 docs/utilities/layout.md create mode 100644 docs/utilities/responsive-modifiers.md create mode 100644 docs/utilities/typography.md create mode 100644 docs/utilities/utilities.md delete mode 100755 script/build diff --git a/404.html b/404.html index 5fde966..a2d250a 100644 --- a/404.html +++ b/404.html @@ -8,4 +8,4 @@

Page not found

-

The page you requested could not be found. Try using the navigation {% if site.search_enabled != false %}or search {% endif %}to find what you're looking for or go to this site's home page.

+

The page you requested could not be found. Try using the navigation {% if site.search_enabled != false %}or search {% endif %}to find what you're looking for or go to this site's home page.

diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..74fa91a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1601 @@ +--- +title: CHANGELOG +layout: default +--- + +# CHANGELOG + +All notable user-facing changes to this project are documented in this file. + +{: .highlight } +The project underwent a major maintenance shift in March 2022. + +## HEAD + +{: .note } +This website is built from the `HEAD` of the `main` branch of the theme repository. + +Code changes to `main` that are *not* in the latest release: + +- N/A + +## Release v0.6.2 + +Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6. + +### Bugfixes + +- Fixed: Windows emoji font fallback by [@flanakin] in [#1337] +- Removed: unused `.passive` toggle in navigation by [@pdmosses] in [#1335] + +[#1335]: https://github.com/just-the-docs/just-the-docs/pull/1335 +[#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337 + +### New Contributors + +- [@flanakin] made their first contribution in [#1337] + +[@flanakin]: https://github.com/flanakin + +## Release v0.6.1 + +Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation. + +### Bugfixes + +- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332] + +[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332 + +## Release v0.6.0 + +Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme. + +### Migrating to `v0.6.0` + +**Migration**: users will need to migrate if: + +- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid` +- they have code that refers to `#main-content-wrap` +- they override the default `light` theme's code, or the theme-loading logic +- they have different favicons for different pages + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.6.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.6.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.6.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.6.0" +``` + +To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag. + +### New Features and Bugfixes + +- Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280] +- Fixed: build times for large sites by [@pdmosses] in [#1244] +- Fixed: missing closing `` tag in `sidebar.html` by [@mattxwang] in [#1304] +- Fixed: removed duplicate `#main-content-wrap` minimal and default layouts by [@mattxwang] in [#1305] + +### Documentation + +{: .warning } +The theme docs are unversioned, and already reflect the above changes. + +Docs changes: + +- A [footnote]({% link docs/configuration.md %}#fn:js-disabled) in the configuration docs explains how disabling JavaScript affects the display of navigation links when browsing folded collections. +- Invalid HTML has been removed from most documentation examples. + +### New Contributors + +- [@sigv] made their first contribution in [#1280] + +[@sigv]: https://github.com/sigv +[#1244]: https://github.com/just-the-docs/just-the-docs/pull/1244 +[#1280]: https://github.com/just-the-docs/just-the-docs/pull/1280 +[#1304]: https://github.com/just-the-docs/just-the-docs/pull/1304 +[#1305]: https://github.com/just-the-docs/just-the-docs/pull/1305 + +## Release v0.5.4 + +Hi all, this is a small patch release that only includes one change: fixing a style clash between Mermaid's labels and Just the Docs' labels. + +*Note: for subsequent patch releases, we will omit migration instructions (for brevity). In all cases, immediate migration should be backwards-compatible. Refer to previous major or minor update instructions for more information.* + +### Bugfixes + +- Fixed: Mermaid labels inheriting theme `.label` styling by [@mattxwang] in [#1278] + +[#1278]: https://github.com/just-the-docs/just-the-docs/pull/1278 + +## Release v0.5.3 + +Hi all, this is a minor patch release that only includes one change: changing all text-based CSS properties to use `rem` instead of hard-coded `px` values. This has two effects: + +1. All deprecation warnings are now fixed on build; you should now get a clean build with `jekyll build`. +2. We have **deprecated the `$root-font-size` SCSS variable**. We will remove it in an upcoming release of the theme. + +If you use the stock Just the Docs theme, this release should have no impact on your final built site. If you change the `$root-font-size` SCSS variable, you might experience light layout shifts. + +### Using Release `v0.5.3` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.3` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.3 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.3" +``` + +To use and pin a previous version of the theme, replace the `0.5.3` with the desired release tag. + +### Bugfixes + +- Fixed: font-size scaling for text-related CSS properties by using `rem` instead of fixed `px` values; deprecate `$root-font-size` by [@mattxwang] in [#1169] + +[#1169]: https://github.com/just-the-docs/just-the-docs/pull/1169 + +## Release v0.5.2 + +Hi all, this is a minor patch release that mostly focuses on accessibility. Since we follow semantic versioning, this should be a smooth upgrade with no breaking changes. + +In addition, the theme docs website has a new canonical URL: . We've also retroactively published the theme docs website for version `v0.3.3` at . Thank you to our GitHub sponsors for funding our domain name! + +### Using Release `v0.5.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.2 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.2" +``` + +To use and pin a previous version of the theme, replace the `0.5.2` with the desired release tag. + +### Bugfixes + +- Fixed: liquid variable leakage in navigation components by [@pdmosses] in [#1243] +- Fixed: ARIA roles and labels for search, header, logo, mobile menu button, and main content by [@joelhawksley] in [#1259] +- Fixed: ARIA labels for all anchors with `href="#"`; adds `aria-pressed` information for toggles by [@mattxwang] in [#1262] + +### New Contributors + +- [@joelhawksley] made their first contribution in [#1259] + +[@joelhawksley]: https://github.com/joelhawksley + +[#1243]: https://github.com/just-the-docs/just-the-docs/pull/1243 +[#1259]: https://github.com/just-the-docs/just-the-docs/pull/1259 +[#1262]: https://github.com/just-the-docs/just-the-docs/pull/1262 + +## Release v0.5.1 + +Hi all, this is a very small minor patch release that has two small behavioral bugfixes: fixing a regression introduced in `v0.5.0` on Safari versions `<16.4` (broken media query), and the copy code button providing incorrect feedback in insecure browser contexts. This should be a smooth upgrade with no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.5.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.1 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.1" +``` + +To use and pin a previous version of the theme, replace the `0.5.1` with the desired release tag. + +### Bugfixes + + +- Fixed: disable copy code button in insecure contexts [@rmoff] in [#1226] +- Fixed: context-based media feature not supported by Safari `<16.4` by [@mattxwang] in [#1240] + +### Documentation + +- Added: document copy code button requiring secure context by [@rmoff] in [#1225] +- Fixed: typo ("them" → "theme") in MIGRATION.md by [@waldyrious] in [#1219] +- Fixed: `font-weight` typo (Utilities > Typography) by [@mattxwang] in [#1229] +- Fixed: `just the docs` typo in migration guide by [@mattxwang] in [#1230] + +### New Contributors +- [@rmoff] made their first contribution in [#1225] + +[#1219]: https://github.com/just-the-docs/just-the-docs/pull/1219 +[#1225]: https://github.com/just-the-docs/just-the-docs/pull/1225 +[#1226]: https://github.com/just-the-docs/just-the-docs/pull/1226 +[#1229]: https://github.com/just-the-docs/just-the-docs/pull/1229 +[#1230]: https://github.com/just-the-docs/just-the-docs/pull/1230 +[#1240]: https://github.com/just-the-docs/just-the-docs/pull/1240 + +[@rmoff]: https://github.com/rmoff + +## Release v0.5.0 + +Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`. + +We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Migrating to `v0.5.0` + +**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves. + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.5.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.0" +``` + +To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag. + +### Bugfixes + +- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209] +- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208] +- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190] +- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107] +- Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0) + +[#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107 +[#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187 +[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190 +[#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208 +[#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209 + +## Release v0.4.2 + +Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.com/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.2" +``` + +To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag. + +### Bugfixes + +- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166] +- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173] +- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184] +- Removed: unused dark syntax themes by [@mattxwang] in [#1192] + +### Documentation + +- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2) + +[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166 +[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173 +[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182 +[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184 +[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192 + +## Release v0.4.1 + +Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.1" +``` + +To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag. + +### Bugfixes + +- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165] +- Fixed: AsciiDoc code block styling by [@flyx] in [#1168] +- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177] +- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167] + +### Documentation + +- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108] + +### New Contributors + +- [@flyx] made their first contribution in [#1168] +- [@Dima-369] made their first contribution in [#1177] + +[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108 +[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165 +[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167 +[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168 +[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177 + +[@flyx]: https://github.com/flyx +[@Dima-369]: https://github.com/Dima-369 + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1) + +## Release v0.4.0 + +We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme. + +### Brief Overview - Highlighted Changes + +`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes: + +- better support for dark theme: dark highlighting, search input color +- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content +- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library +- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets +- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links) +- major improvements to nav generation efficiency and robustness +- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content) +- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature) +- [new custom includes](https://just-the-docs.com/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices +- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more! +- more documentation for [custom includes](https://just-the-docs.com/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.com/MIGRATION/) + +*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.* + +### Using Release `v0.4.0` + +Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0" +``` + +If you would prefer to not upgrade, you can enforce that explicitly: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Migration Guide and Strategies + +We've developed a new [migration guide](https://just-the-docs.com/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site. + +**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes. + +Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release. + +For support with migrating to `v0.4.0`, [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Roadmap (What's Next?) + +Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future! + +Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release. + +For version `v0.5`, our roadmap includes: + +- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences +- better GDPR compliance for analytics +- multi-level/recursive navigation (unlimited hierarchy of child pages) + +In future versions, we also plan on: + +- adding better dark theme defaults +- adding better internationalization support +- exploring offline PDF generation +- improving accessibility within the theme +- improving search functionality +- refactoring and improving the robustness of our codebase + +Have ideas for what's next, or want to get involved? [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! We're looking for more contributors and maintainers to help us develop the theme. + +### New Features + +- Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +- Added: custom favicon `_includes` by [@burner1024] in [#364] +- Added: set color for search input by [@pdmosses] in [#498] +- Added: search placeholder configuration by [@mattxwang] in [#613] +- Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +- Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +- Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +- Added: mermaid.js support by [@nascosto] in [#857] +- Added: support for external navigation links by [@SPGoding] in [#876] +- Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes + +- Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +- Fixed: nested task lists (#517) by [@pdmosses] in [#855] +- Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +- Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +- Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +- Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +- Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +- Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +- Fixed: allow links to wrap by [@pdmosses] in [#905] +- Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Maintenance + +- Added: VScode devcontainer by [@max06] in [#783] +- Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +- Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +- Updated: new repo path by [@pmarsceill] in [#775] +- Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +- Updated: README by [@pmarsceill] in [#777] +- Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +- Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +- Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] +- Deleted: unused script directory by [@mattxwang] in [#937] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Documentation + +- Added: docs on how to break an `ol` by [@pdmosses] in [#856] +- Added: docs for custom includes by [@nathanjessen] in [#806] +- Added: document caveat about variable dependencies by [@waldyrious] in [#555] +- Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Added: migration guide by [@pdmosses] in [#1059] +- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138] +- Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +- Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +- Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +- Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +- Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +- Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +- Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +- Fixed: spacing in toc example by [@henryiii] in [#835] +- Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +- Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Fixed: typo in changelog links [@koppor] in [#1000] +- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130] +- Fixed: broken relative page links by [@mattxwang] in [#1106] +- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Updated: `README` demo video by [@codewithfan] in [#1097] + +### New Contributors + +- [@AdityaTiwari2102] made their first contribution in [#477] +- [@svrooij] made their first contribution in [#544] +- [@alexsegura] made their first contribution in [#519] +- [@burner1024] made their first contribution in [#364] +- [@JeffGuKang] made their first contribution in [#221] +- [@dougaitken] made their first contribution in [#782] +- [@max06] made their first contribution in [#783] +- [@sehilyi] made their first contribution in [#499] +- [@nathanjessen] made their first contribution in [#473] +- [@waldyrious] made their first contribution in [#549] +- [@MichelleBlanchette] made their first contribution in [#554] +- [@henryiii] made their first contribution in [#835] +- [@jmertic] made their first contribution in [#726] +- [@jacobhq] made their first contribution in [#846] +- [@UnclassedPenguin] made their first contribution in [#814] +- [@alyssais] made their first contribution in [#829] +- [@nascosto] made their first contribution in [#857] +- [@SPGoding] made their first contribution in [#876] +- [@iridazzle] made their first contribution in [#727] +- [@ivanskodje] made their first contribution in [#891] +- [@Eisverygoodletter] made their first contribution in [#893] +- [@robinpokorny] made their first contribution in [#940] +- [@olgarithms] made their first contribution in [#951] +- [@manuelhenke] made their first contribution in [#941] +- [@JPrevost] made their first contribution in [#950] +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +## Pre-release v0.4.0.rc5 + +Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release. + +This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), `lunr` indexing, and loading `mermaid` locally. In addition, it fixes bugs introduced in `.rc4`: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from `v0.3.3`. + +### Trying out pre-release `v0.4.0.rc5` + +Simlar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc5" +``` + +By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes and Maintenance + +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Docs + +- Docs: add a migration guide by [@pdmosses] in [#1059] +- Docs: update `README` demo video by [@codewithfan] in [#1097] +- Docs: update "View Typography Utilities" link by [@agabrys] in [#1130] +- Docs: fix broken relative page links by [@mattxwang] in [#1106] +- Docs: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Docs: label new features introduced in `v0.4` by [@mattxwang] in [#1138] + +### New Contributors + +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +[#1059]: https://github.com/just-the-docs/just-the-docs/pull/1059 +[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068 +[#1097]: https://github.com/just-the-docs/just-the-docs/pull/1097 +[#1106]: https://github.com/just-the-docs/just-the-docs/pull/1106 +[#1123]: https://github.com/just-the-docs/just-the-docs/pull/1123 +[#1124]: https://github.com/just-the-docs/just-the-docs/pull/1124 +[#1128]: https://github.com/just-the-docs/just-the-docs/pull/1128 +[#1130]: https://github.com/just-the-docs/just-the-docs/pull/1130 +[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135 +[#1138]: https://github.com/just-the-docs/just-the-docs/pull/1138 +[#1139]: https://github.com/just-the-docs/just-the-docs/pull/1139 +[#1142]: https://github.com/just-the-docs/just-the-docs/pull/1142 +[#1143]: https://github.com/just-the-docs/just-the-docs/pull/1143 +[#1153]: https://github.com/just-the-docs/just-the-docs/pull/1153 + +[@agabrys]: https://github.com/agabrys +[@codewithfan]: https://github.com/codewithfan +[@diablodale]: https://github.com/diablodale +[@fabrik42]: https://github.com/fabrik42 +[@kevinlin1]: https://github.com/kevinlin1 +[@EricFromCanada]: https://github.com/EricFromCanada +[@m-r-mccormick]: https://github.com/m-r-mccormick + +## Pre-release v0.4.0.rc4 + +Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. **We aim to re-release this as `v0.4.0`, with only few changes**. + +Notable new additions include: + +- modular site components, which split up the site into smaller reusable components; advanced theme users can then remix layouts quickly without duplication +- a "copy code" button to code blocks +- fixing bugs in generated TOCs and navigation from previous prereleases +- various cleanups of CSS and HTML markup + +The roadmap to `v0.4.0` is small. We are only looking to: + +- finish a migration guide, so users can easily upgrade from `v0.3.3` to `v0.4.0` +- fix one last bug relating to callouts and custom colors +- fix any new bugs introduced by this pre-release + +Have any questions, thoughts, or concerns? We'd love to hear from you! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc4` + +Simlar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc4" +``` + +By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] + +### Bugfixes and Maintenance + +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Docs + +- Docs: fix typo in changelog links [@koppor] in [#1000] +- Docs: update homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Docs: update README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Docs: fix two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Docs: Add warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Docs: remove Google Analytics on main site by [@mattxwang] in [#1113] + +### New Contributors + +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4 + +[#945]: https://github.com/just-the-docs/just-the-docs/pull/945 +[#999]: https://github.com/just-the-docs/just-the-docs/pull/999 +[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000 +[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001 +[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010 +[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015 +[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018 +[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019 +[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021 +[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027 +[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029 +[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040 +[#1058]: https://github.com/just-the-docs/just-the-docs/pull/1058 +[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061 +[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065 +[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071 +[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074 +[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076 +[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077 +[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090 +[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091 +[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092 +[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095 +[#1096]: https://github.com/just-the-docs/just-the-docs/pull/1096 +[#1102]: https://github.com/just-the-docs/just-the-docs/pull/1102 +[#1104]: https://github.com/just-the-docs/just-the-docs/pull/1104 +[#1110]: https://github.com/just-the-docs/just-the-docs/pull/1110 +[#1113]: https://github.com/just-the-docs/just-the-docs/pull/1113 + +[@captn3m0]: https://github.com/captn3m0 +[@deseo]: https://github.com/deseo +[@koppor]: https://github.com/koppor +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@simonebortolin]: https://github.com/simonebortolin +[@SConaway]: https://github.com/SConaway +[@Tom-Brouwer]: https://github.com/Tom-Brouwer + +## Pre-release v0.4.0.rc3 + +Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`. + +In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease. + +We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work! + +### Trying out pre-release `v0.4.0.rc3` + +Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc3" +``` + +By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +Broadly, this prerelease is feature-light! + +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] + +### Bugfixes and Experimental Features + +*Note*: experimental nav optimization may be unstable. Please give us feedback! + +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] + +[#965]: https://github.com/just-the-docs/just-the-docs/pull/965 +[#960]: https://github.com/just-the-docs/just-the-docs/pull/960 +[#962]: https://github.com/just-the-docs/just-the-docs/pull/962 +[#964]: https://github.com/just-the-docs/just-the-docs/pull/964 +[#967]: https://github.com/just-the-docs/just-the-docs/pull/967 +[#974]: https://github.com/just-the-docs/just-the-docs/pull/974 +[#980]: https://github.com/just-the-docs/just-the-docs/pull/980 +[#985]: https://github.com/just-the-docs/just-the-docs/pull/985 +[#986]: https://github.com/just-the-docs/just-the-docs/pull/986 +[#992]: https://github.com/just-the-docs/just-the-docs/pull/992 + +[@henryiii]: https://github.com/henryiii + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3 + +## Pre-release v0.4.0.rc2 + +{: .warning } +This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`! + +Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight: + +- significant improvement on build time of navigation panel by [@pdmosses] + - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds! +- improved accessibility features led by [@JPrevost] +- more docs! + +The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know! + +### Trying out pre-release `v0.4.0.rc2` + +Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc2" +``` + +By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] + +[#950]: https://github.com/just-the-docs/just-the-docs/pull/950 +[#944]: https://github.com/just-the-docs/just-the-docs/pull/944 +[#939]: https://github.com/just-the-docs/just-the-docs/pull/939 +[#949]: https://github.com/just-the-docs/just-the-docs/pull/949 +[#941]: https://github.com/just-the-docs/just-the-docs/pull/941 +[#956]: https://github.com/just-the-docs/just-the-docs/pull/956 + +[@alyssais]: https://github.com/alyssais + +### Documentation and Maintenance + +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Deleted: unused script directory by [@mattxwang] in [#937] + +[#935]: https://github.com/just-the-docs/just-the-docs/pull/935 +[#940]: https://github.com/just-the-docs/just-the-docs/pull/940 +[#951]: https://github.com/just-the-docs/just-the-docs/pull/951 +[#955]: https://github.com/just-the-docs/just-the-docs/pull/955 +[#937]: https://github.com/just-the-docs/just-the-docs/pull/937 + +### New Contributors + +* [@robinpokorny] made their first contribution in [#940] +* [@olgarithms] made their first contribution in [#951] +* [@manuelhenke] made their first contribution in [#941] +* [@JPrevost] made their first contribution in [#950] + +[@robinpokorny]: https://github.com/robinpokorny +[@olgarithms]: https://github.com/olgarithms +[@manuelhenke]: https://github.com/manuelhenke +[@JPrevost]: https://github.com/JPrevost + +## Pre-release v0.4.0.rc1 + +### We're back! + +Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include: + +- The new callouts component +- Allowing pages and collections to coexist on the navigation pane +- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements +- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting +- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color +- More documentation, especially on using custom includes +- Updating core dependencies to stable Ruby versions +- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way! + +We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc1` + +Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc1" +``` + +### Staying on `v0.3.3` + +If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to `v0.3.3` (i.e. by a `Gemfile.lock` or in `remote_theme`, then there's nothing you need to do. + +If you have not pinned your theme version, you should either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +{: .warning } +Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`. + +### Maintenance + +Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks! + +The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time! + +[@mattxwang]: https://github.com/mattxwang +[@pdmosses]: https://github.com/pdmosses +[@skullface]: https://github.com/skullface +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 + +### Roadmap + +In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs. + +We're also scoping out medium and long-term projects, and want to keep you in the loop. These include: + +- upgrading to Jekyll 4, and stopping support for Jekyll 3 +- versioned docs - issue [#728] +- improved accessibility - issues [#566], [#870] +- internationalization (i18n) - issue [#59] +- recursive/multi-level navigation - PR [#462] +- toggleable dark mode - issue [#234] + +as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome! + +[#728]: https://github.com/just-the-docs/just-the-docs/issues/728 +[#566]: https://github.com/just-the-docs/just-the-docs/issues/566 +[#870]: https://github.com/just-the-docs/just-the-docs/issues/870 +[#59]: https://github.com/just-the-docs/just-the-docs/issues/59 +[#462]: https://github.com/just-the-docs/just-the-docs/pull/462 +[#234]: https://github.com/just-the-docs/just-the-docs/issues/234 + +### Features + +* Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +* Added: custom favicon `_includes` by [@burner1024] in [#364] +* Added: set color for search input by [@pdmosses] in [#498] +* Added: search placeholder configuration by [@mattxwang] in [#613] +* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +* Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +* Added: mermaid.js support by [@nascosto] in [#857] +* Added: support for external navigation links by [@SPGoding] in [#876] +* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +* Fixed: nested task lists (#517) by [@pdmosses] in [#855] +* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +* Fixed: allow links to wrap by [@pdmosses] in [#905] +* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] + +[#578]: https://github.com/just-the-docs/just-the-docs/pull/578 +[#463]: https://github.com/just-the-docs/just-the-docs/pull/463 +[#448]: https://github.com/just-the-docs/just-the-docs/pull/448 +[#466]: https://github.com/just-the-docs/just-the-docs/pull/466 +[#477]: https://github.com/just-the-docs/just-the-docs/pull/477 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#496]: https://github.com/just-the-docs/just-the-docs/pull/496 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#494]: https://github.com/just-the-docs/just-the-docs/pull/494 +[#639]: https://github.com/just-the-docs/just-the-docs/pull/639 +[#544]: https://github.com/just-the-docs/just-the-docs/pull/544 +[#364]: https://github.com/just-the-docs/just-the-docs/pull/364 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#613]: https://github.com/just-the-docs/just-the-docs/pull/613 +[#726]: https://github.com/just-the-docs/just-the-docs/pull/726 +[#474]: https://github.com/just-the-docs/just-the-docs/pull/474 +[#829]: https://github.com/just-the-docs/just-the-docs/pull/829 +[#857]: https://github.com/just-the-docs/just-the-docs/pull/857 +[#876]: https://github.com/just-the-docs/just-the-docs/pull/876 +[#909]: https://github.com/just-the-docs/just-the-docs/pull/909 +[#519]: https://github.com/just-the-docs/just-the-docs/pull/519 +[#855]: https://github.com/just-the-docs/just-the-docs/pull/855 +[#686]: https://github.com/just-the-docs/just-the-docs/pull/686 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#846]: https://github.com/just-the-docs/just-the-docs/pull/846 +[#727]: https://github.com/just-the-docs/just-the-docs/pull/727 +[#889]: https://github.com/just-the-docs/just-the-docs/pull/889 +[#893]: https://github.com/just-the-docs/just-the-docs/pull/893 +[#905]: https://github.com/just-the-docs/just-the-docs/pull/905 +[#898]: https://github.com/just-the-docs/just-the-docs/pull/898 + +### Documentation + +* Added: docs on how to break an `ol` by [@pdmosses] in [#856] +* Added: docs for custom includes by [@nathanjessen] in [#806] +* Added: document caveat about variable dependencies by [@waldyrious] in [#555] +* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +* Fixed: spacing in toc example by [@henryiii] in [#835] +* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] + +[#856]: https://github.com/just-the-docs/just-the-docs/pull/856 +[#806]: https://github.com/just-the-docs/just-the-docs/pull/806 +[#555]: https://github.com/just-the-docs/just-the-docs/pull/555 +[#814]: https://github.com/just-the-docs/just-the-docs/pull/814 +[#778]: https://github.com/just-the-docs/just-the-docs/pull/778 +[#221]: https://github.com/just-the-docs/just-the-docs/pull/221 +[#782]: https://github.com/just-the-docs/just-the-docs/pull/782 +[#549]: https://github.com/just-the-docs/just-the-docs/pull/549 +[#554]: https://github.com/just-the-docs/just-the-docs/pull/554 +[#499]: https://github.com/just-the-docs/just-the-docs/pull/499 +[#473]: https://github.com/just-the-docs/just-the-docs/pull/473 +[#835]: https://github.com/just-the-docs/just-the-docs/pull/835 +[#891]: https://github.com/just-the-docs/just-the-docs/pull/891 +[#906]: https://github.com/just-the-docs/just-the-docs/pull/906 + +### Maintenance + +* Added: VScode devcontainer by [@max06] in [#783] +* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +* Updated: new repo path by [@pmarsceill] in [#775] +* Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +* Updated: README by [@pmarsceill] in [#777] +* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] + +[#783]: https://github.com/just-the-docs/just-the-docs/pull/783 +[#799]: https://github.com/just-the-docs/just-the-docs/pull/799 +[#797]: https://github.com/just-the-docs/just-the-docs/pull/797 +[#775]: https://github.com/just-the-docs/just-the-docs/pull/775 +[#776]: https://github.com/just-the-docs/just-the-docs/pull/776 +[#777]: https://github.com/just-the-docs/just-the-docs/pull/777 +[#790]: https://github.com/just-the-docs/just-the-docs/pull/790 +[#820]: https://github.com/just-the-docs/just-the-docs/pull/820 +[#821]: https://github.com/just-the-docs/just-the-docs/pull/821 + +### Dependencies + +* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627] +* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606] +* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641] +* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640] +* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511] +* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699] +* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766] +* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787] +* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809] +* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864] + +[#627]: https://github.com/just-the-docs/just-the-docs/pull/627 +[#606]: https://github.com/just-the-docs/just-the-docs/pull/606 +[#641]: https://github.com/just-the-docs/just-the-docs/pull/641 +[#640]: https://github.com/just-the-docs/just-the-docs/pull/640 +[#511]: https://github.com/just-the-docs/just-the-docs/pull/511 +[#699]: https://github.com/just-the-docs/just-the-docs/pull/699 +[#766]: https://github.com/just-the-docs/just-the-docs/pull/766 +[#787]: https://github.com/just-the-docs/just-the-docs/pull/787 +[#809]: https://github.com/just-the-docs/just-the-docs/pull/809 +[#864]: https://github.com/just-the-docs/just-the-docs/pull/864 + +### New Contributors + +* [@AdityaTiwari2102] made their first contribution in [#477] +* [@svrooij] made their first contribution in [#544] +* [@alexsegura] made their first contribution in [#519] +* [@burner1024] made their first contribution in [#364] +* [@JeffGuKang] made their first contribution in [#221] +* [@dougaitken] made their first contribution in [#782] +* [@max06] made their first contribution in [#783] +* [@sehilyi] made their first contribution in [#499] +* [@nathanjessen] made their first contribution in [#473] +* [@waldyrious] made their first contribution in [#549] +* [@MichelleBlanchette] made their first contribution in [#554] +* [@henryiii] made their first contribution in [#835] +* [@jmertic] made their first contribution in [#726] +* [@jacobhq] made their first contribution in [#846] +* [@UnclassedPenguin] made their first contribution in [#814] +* [@alyssais] made their first contribution in [#829] +* [@nascosto] made their first contribution in [#857] +* [@SPGoding] made their first contribution in [#876] +* [@iridazzle] made their first contribution in [#727] +* [@ivanskodje] made their first contribution in [#891] +* [@Eisverygoodletter] made their first contribution in [#893] + +[@AdityaTiwari2102]: https://github.com/AdityaTiwari2102 +[@svrooij]: https://github.com/svrooij +[@alexsegura]: https://github.com/alexsegura +[@burner1024]: https://github.com/burner1024 +[@JeffGuKang]: https://github.com/JeffGuKang +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 +[@sehilyi]: https://github.com/sehilyi +[@nathanjessen]: https://github.com/nathanjessen +[@waldyrious]: https://github.com/waldyrious +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@henryiii]: https://github.com/henryiii +[@jmertic]: https://github.com/jmertic +[@jacobhq]: https://github.com/jacobhq +[@UnclassedPenguin]: https://github.com/UnclassedPenguin +[@alyssais]: https://github.com/alyssais +[@nascosto]: https://github.com/nascosto +[@SPGoding]: https://github.com/SPGoding +[@iridazzle]: https://github.com/iridazzle +[@ivanskodje]: https://github.com/ivanskodje +[@Eisverygoodletter]: https://github.com/Eisverygoodletter + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1 + +[@pmarsceill]: https://github.com/pmarsceill + +## v0.3.3 + +### 🚀 Features + +- Add custom header and footer include files @CodeSandwich (#334) + +### 🐛 Bug Fixes + +- Limit the effect of `nav_exclude` to the main navigation @pdmosses (#443) +- Update normalize.scss @pdmosses (#444) +- Update code.scss @pdmosses (#445) +- Fix list alignment @pdmosses (#446) + +### 🧰 Maintenance + +- Bump stylelint-config-primer from 9.0.0 to 9.2.1 @dependabot-preview (#451) +- Bump stylelint from 13.6.1 to 13.7.2 @dependabot-preview (#440) +- Bump @primer/css from 15.1.0 to 15.2.0 @dependabot-preview (#436) +- Bump prettier from 2.1.1 to 2.1.2 @dependabot-preview (#429) + +## v0.3.2 + +### Changes + +- Safe page sorting @pdmosses (#411) +- v0.3.2 @pmarsceill (#388) + +### 🚀 Features + +- make font-sizes sass variables so they can be changed @pdebruic (#361) +- run the site locally inside docker container @fogfish (#398) +- Feature/doc collections @SgtSilvio (#379) +- Adjust dl layout @pdmosses (#401) + +### 🐛 Bug Fixes + +- Add site.gh_edit_source to "Edit this page on GitHub" link @mrfleap (#418) +- Inhibit text-transform for code in h4 @pdmosses (#404) +- Fix native font stack precedence issue on Windows systems. @hvianna (#331) +- Support for the linenos option on highlighted code @pdmosses (#375) +- Update anchor_headings.html @pdmosses (#399) +- Fix https @marksie1988 (#359) + +### 🧰 Maintenance + +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#427) +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#419) +- [Security] Bump lodash from 4.17.15 to 4.17.19 @dependabot-preview (#389) +- Bump @primer/css from 14.4.0 to 15.1.0 @dependabot-preview (#402) +- Bump lodash from 4.17.15 to 4.17.19 @dependabot (#384) +- Bump @primer/css from 14.4.0 to 15.0.0 @dependabot-preview (#371) + + +## v0.3.1 + +### Changes + +### 🐛 Bug Fixes + +- Improve accessibility by adding label to Anchor links. @mscoutermarsh (#376) + +### 🧰 Maintenance + +- Remove collapsible TOC on nav doc @pmarsceill (#368) +- Pdmosses collapsible toc @pmarsceill (#367) + + +## v0.3.0 + +### Changes + +- v0.2.9 @pmarsceill (#306) + +### 🚀 Features + +- Add print styles @pmarsceill (#362) +- Navigation improvements and search sections @SgtSilvio (#352) + +### 🐛 Bug Fixes + +- Remove constraint with jekyll 4.1.0 @PierrickMartos (#348) + +### 🧰 Maintenance + +- Bump version numbers @pmarsceill (#360) +- Bump stylelint from 13.3.3 to 13.6.1 @dependabot-preview (#343) +- Bump stylelint-config-prettier from 8.0.1 to 8.0.2 @dependabot-preview (#349) + + +## v0.2.9 + +### Bug fixes +- Horizontal Alignment #103 @pmarsceill +- Code snippet in headers do not inherit font size #140 @pmarsceill +- Fix duplicated title and description tags #294 @iefserge +- Update nav.html for handling nav_exclude #282 @blawqchain +- Fix duplicate entries in nav.html and default.html #239 @KasparEtter +- Don't show pages with no title (e.g. redirects in nav) https://github.com/pmarsceill/just-the-docs/pull/295/commits/672de29f2e332a9350af7237e4fb6693c848989e @SgtSilvio +- [SEARCH RAKE] Fix search generator #319 @RoiArthurB + +### Enhancements +- Improvement/custom themes #186 @SgtSilvio +- feat: adds "edit this page" and "page last modified" to footer #217 @malsf21 +- feat: adds option to open aux links in new tab #229 @malsf21 +- Default nav order #236 @pdmosses +- Enable IP anonymization in Google Analytics (GDPR) #250 @r-brown + +closes #240 #308 #266 #140 #103 + +## v0.2.8 + +### Bugfixes +- bugfix in search.rake #218 @tiaitsch85 + +### Dependency and security updates: + +- Update jekyll requirement from ~> 3.8.5 to >= 3.8.5, < 4.1.0 #197 @dependabot-preview +- Update rake requirement from ~> 12.3.1 to >= 12.3.1, < 13.1.0 #227 @dependabot-preview +- Bump stylelint-config-primer from 8.0.0 to 9.0.0 #247 @dependabot-preview +- Update bundler requirement from ~> 2.0.1 to ~> 2.1.4 #268 @dependabot-preview +- Bump @primer/css from 12.7.0 to 14.3.0 #296 @dependabot-preview + +### Operations + +- Update CI to test multiple versions of Jekyll +- Update CI to check the rake command that builds the search file + +fixes #291 #256 #293 #177 + +## v0.2.7 + +### Bugs fixed +- Anchor headings are now displayed on hover, not only on heading hover +- Deduplicated anchor heading svg +- If last page of `site.html_pages` was excluded from search, search json breaks +- Config variable should be `blanklines` not `blank_lines` for html compression +- `list-style-none` does not hide bullets on `ul` + +### Enhancements +- Summary for child pages appears in generated TOC +- Site logo configuration supported replacing title text with image +- Allow custom CSS overrides (new scss partial at the end of the cascade) separate from variable overrides. +- Configuration around search strings added to allow search for hyphenated words + +### Maintenance +- Update docs to suggest using index.md as section page filename +- Bump @primer/css from 12.6.0 to 12.7.0 +- Bump mixin-deep from 1.3.1 to 1.3.2 +- Bump stylelint-config-primer from 7.0.1 to 8.0.0 + +### PR included +- #98 by @stefanoborini Introduces the possibility for a summary in the table of contents +- #141 by @ghabs Fix trailing comma bug in search-data.json +- #153 by @jacobherrington Change button copy on theme preview +- #181 by @m3nu Recommend using index.md as parent page for sections +- #183 by @SgtSilvio Improve heading anchors +- #187 by @SgtSilvio Improvement/site logo +- #200 Bump mixin-deep from 1.3.1 to 1.3.2 +- #203 by @pdmosses Search config +- #205 by @pdmosses Fix blank_lines var to blanklines in config.yml +- #206 by @iamcarrico Allow for custom overrides by the user +- #208 Bump @primer/css from 12.6.0 to 12.7.0 +- #213 Bump mixin-deep from 1.3.1 to 1.3.2 +- #214 Bump stylelint-config-primer from 7.0.1 to 8.0.0 +- #215 Bump @primer/css from 12.6.0 to 12.7.0 + +## v0.2.6 + +### Bugs fixed +- Google Analytics tag has been updated #162 +- ~BaseURL has been modified #109~ Reverted -- seems the existing implementation worked +- Titles can now wrap fixes #106 + +### Enhancements +- Search now displays content preview #135 +- Custom footer content added #179 +- Now using GitHub Actions for CI #170 + +### Maintenance +- lunrjs upgraded #135 +- Nav generation is optimized #159 +- Stylelint upgrade #143 +- Stylelint config primer upgrade #149 +- Lodash upgrade #160 + +### PR included +~#109 by @daviddarnes - Fix baseurl link~ Reverted +#135 by @SgtSilvio - Upgrades lunr.js, improves search UI, adds heading anchors +#152 by @yavorg - Improves syntax highlighting for js readablity +#159 by @julienduchesne - Optimizes nav generation +#162 by @nergmada - Modifies the google analytics code to match the new tags used by GA + + +## v0.2.5 + +### Bugs fixed + +- Duplicate title tag when Jekyll SEO Plugin gem is used #125 #126 + +### Enhancements + +- Favicon support added #118 + +### Maintenance +- Bump stylelint-config-primer from 6.0.0 to 7.0.0 #123 +- Bump @primer/css from 12.2.3 to 12.3.1 #129 +- Add workflow to publish to GPR +- Fix workflow to publish to Ruby Gems + +## v0.2.4 + +### Bugs + +- #102 Remove unnecessary console.log() @JoeNyland +- #97 Import custom Sass variable overrides before default variables are defined @montchr and @ptvandi + +### Additions +- #117 Add links to docs for setting up GH pages locally @gnarea +- #95 Add SEO and 'lang' param for `_config` @gebeto + +## v0.2.3 + +### Enhancements +- Adds ability to use Google Analytics tracking by @pmarsceill + +### Bug fixes +- Fixes 404 error for "/assets/js//search-data.json" by @stephenedmondson +- Fixes #80 Single quotes in the string were unescaped and ruby attempted variable substitution of amp within it (which failed) by @novelistparty +- Fixes bug that would only show 2 or more search results (not one) by @ilivewithian +- Fixes a typo on the layout example by @woernfl +- Fixes #78 Page scroll position too far down on load by @pmarsceill +- Fixds ability to nest ul in ol without breaking style or counters + +### Dependency updates +- Bumps stylelint dependency from 9.9.0 to 9.10.1 + +## v0.2.2 + +- Bumps stylelint-config-primer to 3.0.1 #44 +- Bumps bundler req to 2.0.1 #61 +- Adds custom 404 page +- Excludes package-lock.json from jekyll build #47 +- Fixes keyboard scrolling / focus #48 +- Adds ARIA roles to navigation elements +- Adds support for optional page description metadata (if present in yaml front matter) +- Addresses some issues with search in #46 +- Option to hide TOC on parent pages if turned off in page's YAML front matter #30 +- Option to suppress an item from being indexed by search if present in page's YAML front matter #32 + +## v0.2.1 + +This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version. + +## v0.2.0 + +Adds: +- Dark mode via `color_scheme` parameter +- Ability to exclude a page from the main nav with `nav_exclude` parameter closes #21 +- Ability for create children of children pages (3 nav levels) closes #25 + +Changes: +- Permalink structure for tiered navigation has been updated +- Some colors have been updated for consistency / accessibility + +## v0.1.6 + +### Added + +- Support for task list styles #19 +- Configuration docs +- Configuration option to enable / disable search +- Normalize.scss dependency pulled into project #16 # + +### Fixed + +- Layout bug in navigation #17 + +## v0.1.5 + +Major changes: + +- Fixed bug where the rake task would fail when the assets/js directory didn't exist + +## v0.1.4 + +Major changes: +- Adds Rake as a runtime dependency +- Definition list styled +- Sidebar and support cleaned up for smaller screen support +- Updated some stale docs + +## v0.1.3 + +Major changes: +- Fix path problems, typos, and general clean-up for OSS. + +## v0.1.2 + +Fix paths when deployed to gh-pages + +## v0.1.1 + +Major updates: +- Adds search to mobile nav +- Pulls footer to bottom of the page on mobile (not hidden in nav) + +Minor updates: +- Cleans up h1 typography spacing diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 10fda59..a57ebc6 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,45 +2,131 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment include: +Examples of behavior that contributes to a positive environment for our +community include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at patrick.marsceill@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +patrick.marsceill@gmail.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/Dockerfile b/Dockerfile index 5f0ddae..a499513 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM ruby:2.6 +FROM ruby:2.7 ENV LC_ALL C.UTF-8 ENV LANG en_US.UTF-8 @@ -10,4 +10,3 @@ COPY Gemfile just-the-docs.gemspec ./ RUN gem install bundler && bundle install EXPOSE 4000 - diff --git a/Gemfile b/Gemfile index 113806a..76bd139 100644 --- a/Gemfile +++ b/Gemfile @@ -1,3 +1,8 @@ source "https://rubygems.org" gemspec -gem "just-the-docs" + +gem "jekyll-github-metadata", ">= 2.15" + +gem "jekyll-include-cache", group: :jekyll_plugins + +gem "html-proofer", "~> 5.0", :group => :development diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..e71b6d0 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,150 @@ +PATH + remote: . + specs: + just-the-docs (0.6.2) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + +GEM + remote: https://rubygems.org/ + specs: + Ascii85 (1.1.0) + addressable (2.8.4) + public_suffix (>= 2.0.2, < 6.0) + afm (0.2.2) + async (2.6.3) + console (~> 1.10) + fiber-annotation + io-event (~> 1.1) + timers (~> 4.1) + colorator (1.1.0) + concurrent-ruby (1.2.2) + console (1.23.2) + fiber-annotation + fiber-local + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + faraday (2.7.10) + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.15.5) + fiber-annotation (0.2.0) + fiber-local (1.0.0) + forwardable-extended (2.6.0) + google-protobuf (3.23.4-arm64-darwin) + google-protobuf (3.23.4-x86_64-linux) + hashery (2.1.2) + html-proofer (5.0.8) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + io-event (1.2.3) + jekyll (4.3.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-github-metadata (2.16.0) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + nokogiri (1.15.4-arm64-darwin) + racc (~> 1.4) + nokogiri (1.15.4-x86_64-linux) + racc (~> 1.4) + octokit (6.1.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + pdf-reader (2.11.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.0.3) + racc (1.7.1) + rainbow (3.1.1) + rake (13.0.6) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.6) + rouge (4.1.2) + ruby-rc4 (0.1.5) + ruby2_keywords (0.0.5) + safe_yaml (1.0.5) + sass-embedded (1.64.1-arm64-darwin) + google-protobuf (~> 3.23) + sass-embedded (1.64.1-x86_64-linux-gnu) + google-protobuf (~> 3.23) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + timers (4.3.5) + ttfunk (1.7.0) + typhoeus (1.4.0) + ethon (>= 0.9.0) + unicode-display_width (2.4.2) + webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.6.11) + +PLATFORMS + arm64-darwin + x86_64-linux + +DEPENDENCIES + bundler (>= 2.3.5) + html-proofer (~> 5.0) + jekyll-github-metadata (>= 2.15) + jekyll-include-cache + just-the-docs! + +BUNDLED WITH + 2.4.13 diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..eca953d --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,493 @@ +--- +title: Migration and Upgrading +layout: default +--- + +# Migrating and Upgrading + +Summary +: A site that uses `just-the-docs` (as a theme or as a remote theme) automatically + switches to a new release, unless it is pinned to a previous version. + + This migration guide draws attention to: + + - changes that might break your site, + - features added in the latest release, and + - features that have become deprecated (and are likely to be removed in a future release). + +This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`. + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +{::options toc_levels="2..4" /} + +{: .warning } +> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your +> website is built using the current `main` branch of the theme, which may include +> changes made after the latest release; see the [CHANGELOG]. +> +> If your configuration states `theme: just_the_docs` and your `Gemfile` specifies +> `gem "just-the-docs"`, your website is always built using the latest release. + +{: .note } +> If you have cloned/forked and customised the theme repo, +> and pull the changes of a new release to your clone, +> you may need to resolve merge conflicts. + +[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %} + +## v0.5.x - v0.6.0 + +### POTENTIALLY-BREAKING CHANGES in v0.6.0 + +There are some *very minor* potentially-breaking changes for users in version `v0.6.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern: + +1. the addition of new `_includes/favicon.html`, `_includes/head_nav.html`, and `_includes/css/activation.scss.liquid` + - **explicit migration only necessary if users have defined a custom file with the same name** +2. removing `id="main-content-wrap` from wrapper `div` elements in default layouts + - **explicit migration only necessary if users have written code that depends on `#main-content-wrap`** +3. loading the new `$color-scheme` variable (from the light scheme by default) + - **explicit migration only necessary if users have overridden the base light theme** +4. caching the favicon for the entire site + - **explicit migration only necessary if users have different favicons for different pages** + +#### New Includes + +Version `v0.6.0` introduces three new `_includes` files: + +- `_includes/favicon.html`, which now contains logic previously in `_includes/head.html`: loading `favicon.ico` if no favicon is specified +- `_includes/head_nav.html`, which generates CSS used for the new efficient navigation implementation +- `_includes/css/activation.scss.liquid`, which is used by `head_nav` for navigation implementation + +If users have existing `_includes` files with this name, they should be renamed (and imported with their new name) prior to upgrading to `0.6.0`. No other change is necessary. + +#### Removed `#main-content-wrap` + +In `_layouts/default.html` and `_layouts/minimal.html`, the `id="main-content-wrap"` has been removed from the wrapper div (in part due to a bug with multiple `id`s on one element). Internally, our theme *does not use* these `id`s; for most users, this does not require any action. + +However, code that relies on this `id` must be changed. Each of the related elements still has the unique class `.main-content-wrap`, and can be selected with this class. For example, in CSS: + +```css +/* OLD */ +#main-content-wrap { /* ... */ } + +/* NEW */ +.main-content-wrap { /* ... */ } +``` + +Or in JS: + +```js +// OLD +document.getElementById("main-content-wrap"); + +// NEW +document.getElementsByClassName("main-content-wrap")[0]; +``` + +#### New `$color-scheme` variable + +The theme now properly sets the `color-scheme` property. To do so, the new `$color-scheme` SCSS variable has been created. The variable has been added to the default `light` scheme, which is *always* loaded by Just the Docs. + +Migration is only needed if: + +- the packaged `light` scheme has been *overridden* (this is *not* the same as using a custom scheme) +- or, the scheme logic to always load `light` has been changed + +(neither of these behaviours are recommended by Just the Docs) + +In either of these cases, users should add a `$color-scheme` SCSS variable to their active scheme with the appropriate value (see: [MDN docs on `color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)). + +```scss +$color-scheme: light !default; +``` + +#### Cached favicon + +Version `v0.6.0` adds a new `_include` that caches the favicon for the entire site. This significantly improves page build times for large sites. + +However, some users may load different favicons for each page (and/or dynamically change the first favicon load). In this case, they should override the logic in `_includes/favicon.html` by **replacing** it with an empty file (this is *different* from deleting it). No further migration is necessary. + +## v0.4.x - v0.5.0 + +### POTENTIALLY-BREAKING CHANGES in v0.5.0 + +There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context: + +1. `setup.scss` was introduced in `v0.4.0` +2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code +3. in `v0.4.2`, we adjusted the order to import `setup.scss` *after* color scheme SCSS code +4. in `v0.5.0`, we have reverted the previous change: `setup.scss` is now again imported *before* color scheme SCSS code + +This does not affect most users. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes. + +Explicit migration steps are only needed if: + +1. a custom `setup.scss` has been defined, +2. **and** the `setup.scss` depends on variables or functions defined in color scheme SCSS code; this change was only possible on `v0.4.2` + +For those users, we suggest moving those variables and functions to each relevant color scheme. +## v0.3.3 … v0.4.x + +### REPOSITORY CHANGES + +#### Just the Docs + +The theme repo is now at . +The name of its default branch is now `main`. + +The theme docs website is now published at . We've also retroactively published the theme docs website for version `v0.3.3` at . + +GitHub provides access to previous versions of the theme repo. +You can browse [previous versions of the theme docs website] on the [Internet Archive]. + +[previous versions of the theme docs website]: https://web.archive.org/web/20220000000000*/https://just-the-docs.github.io/just-the-docs +[Internet Archive]: https://web.archive.org/ + +The [README] page on the theme repo repeats much of the information from the [home page], +formatted for browsing on GitHub. +It also explains how to install the theme as a Ruby Gem, without creating a new site. + +[README]: https://github.com/just-the-docs/just-the-docs/blob/main/README.md +[home page]: https://just-the-docs.com + +#### Deploy previews + +When a PR builds successfully, Netlify provides a preview of how the theme docs website will look if the PR is merged. +You can find links to the preview near the bottom of the Conversation tab of the PR. + +#### Just the Docs Template + +The template at +creates a repo with the minimal source files for a Just the Docs website. +After configuring the relevant parameters, you can build and serve the website +both locally and on GitHub Pages – using either Jekyll 3 or Jekyll 4! + +#### Just the Docs Tests + +The tests website at +consists mainly of regression tests for bug fixes and new features. + +The test source files at +illustrate the use of many Markdown and Jekyll features, +including some that are not included in the theme docs. + +For example, see how to add support for rendering TeX/LaTeX [math formulas] with KaTeX and MathJax. + +[math formulas]: https://just-the-docs.github.io/just-the-docs-tests/components/math/index/ + +### POTENTIALLY-BREAKING CHANGES in v0.4.0 + +If switching to a new release of the theme breaks your website, +check that you don't have any files in the `_includes`, `_layouts`, and `_sass` +directories with the same names as files provided by the theme. + +If your repo has a customised copy of `_layouts/default.html` from a previous release, +try removing it, or replace it by a fresh copy of the theme file. + +{: .warning } +The following changes made in v0.4.0 *might* break or adversely affect your website +when you next rebuild it, unless you have pinned it! + +#### New includes and SCSS + +Version 0.4.0 introduces many new `_includes` files. If you already have an existing include with the same name as a new addition, you will need to migrate or update that include. The new files are (relative to the `_includes` folder): + +- `mermaid_config.js` +- `nav_footer_custom` +- `search_placeholder_custom` +- `toc_heading_custom` +- the entire `components/` folder: + - `aux_nav`, `breadcrumbs`, `children_nav`, `footer`, `header`, `mermaid`, `search_footer`, `search_header`, `sidebar` +- the entire `icons/` folder + - `code_copy`, `document`, `expand`, `external_link`, `icons`, `link`, `menu`, `search` +- the entire `lunr/` folder + - `custom-data.json`, `custom-index.js` + +We have removed some code in `_sass/vendor` and added a new file at `_sass/custom/setup.scss`. + +#### favicons + +The file `_includes/favicon.html` is now ignored by the theme. +If you're using it, your website's favicon is no longer displayed by browsers. + +To fix: Move the content of `_includes/favicon.html` to `_includes/head_custom.html`. + +#### Custom callout colors + +The file `_sass/custom/custom.scss` is now imported last: _after_ the configuration of callouts. +If you've defined custom color variables for callouts in `_sass/custom/custom.scss` +(and used them when configuring your callouts in `_config.yml`) +you will not be able to rebuild your website. + +To fix: Move custom color variables for callouts in `_sass/custom/custom.scss` to `_sass/custom/variables.scss`. + +#### Pages and collections + +Links to ordinary pages now appear in the navigation on sites that use collections. +You might want the navigation of your site to consist entirely of collections. + +To fix: Add the front matter `nav_exclude: true` to pages that the navigation should not display. + +#### Relative URLs + +All generated URLs are now relative. +This is a bug fix, and unlikely to break any site. + +Relative links to pages within a website support deployment to different servers. + +#### Navigation order + +The order in which the navigation panel lists pages has been simplified. +All pages with `nav_order` values now come before all pages that are ordered by `title`. + +If your website has a group of *sibling* pages where some siblings have `nav_order` +string values, and others are ordered by numerical `title` values, +the former now come before the latter. + +To fix: Add numerical `nav_order` values to the pages with numerical `title` values. + +### DEPRECATIONS + +{: .warning } +The following features are deprecated, and to be removed in a future release. + +#### Jekyll 3 + +You can still use Jekyll 3 (3.8.5 or later) to build websites using v0.4.0 of the theme. +However, future releases of the theme may require the use of Jekyll 4. + +You can already use Jekyll 4 to build your website *locally*. +It should look exactly the same as when built with Jekyll 3.[^Jekyll4] + +[^Jekyll4]: + Jekyll 4 depends on more recent versions of other gems than Jekyll 3, + and the differences between those versions may affect the files of your built site. + +To use Jekyll 4 when building your website *on GitHub Pages*, you need to run GitHub Actions. +The simplest way of setting that up in a new repo is to create the repo using the Just the Docs template. +To start running Jekyll 4 to build an existing repo on GitHub Pages, +you can create a new repo with the template, then copy its `.github/workflows` directory, +and update your repo settings to use Actions. + +#### Footer content configuration + +Currently, if your configuration sets `footer_content` to some text, +the theme displays that text at the bottom of the main section of each page. + +The file `_includes/footer_custom.html` provides a more general way of customizing +not only the text but also the markup for the page footer area. + +You can replicate the current display of `TEXT` in the footer using the following markup: + +```html +

TEXT

+``` + +### THEME WEBSITE CHANGES + +The website now uses *callouts*[^callouts] to draw attention to important information. + +[^callouts]: + The theme website configuration defines the callout titles and colors used there. + Websites that use the theme have to configure their own callout titles and colors. + +The theme uses [semantic versioning]. +A normal version number takes the form X.Y.Z, +where X is the major version, Y is the minor version, and Z is the patch version. +The theme uses version X.Y.Z.rcN for pre-release N of version X.Y.Z. +When referring to version numbers on GitHub, we usually prefix them by 'v'. + +[semantic versioning]: https://semver.org + +Major version zero (0.Y.Z) is for initial development, where anything *may* change at any time. +In practice, we increment the patch version Z for bug fixes and backwards compatible changes; +we increment the minor version Y for changes that could break websites using the theme +without pinning it to a specific version. + +The label `NEW` in the theme website indicates a feature that has been changed or added +since the release of the previous *minor* version. +For example, after the release of v0.4.Z, the theme website should label `NEW` all features that +we have changed or added since v0.3.0 – not just since v0.3.3. +When we release v0.5.0, we will remove all those labels, and add labels on features since v0.4.0. + +The theme docs website is not itself versioned. +It changes incrementally, independently of theme releases. + +#### Home page + +The theme home page now focuses on the simplest ways of using the theme. +It also notes the different behaviour of `theme` and `remote_theme` in connection +with interim versions of the theme, such as pre-releases. + +#### CHANGELOG + +The CHANGELOG page lists the changes made in all previous releases and pre-releases of new versions of the theme gem. + +It also lists changes made to the `main` branch of the theme since the latest release or pre-release. + +For changes since v0.3.3, the log usually references the merged PR that made the change and its author. + +### NON-BREAKING CHANGES (OUTLINE ONLY) + +#### Accessibility + +- Skip to main content: the first keyboard-navigatable item is now a link to skip over the sidebar and header to the main content of the page. PR: [#949]. +- Aria-labels: improved `aria-label`s have been added to various site elements. PRs: [#950], ... +- Other general improvements: gradual changes have improved tab focusability, contrast, and semantic elements. More work still to come. PRs: [#498], [#846] + +#### Configuration + +- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more. +- Multiple Google Analytics tags are now supported. PR: [#1029] + +#### Customization + +- all user-facing text is now customizable; previously, several elements (ex search placeholder) were hardwired into the theme. Now, users can blend custom includes and layouts to internationalize their sites. +- we've clarified the role of `custom.scss` to be imported last; to allow users to define custom or override variables, we've added a new file `setup.scss`. PR: [#1135] + +#### Custom Includes + +We've added several custom `_includes` to provide users with more customization options for different site elements. We've also added a section to [Configuration]({% link docs/customization.md %}#override-includes) to outline these. + +All of these are opt-in by default; however, **these may be breaking if you have existing `_includes` with the same name**. + +Each item is listed with the relevant file and PR. + +- TOC heading: `toc_heading_custom.html`, PR: [#980] +- Navigation panel footer: `nav_footer_custom.html`, PR: [#474] +- Search placeholder: `search_placeholder_custom.html`, PR: [#613] +- Modular site components: `components/` and `icons/`, PR: [#1058] +- Custom search indices: `lunr/`, PR: [#1068] + +In a future (version 1) release, we may rename the custom include files. + +#### Modular Components + +We've broken up the default layout (`_layouts/default.html`) into multiple reusable components. This should have no impact on most users; however, it should make it easier to implement custom layouts. + +For more, see [Custom layouts and includes]({% link docs/customization.md %}#custom-layouts-and-includes). PR: [#1058]. + +#### Navigation + +- Collections: nav panel shows links to ordinary pages before collections +- Collection folding; part of "Combination". PR: [#578] +- Scrolling to show link to selected page. PR: [#639] +- External nav links are now supported. PR: [#876] +- Child nav order: sort navigation pages with `child_nav_order`. PR: [#726] +- Order when mixing different ways of specifying nav order + +#### Search + +In addition to customizing the search placeholder, we've also added the ability to provide custom content to the search index. for more, see [Custom content for search index]({% link docs/search.md %}#custom-content-for-search-index). PR: [#1068]. + +#### Styling + +- Code copying: code blocks now allow users to easily copy their contents. PR: [#945] +- Blockquote: shows vertical bar on left. PR: [#965] +- Links wrap. PR: [#905] +- Callouts: a new component similar to alerts or banners. See [UI Components - Callouts]({% link docs/ui-components/callouts.md %}). PR: [#466] + +---- + +[#856]: https://github.com/just-the-docs/just-the-docs/pull/856 +[#806]: https://github.com/just-the-docs/just-the-docs/pull/806 +[#555]: https://github.com/just-the-docs/just-the-docs/pull/555 +[#814]: https://github.com/just-the-docs/just-the-docs/pull/814 +[#778]: https://github.com/just-the-docs/just-the-docs/pull/778 +[#221]: https://github.com/just-the-docs/just-the-docs/pull/221 +[#782]: https://github.com/just-the-docs/just-the-docs/pull/782 +[#549]: https://github.com/just-the-docs/just-the-docs/pull/549 +[#554]: https://github.com/just-the-docs/just-the-docs/pull/554 +[#499]: https://github.com/just-the-docs/just-the-docs/pull/499 +[#473]: https://github.com/just-the-docs/just-the-docs/pull/473 +[#835]: https://github.com/just-the-docs/just-the-docs/pull/835 +[#891]: https://github.com/just-the-docs/just-the-docs/pull/891 +[#906]: https://github.com/just-the-docs/just-the-docs/pull/906 + +[#578]: https://github.com/just-the-docs/just-the-docs/pull/578 +[#463]: https://github.com/just-the-docs/just-the-docs/pull/463 +[#448]: https://github.com/just-the-docs/just-the-docs/pull/448 +[#466]: https://github.com/just-the-docs/just-the-docs/pull/466 +[#477]: https://github.com/just-the-docs/just-the-docs/pull/477 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#496]: https://github.com/just-the-docs/just-the-docs/pull/496 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#494]: https://github.com/just-the-docs/just-the-docs/pull/494 +[#639]: https://github.com/just-the-docs/just-the-docs/pull/639 +[#544]: https://github.com/just-the-docs/just-the-docs/pull/544 +[#364]: https://github.com/just-the-docs/just-the-docs/pull/364 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#613]: https://github.com/just-the-docs/just-the-docs/pull/613 +[#726]: https://github.com/just-the-docs/just-the-docs/pull/726 +[#474]: https://github.com/just-the-docs/just-the-docs/pull/474 +[#829]: https://github.com/just-the-docs/just-the-docs/pull/829 +[#857]: https://github.com/just-the-docs/just-the-docs/pull/857 +[#876]: https://github.com/just-the-docs/just-the-docs/pull/876 +[#909]: https://github.com/just-the-docs/just-the-docs/pull/909 +[#519]: https://github.com/just-the-docs/just-the-docs/pull/519 +[#855]: https://github.com/just-the-docs/just-the-docs/pull/855 +[#686]: https://github.com/just-the-docs/just-the-docs/pull/686 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#846]: https://github.com/just-the-docs/just-the-docs/pull/846 +[#727]: https://github.com/just-the-docs/just-the-docs/pull/727 +[#889]: https://github.com/just-the-docs/just-the-docs/pull/889 +[#893]: https://github.com/just-the-docs/just-the-docs/pull/893 +[#905]: https://github.com/just-the-docs/just-the-docs/pull/905 +[#898]: https://github.com/just-the-docs/just-the-docs/pull/898 + +[#950]: https://github.com/just-the-docs/just-the-docs/pull/950 +[#944]: https://github.com/just-the-docs/just-the-docs/pull/944 +[#939]: https://github.com/just-the-docs/just-the-docs/pull/939 +[#949]: https://github.com/just-the-docs/just-the-docs/pull/949 +[#941]: https://github.com/just-the-docs/just-the-docs/pull/941 +[#956]: https://github.com/just-the-docs/just-the-docs/pull/956 +[#935]: https://github.com/just-the-docs/just-the-docs/pull/935 +[#940]: https://github.com/just-the-docs/just-the-docs/pull/940 +[#951]: https://github.com/just-the-docs/just-the-docs/pull/951 +[#955]: https://github.com/just-the-docs/just-the-docs/pull/955 +[#937]: https://github.com/just-the-docs/just-the-docs/pull/937 + +[#965]: https://github.com/just-the-docs/just-the-docs/pull/965 +[#960]: https://github.com/just-the-docs/just-the-docs/pull/960 +[#962]: https://github.com/just-the-docs/just-the-docs/pull/962 +[#964]: https://github.com/just-the-docs/just-the-docs/pull/964 +[#967]: https://github.com/just-the-docs/just-the-docs/pull/967 +[#974]: https://github.com/just-the-docs/just-the-docs/pull/974 +[#980]: https://github.com/just-the-docs/just-the-docs/pull/980 +[#985]: https://github.com/just-the-docs/just-the-docs/pull/985 +[#986]: https://github.com/just-the-docs/just-the-docs/pull/986 +[#992]: https://github.com/just-the-docs/just-the-docs/pull/992 + +[#945]: https://github.com/just-the-docs/just-the-docs/pull/945 +[#999]: https://github.com/just-the-docs/just-the-docs/pull/999 +[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000 +[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001 +[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010 +[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015 +[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018 +[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019 +[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021 +[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027 +[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029 +[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040 +[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061 +[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065 +[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071 +[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074 +[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076 +[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077 +[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090 +[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091 +[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092 +[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095 + +[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068 +[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135 diff --git a/README.md b/README.md index d5e4d3f..d8b76b8 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,110 @@ -# Documentation site for *microbetag* +

+ Gem version CI Build status Netlify Status +

+

+

+

Just the Docs

+

A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.
Easily hosted on GitHub Pages with few dependencies.

+

See it in action!

+


+

-This site is using the [just-the-docs](https://just-the-docs.github.io/just-the-docs/) theme. +

A video walkthrough of various Just the Docs features

+https://user-images.githubusercontent.com/85418632/211225192-7e5d1116-2f4f-4305-bb9b-437fe47df071.mp4 + +## Installation + +### Use the template + +The [Just the Docs Template] provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "[use the template]"! + +Note: To use the theme, you do ***not*** need to clone or fork the [Just the Docs repo]! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs. + +You can easily set the site created by the template to be published on [GitHub Pages] – the [template README] file explains how to do that, along with other details. + +If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^2] And you will be able to deploy your local build to a different platform than GitHub Pages. + +More specifically, the created site: + +- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem +- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages + +Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. + +### Use RubyGems + +Alternatively, you can install the theme as a Ruby Gem, without creating a new site. + +Add this line to your Jekyll site's `Gemfile`: + +```ruby +gem "just-the-docs" +``` + +And add this line to your Jekyll site's `_config.yml`: + +```yaml +theme: just-the-docs +``` + +And then execute: + + $ bundle + +Or install it yourself as: + + $ gem install just-the-docs + +Alternatively, you can run it inside Docker while developing your site + + $ docker-compose up + +## Usage + +[View the documentation][Just the Docs] for usage information. ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/pmarsceill/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. +Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. + +### Submitting code changes: +- Submit an [Issue](https://github.com/just-the-docs/just-the-docs/issues) that motivates the changes, using the appropriate template +- Discuss the proposed changes with other users and the maintainers +- Open a [Pull Request](https://github.com/just-the-docs/just-the-docs/pulls) +- Ensure all CI tests pass +- Provide instructions to check the effect of the changes +- Await code review +### Design and development principles of this theme: + +1. As few dependencies as possible +2. No build script needed +3. First class mobile experience +4. Make the content shine + +## Development + +To set up your environment to develop this theme: fork this repo, the run `bundle install` from the root directory. + +A modern [devcontainer configuration](https://code.visualstudio.com/docs/remote/containers) for VSCode is included. + +Your theme is set up just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal. + +When this theme is released, only the files in `_layouts`, `_includes`, and `_sass` tracked with Git will be included in the gem. ## License The theme is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). + +[^2]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). + +[Jekyll]: https://jekyllrb.com +[Just the Docs Template]: https://just-the-docs.github.io/just-the-docs-template/ +[Just the Docs]: https://just-the-docs.com +[Just the Docs repo]: https://github.com/just-the-docs/just-the-docs +[GitHub Pages]: https://pages.github.com/ +[Template README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md +[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ +[use the template]: https://github.com/just-the-docs/just-the-docs-template/generate diff --git a/_config.yml b/_config.yml index 47acc04..4ee6056 100644 --- a/_config.yml +++ b/_config.yml @@ -1,61 +1,59 @@ - -title: "microbetag" -description: A place with the background and the *how to* of the *microbetag* tool - currently in production - -# remote_theme: pmarsceill/just-the-docs - -# Permalinks are the output path for your pages, posts, or collections. -# They allow you to structure the directories of your source code different from the directories in your output. -# For more check: https://jekyllrb.com/docs/permalinks/ - - - - +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole site, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing these this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'jekyll serve'. If you change this file, please restart the server process. + +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. +title: Just the Docs +description: A Jekyll theme for documentation baseurl: "" # the subpath of your site, e.g. /blog url: "https://just-the-docs.com" # the base hostname & protocol for your site, e.g. http://example.com repository: just-the-docs/just-the-docs # for github-metadata - - - permalink: pretty -# What it says! ;) -exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", -"script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile", "docs/tests/"] - -# exclude: -# # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml: -# - .sass-cache/ -# - .jekyll-cache/ -# - gemfiles/ -# - Gemfile -# - Gemfile.lock -# - node_modules/ -# - vendor/bundle/ -# - vendor/cache/ -# - vendor/gems/ -# - vendor/ruby/ -# # specific to the theme website: -# - bin/ -# - lib/ -# - "*.gemspec" -# - "*.gem" -# - LICENSE.txt -# - package.json -# - package-lock.json -# - Rakefile -# - README.md -# - CODE_OF_CONDUCT.md -# - docker-compose.yml -# - Dockerfile -# # theme test code -# - fixtures/ - -# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define -color_scheme: nil - -# Enable search and set the params for searching +exclude: + # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml: + - .sass-cache/ + - .jekyll-cache/ + - gemfiles/ + - Gemfile + - Gemfile.lock + - node_modules/ + - vendor/bundle/ + - vendor/cache/ + - vendor/gems/ + - vendor/ruby/ + # specific to the theme website: + - bin/ + - lib/ + - "*.gemspec" + - "*.gem" + - LICENSE.txt + - package.json + - package-lock.json + - Rakefile + - README.md + - CODE_OF_CONDUCT.md + - docker-compose.yml + - Dockerfile + # theme test code + - fixtures/ + +# Set a path/url to a logo that will be displayed instead of the title +#logo: "/assets/images/just-the-docs.png" + +# Enable or disable the site search +# Supports true (default) or false search_enabled: true search: # Split pages into sections that can be searched individually @@ -81,7 +79,8 @@ search: # Supports true or false (default) button: false - +# For copy button on code +enable_copy_code_button: true # By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in mermaid: @@ -97,16 +96,48 @@ mermaid: # path: "/assets/js/mermaid.min.js" # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (MIT license. This site is powered by Netlify." + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub" +gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from +# gh_edit_source: docs # the source that your files originate from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define color_scheme: nil diff --git a/_sass/support/_functions.scss b/_sass/support/_functions.scss deleted file mode 100644 index 6772f4e..0000000 --- a/_sass/support/_functions.scss +++ /dev/null @@ -1,9 +0,0 @@ -@function rem($size, $unit: "") { - $remSize: $size / $root-font-size; - - @if ($unit == false) { - @return #{$remSize}; - } @else { - @return #{$remSize}rem; - } -} diff --git a/assets/images/just-the-docs.png b/assets/images/just-the-docs.png deleted file mode 100644 index 81c33065f2794814cbe1a53791d8bc4bfbb91cb1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20992 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 z 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 diff --git a/assets/images/search.svg b/assets/images/search.svg deleted file mode 100644 index 421ca4d..0000000 --- a/assets/images/search.svg +++ /dev/null @@ -1 +0,0 @@ -Search diff --git a/components/aux_nav.html b/components/aux_nav.html deleted file mode 100644 index f327da6..0000000 --- a/components/aux_nav.html +++ /dev/null @@ -1,15 +0,0 @@ - diff --git a/components/breadcrumbs.html b/components/breadcrumbs.html deleted file mode 100644 index 82ad6bd..0000000 --- a/components/breadcrumbs.html +++ /dev/null @@ -1,43 +0,0 @@ -{%- comment -%} - Include as: {%- include components/breadcrumbs.html -%} - Depends on: page, site. - Results in: HTML for the breadcrumbs component. - Overwrites: - pages_list, parent_page, grandparent_page. -{%- endcomment -%} - -{%- if page.url != "/" and page.parent -%} - - {%- assign pages_list = site[page.collection] - | default: site.html_pages - | where_exp: "item", "item.title != nil" - | where_exp: "item", "item.has_children != nil" -%} - - {%- if page.grand_parent -%} - {%- assign parent_page = pages_list - | where: "title", page.parent - | where: "parent", page.grand_parent - | first -%} - {%- assign grandparent_page = pages_list - | where: "title", page.grand_parent - | first -%} - {%- else -%} - {%- assign parent_page = pages_list - | where: "title", page.parent - | where_exp: "item", "item.parent == nil" - | first -%} - {%- endif -%} - - - -{%- endif -%} diff --git a/components/children_nav.html b/components/children_nav.html deleted file mode 100644 index ce2482a..0000000 --- a/components/children_nav.html +++ /dev/null @@ -1,33 +0,0 @@ -{%- comment -%} - Include as: {%- include components/children_nav.html -%} - Depends on: page, site. - Results in: HTML for the children-navigation component. - Includes: - sorted_pages.html - toc_heading_custom.html - Overwrites: - child_pages. -{%- endcomment -%} - -{%- if page.has_children == true and page.has_toc != false -%} - {%- assign child_pages = site[page.collection] - | default: site.html_pages - | where: "parent", page.title - | where: "grand_parent", page.parent -%} - - {%- include sorted_pages.html pages = child_pages -%} - - {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%} - {%- assign sorted_pages = sorted_pages | reverse -%} - {%- endif -%} -{%- endif -%} - -
-{% include toc_heading_custom.html %} -
    -{% for child in sorted_pages %} -
  • - {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} -
    • -{% endfor %} -
diff --git a/components/footer.html b/components/footer.html deleted file mode 100644 index 01b2c23..0000000 --- a/components/footer.html +++ /dev/null @@ -1,34 +0,0 @@ -{% capture footer_custom %} - {%- include footer_custom.html -%} -{% endcapture %} -{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %} -
-
- {% if site.back_to_top %} -

{{ site.back_to_top_text }}

- {% endif %} - - {{ footer_custom }} - - {% if site.last_edit_timestamp or site.gh_edit_link %} -
- {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %} -

- Page last modified: {{ page.last_modified_date | date: site.last_edit_time_format }}. -

- {% endif %} - {% if - site.gh_edit_link and - site.gh_edit_link_text and - site.gh_edit_repository and - site.gh_edit_branch and - site.gh_edit_view_mode - %} -

- {{ site.gh_edit_link_text }} -

- {% endif %} -
- {% endif %} -
-{% endif %} diff --git a/components/header.html b/components/header.html deleted file mode 100644 index f9c3386..0000000 --- a/components/header.html +++ /dev/null @@ -1,11 +0,0 @@ -
- {% if site.search_enabled != false %} - {% include components/search_header.html %} - {% else %} -
- {% endif %} - {% include header_custom.html %} - {% if site.aux_links %} - {% include components/aux_nav.html %} - {% endif %} -
diff --git a/components/mermaid.html b/components/mermaid.html deleted file mode 100644 index a99a563..0000000 --- a/components/mermaid.html +++ /dev/null @@ -1,45 +0,0 @@ -{% comment %} -The complexity of this file comes from a breaking change in Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work earlier?). - -So, we check whether the user's Mermaid version is >= 10; if not, we fall back to the previous init syntax. - -If a user is using a custom mermaid file and doesn't specify a version, we default to the < v10 behaviour. Users who use version v10 or above should specify this in the version key. -{% endcomment %} - -{% if site.mermaid.version %} - {% assign mermaid_major_version = site.mermaid.version | split: "." | first | plus: 0 %} -{% else %} - {% assign mermaid_major_version = 9 %} -{% endif %} - -{% if mermaid_major_version > 9 %} - - - -{% else %} - -{% if site.mermaid.path %} - -{% else %} - -{% endif %} - - - -{% endif %} diff --git a/components/search_footer.html b/components/search_footer.html deleted file mode 100644 index d448fdb..0000000 --- a/components/search_footer.html +++ /dev/null @@ -1,7 +0,0 @@ -{% if site.search.button %} - -{% endif %} - -
diff --git a/components/search_header.html b/components/search_header.html deleted file mode 100644 index 3562124..0000000 --- a/components/search_header.html +++ /dev/null @@ -1,9 +0,0 @@ -{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %} - - diff --git a/components/sidebar.html b/components/sidebar.html deleted file mode 100644 index 7863340..0000000 --- a/components/sidebar.html +++ /dev/null @@ -1,83 +0,0 @@ -{%- comment -%} - Include as: {%- include components/sidebar.html -%} - Depends on: page(?), site. - Results in: HTML for the side bar. - Includes: - title.html, nav.html, nav_footer_custom.html - Overwrites: - pages_top_size, collections_size, collection_entry, - collection_key, collection_value, collection, nav_footer_custom. - Should not be cached, because nav_footer_custom.html might depend on page. -{%- endcomment -%} - -
- - - - {% capture nav_footer_custom %} - {%- include nav_footer_custom.html -%} - {% endcapture %} - {% if nav_footer_custom != "" %} - {{ nav_footer_custom }} - {% else %} -
- This site uses Just the Docs, a documentation theme for Jekyll. -
- {% endif %} -
diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 7227544..0000000 --- a/docs/api.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: default -title: API documentation -nav_order: 4 ---- - -# API documentation -{: .no_toc } - - -{: .fs-6 .fw-300 } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - - - -microbetagDB API provides programmatic access to the data. - -The base address to the API is https://msysbio.gbiomed.kuleuven.be/. - -Below you may find the syntax to retrieve the various data and/or annotations included. - - -## Get genome ids for a NCBI Taxonoy Id - -To check whether a species is present on microbetag, one may find its corresponding NCBI Taxonomy Id and search for -related genomes present on the microbetag DB. - -For example, assuming we are interested in the *Blautia hansenii* DSM 20583 strain, we find from NCBI Taxonomy that its corresponding id is [537007](https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=537007). - -Using the `ncbiTaxId-to-genomeId` route we may get the related genomes on microbetag DB: - -```bash -curl -X GET https://msysbio.gbiomed.kuleuven.be/ncbiTaxId-to-genomeId/537007 -``` -that returns a list of genomes used in microbetag annotations: - -```bash -{ - "853": [ - "GCA_002222595", - ] -} -``` - -Similarly, in Python: - -```python ->>> import requests ->>> url = "https://msysbio.gbiomed.kuleuven.be/ncbiTaxId-to-genomeId/853" ->>> r = requests.get(url) ->>> r.status_code -200 ->>> r.json() -{"537007": ["GCA_002222595.2"]} -``` - - -## Get phenotypic traits of a species - -One may get the corresponding phenotypic traits of a genome present on the microbetag DB -using the `/phen-traits/` route and the GTDB genome id. - -```bash -curl -X GET https://msysbio.gbiomed.kuleuven.be/phen-traits/GCF_002222595.2 -``` - -this would return (we show only a part of the outcome) - -```bash -{ - "NOB": "NO", - "NOBScore": "0.8078", - "T3SS": "NO", - "T3SSScore": "0.8391", - "T6SS": "NO", - "T6SSScore": "0.7836", - "aSaccharolytic": "NO", - "aSaccharolyticScore": "0.8672", - ... -} -``` - - - - - -dd - - -These callout names are *not* pre-defined by the theme: you need to define your own names. - - - - - - - -## Common errors - -There are three possible types of client errors on API calls: - -- 400 Bad requests. - -- 404 Not found. - - - diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..0660d5d --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,330 @@ +--- +layout: default +title: Configuration +nav_order: 2 +--- + +# Configuration +{: .no_toc } + +Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file. +{: .fs-6 .fw-300 } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example. + +## Site logo + +```yaml +# Set a path/url to a logo that will be displayed instead of the title +logo: "/assets/images/just-the-docs.png" +``` + +## Site favicon + +```yaml +# Set a path/url to a favicon that will be displayed by the browser +favicon_ico: "/assets/images/favicon.ico" +``` + +If the path to your favicon is `/favicon.ico`, you can leave `favicon_ico` unset. + +## Search + +```yaml +# Enable or disable the site search +# Supports true (default) or false +search_enabled: true + +search: + # Split pages into sections that can be searched individually + # Supports 1 - 6, default: 2 + heading_level: 2 + # Maximum amount of previews per search result + # Default: 3 + previews: 3 + # Maximum amount of words to display before a matched word in the preview + # Default: 5 + preview_words_before: 5 + # Maximum amount of words to display after a matched word in the preview + # Default: 10 + preview_words_after: 10 + # Set the search token separator + # Default: /[\s\-/]+/ + # Example: enable support for hyphenated search words + tokenizer_separator: /[\s/]+/ + # Display the relative url in search results + # Supports true (default) or false + rel_url: true + # Enable or disable the search button that appears in the bottom right corner of every page + # Supports true or false (default) + button: false +``` + +## Mermaid Diagrams +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`: + +```yaml +mermaid: + # Version of mermaid library + # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ + version: "9.1.3" +``` + +Provide a `path` instead of a `version` key to load the mermaid library from a local file. + +See [the Code documentation]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information. + +## Aux links + +```yaml +# Aux links for the upper right navigation +aux_links: + "Just the Docs on GitHub": + - "//github.com/just-the-docs/just-the-docs" + +# Makes Aux links open in a new tab. Default is false +aux_links_new_tab: false +``` + +## Heading anchor links + +```yaml +# Heading anchor links appear on hover over h1-h6 tags in page content +# allowing users to deep link to a particular heading on a page. +# +# Supports true (default) or false +heading_anchors: true +``` + +## External navigation links +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +External links can be added to the navigation through the `nav_external_links` option. +See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details. + +## Footer content + +```yaml +# Footer content +# appears at the bottom of every page's main content +# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust +markup / liquid-based content. +footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license." + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from +# gh_edit_source: docs # the source that your files originate from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately +``` + +_note: `footer_content` is deprecated, but still supported. For a better experience we have moved this into an include called `_includes/footer_custom.html` which will allow for robust markup / liquid-based content._ + +- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format +- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime) +- `gh_edit_repository` is the URL of the project's GitHub repository +- `gh_edit_branch` is the branch that the docs site is served from; defaults to `main` +- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/)) +- `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode + +## Color scheme + +```yaml +# Color scheme supports "light" (default) and "dark" +color_scheme: dark +``` + + + + + +See [Customization]({% link docs/customization.md %}) for more information. + +## Callouts +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.: + +```yaml +callouts: + warning: + title: Warning + color: red +``` + +This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this: + +```markdown +{: .warning } +A paragraph... +``` + +[^dark]: + If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. + +The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file: + +```scss +$pink-000: #f77ef1; +$pink-100: #f967f1; +$pink-200: #e94ee1; +$pink-300: #dd2cd4; +``` + +You can override the default `opacity` of the background for a particular callout, e.g.: + +```yaml +callouts: + custom: + color: pink + opacity: 0.3 +``` + +You can change the default opacity (`0.2`) for all callouts, e.g.: + +```yaml +callouts_opacity: 0.3 +``` + +You can also adjust the overall level of callouts. +The value of `callouts_level` is either `quiet` or `loud`; +`loud` increases the saturation and lightness of the backgrounds. +The default level is `quiet` when using the `light` or custom color schemes, +and `loud` when using the `dark color scheme.` + +See [Callouts]({% link docs/ui-components/callouts.md %}) for more information. + +## Google Analytics + +{: .warning } +> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4. + +Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported. + +```yaml +# Google Analytics Tracking (optional) +# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5") +ga_tracking: UA-2709176-10 +ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default) +``` + +### Multiple IDs +{: .d-inline-block .no_toc } + +New (v0.4.0) +{: .label .label-green } + +This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while. + +```yaml +ga_tracking: "UA-1234567-89,G-1AB234CDE5" +``` + +## Document collections + +By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/). +You can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together. + +{: .warning } +> Collection folders always start with an underscore (`_`), e.g. `_tests`. You won't see your collections if you omit the prefix. + +For example, put all your test files in the `_tests` folder and create the `tests` collection: + +```yaml +# Define Jekyll collections +collections: + # Define a collection named "tests", its documents reside in the "_tests" directory + tests: + permalink: "/:collection/:path/" + output: true + +just_the_docs: + # Define which collections are used in just-the-docs + collections: + # Reference the "tests" collection + tests: + # Give the collection a name + name: Tests + # Exclude the collection from the navigation + # Supports true or false (default) + # nav_exclude: true + # Fold the collection in the navigation + # Supports true or false (default) + # nav_fold: true # note: this option is new in v0.4 + # Exclude the collection from the search + # Supports true or false (default) + # search_exclude: true +``` + +The navigation for all your normal pages (if any) is displayed before those in collections. + +New (v0.4.0){: .label .label-green } +Including `nav_fold: true` in a collection configuration *folds* that collection: +an expander symbol appears next to the collection name, +and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled] + +[^js-disabled]: New (v0.6.0){: .label .label-green } + When JavaScript is disabled in the browser, all folded collections are automatically expanded, + since clicking expander symbols has no effect. + (In previous releases, navigation into folded collections required JavaScript to be enabled.) + +You can reference multiple collections. +This creates categories in the navigation with the configured names. + +```yaml +collections: + tests: + permalink: "/:collection/:path/" + output: true + tutorials: + permalink: "/:collection/:path/" + output: true + +just_the_docs: + collections: + tests: + name: Tests + tutorials: + name: Tutorials +``` + +When *all* your pages are in a single collection, its name is not displayed. + +The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page. diff --git a/docs/customization.md b/docs/customization.md new file mode 100644 index 0000000..7c57b77 --- /dev/null +++ b/docs/customization.md @@ -0,0 +1,406 @@ +--- +layout: default +title: Customization +nav_order: 6 +--- + +# Customization +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +## Color schemes + +Just the Docs supports two color schemes: light (default), and dark. + +To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file: + +#### Example +{: .no_toc } + +```yaml +# Color scheme supports "light" (default) and "dark" +color_scheme: dark +``` + + + + + +### deprecated: `legacy_light` +{: .d-inline-block .no_toc } + +New (v0.4.2) +{: .label .label-green } + + +In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme. + +## Custom schemes + +### Define a custom scheme + +You can add custom schemes. +If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name) +where you override theme variables to change colors, fonts, spacing, etc. + +{: .note } +Since the default color scheme is `light`, your custom scheme is implicitly based on the variable settings used by the `light` scheme. + +If you want your custom scheme to be based on the `dark` scheme, you need to start your file with the following line: + +```scss +@import "./color_schemes/dark"; +``` + +You can define custom schemes based on other custom schemes in the same way. + +Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file. + +For example, to change the link color from the purple default to blue, include the following inside your scheme file: + +#### Example +{: .no_toc } + +```scss +$link-color: $blue-000; +``` + +Keep in mind that changing a variable will not automatically change the value of other variables that depend on it. +For example, the default link color (`$link-color`) is set to `$purple-000`. However, redefining `$purple-000` in a custom color scheme will not automatically change `$link-color` to match it. +Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from `_variables.scss` — in this case, rewriting `$link-color: $purple-000;`. + +_Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail. +Please use scheme files. + +### Use a custom scheme + +To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file: + +```yaml +color_scheme: foo +``` + +### Switchable custom scheme + +If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name) +with the following content: + +{% raw %} + --- + --- + {% include css/just-the-docs.scss.liquid color_scheme="foo" %} +{% endraw %} + +This allows you to switch the scheme via the following javascript. + +```js +jtd.setTheme("foo") +``` + +## Override and define new variables +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +To define new SCSS variables or functions, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section) or overriding color scheme variables (in this case, you should create a new color scheme). + +This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example, + +```scss +// _sass/custom/setup.scss +$pink-000: #f77ef1; +$pink-100: #f967f1; +$pink-200: #e94ee1; +$pink-300: #dd2cd4; +``` + +In particular: this file is imported *after* the theme's variables and functions are defined, but *before* any CSS classes are emitted. + +## Override and completely custom styles + +For styles that aren't defined as SCSS variables, you may want to modify specific CSS classes. +Additionally, you may want to add completely custom CSS specific to your content. +To do this, put your styles in the file `_sass/custom/custom.scss`. +This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied. + +For example, if you'd like to add your own styles for printing a page, you could add the following styles. + +#### Example +{: .no_toc } + +```scss +// Print-only styles. +@media print { + .side-bar, + .page-header { + display: none; + } + .main-content { + max-width: auto; + margin: 1em; + } +} +``` + +## Override includes + +You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides. + +To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults). + +Just the Docs provides the following custom includes files: + +### Custom TOC Heading +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +`_includes/toc_heading_custom.html` + +If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content. + +#### Example +{: .no_toc } + +To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add: +```html +

Contents

+``` + +The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} . + +### Custom Footer + +`_includes/footer_custom.html` + +This content appears at the bottom of every page's main content. More info for this include can be found in the [Configuration - Footer content]({% link docs/configuration.md %}#footer-content). + +### Custom Head + +`_includes/head_custom.html` + +Any HTML added to this file will be inserted before the closing `` tag. This might include additional ``, ``, or ` + +Text can be **bold**, _italic_, or ~~strikethrough~~. + +[Link to another page]({{site.baseurl}}/). + +There should be whitespace between paragraphs. + +There should be whitespace between paragraphs. We recommend including a README, or a file with information about your project. + +# [](#header-1)Header 1 + +This is a normal paragraph following a header. GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. + +## [](#header-2)Header 2 + +> This is a blockquote following a header. +> +> When something is important enough, you do it even if the odds are not in your favor. + +### [](#header-3)Header 3 + +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l) + return true; +} +``` + +```ruby +# Ruby code with syntax highlighting +GitHubPages::Dependencies.gems.each do |gem, version| + s.add_dependency(gem, "= #{version}") +end +``` + +#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed` + +* This is an unordered list following a header. +* This is an unordered list following a header. +* This is an unordered list following a header. + +##### [](#header-5)Header 5 + +1. This is an ordered list following a header. +2. This is an ordered list following a header. +3. This is an ordered list following a header. + +###### [](#header-6)Header 6 + +[This is a very long link which wraps and therefore doesn't overflow +even when it comes at the beginning](.) of the line. + +- [This is a very long link which wraps and therefore doesn't overflow the line + when used first in an item ](.) in a list. + +| head1 | head two | three | +|:-------------|:------------------|:------| +| ok | good swedish fish | nice | +| out of stock | good and plenty | nice | +| ok | good `oreos` | hmm | +| ok | good `zoute` drop | yumm | + +### There's a horizontal rule below this. + +* * * + +### Here is an unordered list: + +* Item foo +* Item bar +* Item baz +* Item zip + +### And an ordered list: + +1. Item one +1. Item two +1. Item three +1. Item four + +### And an ordered list, continued: + +1. Item one +1. Item two + +Some text + +{:style="counter-reset:none"} +1. Item three +1. Item four + +### And an ordered list starting from 42: + +{:style="counter-reset:step-counter 41"} +1. Item 42 +1. Item 43 +1. Item 44 + +### And a nested list: + +- level 1 item + - level 2 item + - level 2 item + - level 3 item + - level 3 item +- level 1 item + - level 2 item + - level 2 item + - level 2 item +- level 1 item + - level 2 item + - level 2 item +- level 1 item + +### Nesting an ol in ul in an ol + +- level 1 item (ul) + 1. level 2 item (ol) + 1. level 2 item (ol) + - level 3 item (ul) + - level 3 item (ul) +- level 1 item (ul) + 1. level 2 item (ol) + 1. level 2 item (ol) + - level 3 item (ul) + - level 3 item (ul) + 1. level 4 item (ol) + 1. level 4 item (ol) + - level 3 item (ul) + - level 3 item (ul) +- level 1 item (ul) + +### And a task list + +- [ ] Hello, this is a TODO item +- [ ] Hello, this is another TODO item +- [x] Goodbye, this item is done + +### Nesting task lists + +- [ ] level 1 item (task) + - [ ] level 2 item (task) + - [ ] level 2 item (task) +- [ ] level 1 item (task) +- [ ] level 1 item (task) + +### Nesting a ul in a task list + +- [ ] level 1 item (task) + - level 2 item (ul) + - level 2 item (ul) +- [ ] level 1 item (task) +- [ ] level 1 item (task) + +### Nesting a task list in a ul + +- level 1 item (ul) + - [ ] level 2 item (task) + - [ ] level 2 item (task) +- level 1 item (ul) +- level 1 item (ul) + +### Small image + +![](../../assets/images/small-image.jpg) + +### Large image + +![](../../assets/images/large-image.jpg) + +"[Wroclaw University Library digitizing rare archival texts](https://www.flickr.com/photos/97810305@N08/9401451269)" by [j_cadmus](https://www.flickr.com/photos/97810305@N08) is marked with [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/?ref=openverse). + +### Labels + +I'm a label +{: .label } + +blue +{: .label .label-blue } +green +{: .label .label-green } +purple +{: .label .label-purple } +yellow +{: .label .label-yellow } +red +{: .label .label-red } + +**bold** +{: .label } +*italic* +{: .label } +***bold + italic*** +{: .label } + +### Definition lists can be used with HTML syntax. + +
+
Name
+
Godzilla
+
Born
+
1952
+
Birthplace
+
Japan
+
Color
+
Green
+
+ +#### Multiple description terms and values + +Term +: Brief description of Term + +Longer Term +: Longer description of Term, + possibly more than one line + +Term +: First description of Term, + possibly more than one line + +: Second description of Term, + possibly more than one line + +Term1 +Term2 +: Single description of Term1 and Term2, + possibly more than one line + +Term1 +Term2 +: First description of Term1 and Term2, + possibly more than one line + +: Second description of Term1 and Term2, + possibly more than one line + +### More code + +```python{% raw %} +def dump_args(func): + "This decorator dumps out the arguments passed to a function before calling it" + argnames = func.func_code.co_varnames[:func.func_code.co_argcount] + fname = func.func_name + def echo_func(*args,**kwargs): + print fname, ":", ', '.join( + '%s=%r' % entry + for entry in zip(argnames,args) + kwargs.items()) + return func(*args, **kwargs) + return echo_func + +@dump_args +def f1(a,b,c): + print a + b + c + +f1(1, 2, 3) + +def precondition(precondition, use_conditions=DEFAULT_ON): + return conditions(precondition, None, use_conditions) + +def postcondition(postcondition, use_conditions=DEFAULT_ON): + return conditions(None, postcondition, use_conditions) + +class conditions(object): + __slots__ = ('__precondition', '__postcondition') + + def __init__(self, pre, post, use_conditions=DEFAULT_ON): + if not use_conditions: + pre, post = None, None + + self.__precondition = pre + self.__postcondition = post +{% endraw %}``` + +``` +Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this. +``` + +### Mermaid Diagrams + +The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`. + +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` + +### Collapsed Section + +The following uses the [`
`](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) tag to create a collapsed section. + +
+Shopping list (click me!) + +This is content inside a `
` dropdown. + +- [ ] Apples +- [ ] Oranges +- [ ] Milk + +
diff --git a/docs/layout/layout.md b/docs/layout/layout.md new file mode 100644 index 0000000..6bf3de9 --- /dev/null +++ b/docs/layout/layout.md @@ -0,0 +1,40 @@ +--- +title: Layout +layout: default +nav_order: 4.5 +has_children: true +--- + +# Layout + +You specify the layout for a page in its [front matter]. Just the Docs has a `default` layout with a sidebar, used for almost all pages in the theme docs, and a `minimal` layout that omits the sidebar. +{: .fs-6 .fw-300 } + +## The layout concept + +See the [Jekyll docs page about layouts] for an explanation of the general idea of layouts and how to specify them. + +You can use [Jekyll's front matter defaults] to specify the same layout for many pages. + +## The `default` layout + +This page uses the default layout. + +It is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button. + +Each child (and grandchild) page of a top-level page has so-called *breadcrumbs*: links to its parent (and grandparent) pages. It shows the breadcrumbs above the main content of the page. + +Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content. + +## The `minimal` layout + +A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar -- and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents. + +## Other layouts + +Just the Docs has further layouts: `about`, `home`, `page`, and `post`. Currently, they are all based on the `default` layout. See the [Jekyll docs about inheritance] for how to customize them. + +[front matter]: https://jekyllrb.com/docs/front-matter/ "Jekyll docs about front matter" +[Jekyll docs page about layouts]: https://jekyllrb.com/docs/layouts/ "Jekyll docs about layouts" +[Jekyll's front matter defaults]: https://jekyllrb.com/docs/configuration/front-matter-defaults/ "Jekyll docs about front matter defaults" +[Jekyll docs about inheritance]: https://jekyllrb.com/docs/layouts/#inheritance "Jekyll docs about inheritance" diff --git a/docs/layout/minimal/default-child.md b/docs/layout/minimal/default-child.md new file mode 100644 index 0000000..3035580 --- /dev/null +++ b/docs/layout/minimal/default-child.md @@ -0,0 +1,8 @@ +--- +title: Default layout child page +layout: default +parent: A minimal layout page +grand_parent: Layout +--- + +This is a child page that uses the same minimal layout as its parent page. diff --git a/docs/layout/minimal/minimal-child.md b/docs/layout/minimal/minimal-child.md new file mode 100644 index 0000000..26bcff7 --- /dev/null +++ b/docs/layout/minimal/minimal-child.md @@ -0,0 +1,8 @@ +--- +title: Minimal layout child page +layout: minimal +parent: A minimal layout page +grand_parent: Layout +--- + +This is a child page that uses the same minimal layout as its parent page. diff --git a/docs/layout/minimal/minimal.md b/docs/layout/minimal/minimal.md new file mode 100644 index 0000000..1821d67 --- /dev/null +++ b/docs/layout/minimal/minimal.md @@ -0,0 +1,12 @@ +--- +title: A minimal layout page +layout: minimal +parent: Layout +has_children: true +--- + +# A minimal layout page + +This page illustrates the built-in layout `minimal`. + +One of its child pages also uses the minimal layout; the other child pages uses the default layout. diff --git a/docs/minimal-test.md b/docs/minimal-test.md new file mode 100644 index 0000000..aa754d3 --- /dev/null +++ b/docs/minimal-test.md @@ -0,0 +1,9 @@ +--- +layout: minimal +title: Minimal layout test +nav_exclude: true +--- + +[Return to main website]({{site.baseurl}}/). + +This page demonstrates the packaged `minimal` layout, which does not render the sidebar or header. It can be used for standalone pages. It is also an example of using the new modular site components to define custom layouts; see ["Custom layouts and includes" in the customization docs]({{site.baseurl}}/docs/customization/#custom-layouts-and-includes) for more information. diff --git a/docs/modules.md b/docs/modules.md deleted file mode 100644 index a06dcfd..0000000 --- a/docs/modules.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -layout: default -title: Configuration -nav_order: 2 ---- - -# Configuration -{: .no_toc } - -Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file. -{: .fs-6 .fw-300 } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example. - - -## Callouts -{: .d-inline-block } - -New (v0.4.0) -{: .label .label-green } - -To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.: - -```yaml -callouts: - warning: - title: Warning - color: red -``` - -This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this: - -```markdown -{: .warning } -A paragraph... -``` - -[^dark]: - If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. - -The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file: - -```scss -$pink-000: #f77ef1; -$pink-100: #f967f1; -$pink-200: #e94ee1; -$pink-300: #dd2cd4; -``` - -You can override the default `opacity` of the background for a particular callout, e.g.: - -```yaml -callouts: - custom: - color: pink - opacity: 0.3 -``` - -You can change the default opacity (`0.2`) for all callouts, e.g.: - -```yaml -callouts_opacity: 0.3 -``` - -You can also adjust the overall level of callouts. -The value of `callouts_level` is either `quiet` or `loud`; -`loud` increases the saturation and lightness of the backgrounds. -The default level is `quiet` when using the `light` or custom color schemes, -and `loud` when using the `dark color scheme.` - -See fas for more information. - -## Google Analytics - -{: .warning } -> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4. - -Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported. - -```yaml -# Google Analytics Tracking (optional) -# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5") -ga_tracking: UA-2709176-10 -ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default) -``` - - - - - - - - - - diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md new file mode 100644 index 0000000..23af9b0 --- /dev/null +++ b/docs/navigation-structure.md @@ -0,0 +1,316 @@ +--- +layout: default +title: Navigation Structure +nav_order: 5 +--- + +# Navigation Structure +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +--- + +## Main navigation + +The main navigation for your Just the Docs site is on the left side of the page on large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren). + +By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)). + +--- + +## Ordering pages + +To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter. + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: Customization +nav_order: 4 +--- + +``` + +The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents. + +The parameter values can be numbers (integers, floats) and/or strings. Pages with numerical `nav_order` parameters always come before those with string `nav_order` parameters. When you omit `nav_order` parameters, they default to the titles of the pages. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages. All pages with explicit `nav_order` parameters +come before all pages ordered by their `title` values. + +By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example. + +--- + +## Excluding pages + +For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page. + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: 404 +nav_exclude: true +--- + +``` + +The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation. + +Pages with no `title` are automatically excluded from the main navigation. + +--- + +## Pages with children + +Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the `./docs` directory and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like: + +``` ++-- .. +|-- (Jekyll files) +| +|-- docs +| |-- ui-components +| | |-- index.md (parent page) +| | |-- buttons.md +| | |-- code.md +| | |-- labels.md +| | |-- tables.md +| | +-- typography.md +| | +| |-- utilities +| | |-- index.md (parent page) +| | |-- color.md +| | |-- layout.md +| | |-- responsive-modifiers.md +| | +-- typography.md +| | +| |-- (other md files, pages with no children) +| +-- .. +| +|-- (Jekyll files) ++-- .. +``` + +On the parent pages, add this YAML front matter parameter: + +- `has_children: true` (tells us that this is a parent page) + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: UI Components +nav_order: 2 +has_children: true +--- + +``` + +Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav. + +### Child pages + +{: .text-gamma } + +On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section). + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: Buttons +parent: UI Components +nav_order: 2 +--- + +``` + +The Buttons page appears as a child of UI Components and appears second in the UI Components section. + +### Ordering child pages +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +You can optionally add the following to the YAML front matter to reverse the default sort order of child pages: + +- `child_nav_order: reversed` + +#### Example +{: .no_toc } +```yaml +--- +layout: default +title: Reversed Child Pages +child_nav_order: reversed +--- +``` + +### Auto-generating Table of Contents + +By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter. + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: UI Components +nav_order: 2 +has_children: true +has_toc: false +--- + +``` + +### Children with children + +{: .text-gamma } + +Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages. + +1. Add the `has_children` attribute to the child +1. Add the `parent` and `grand_parent` attribute to the grandchild + +#### Example +{: .no_toc } + +```yaml +--- +layout: default +title: Buttons +parent: UI Components +nav_order: 2 +has_children: true +--- + +``` + +```yaml +--- +layout: default +title: Buttons Child Page +parent: Buttons +grand_parent: UI Components +nav_order: 1 +--- + +``` + +This would create the following navigation structure: + +``` ++-- .. +| +|-- UI Components +| |-- .. +| | +| |-- Buttons +| | |-- Button Child Page +| | +| |-- .. +| ++-- .. +``` + +{: .note } +Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages. + +--- + +## Auxiliary Links + +To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file. + +#### Example +{: .no_toc } + +```yaml +# Aux links for the upper right navigation +aux_links: + "Just the Docs on GitHub": + - "//github.com/just-the-docs/just-the-docs" +``` + +--- + +## External Navigation Links +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file. +External links will appear in the navigation after the links to ordinary pages, but before any collections. + +#### Example +{: .no_toc } + +```yaml +# External navigation links +nav_external_links: + - title: Just the Docs on GitHub + url: https://github.com/just-the-docs/just-the-docs + hide_icon: false # set to true to hide the external link icon - defaults to false +``` + +The external links are decorated by an icon, which distinguishes them from internal links. +You can suppress the icon by setting `hide_icon: true`. + +--- + +## In-page navigation with Table of Contents + +To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `
    ` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class. + +#### Example +{: .no_toc } + +```markdown +# Navigation Structure +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} +``` + +This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`. + +### Collapsible Table of Contents + +The Table of Contents can be made collapsible using the `
    ` and `` elements, as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional. + +```markdown +
    + + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
    +``` + +The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page). diff --git a/docs/search.md b/docs/search.md new file mode 100644 index 0000000..09a1ec5 --- /dev/null +++ b/docs/search.md @@ -0,0 +1,167 @@ +--- +layout: default +title: Search +nav_order: 7 +--- + +# Search +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. +All search results are shown in an auto-complete style interface (there is no search results page). +By default, all generated HTML pages are indexed using the following data points: + +- Page title +- Page content +- Page URL + +## Enable search in configuration + +In your site's `_config.yml`, enable search: + +```yaml +# Enable or disable the site search +# Supports true (default) or false +search_enabled: true +``` + +### Search granularity + +Pages are split into sections that can be searched individually. +The sections are defined by the headings on the page. +Each section is displayed in a separate search result. + +```yaml +# Split pages into sections that can be searched individually +# Supports 1 - 6, default: 2 +search.heading_level: 2 +``` + +### Search previews + +A search result can contain previews that show where the search words are found in the specific section. + +```yaml +# Maximum amount of previews per search result +# Default: 3 +search.previews: 3 + +# Maximum amount of words to display before a matched word in the preview +# Default: 5 +search.preview_words_before: 5 + +# Maximum amount of words to display after a matched word in the preview +# Default: 10 +search.preview_words_after: 10 +``` + +### Search tokenizer + +The default is for hyphens to separate tokens in search terms: +`gem-based` is equivalent to `gem based`, matching either word. +To allow search for hyphenated words: + +```yaml +# Set the search token separator +# Default: /[\s\-/]+/ +# Example: enable support for hyphenated search words +search.tokenizer_separator: /[\s/]+/ +``` + +### Display URL in search results + +```yaml +# Display the relative url in search results +# Supports true (default) or false +search.rel_url: false +``` + +### Display search button + +The search button displays in the bottom right corner of the screen and triggers the search input when clicked. + +```yaml +# Enable or disable the search button that appears in the bottom right corner of every page +# Supports true or false (default) +search.button: true +``` + +## Hiding pages from search + +Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page. +To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter: + +#### Example + +{: .no_toc } + +```yaml +--- +layout: default +title: Page not found +nav_exclude: true +search_exclude: true +--- + +``` + +## Generate search index when used as a gem + +If you use Just the Docs as a remote theme, you do not need the following steps. + +If you use the theme as a gem, you must initialize the search by running this `rake` command that comes with `just-the-docs`: + +```bash +$ bundle exec just-the-docs rake search:init +``` + +This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index. +Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json). + +## Custom content for search index +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +Advanced +{: .label .label-yellow } + +By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed. + +{: .warning } +> Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge. + +1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json` is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem). +2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`. +3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code. + +#### Example + +This example adds front matter `usage` and `examples` fields to the search index. + +`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields. Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences). `jsonify` will probably work for most scenarios. + +{% raw %} +```liquid +{%- capture newline %} +{% endcapture -%} +"myusage": {{ include.page.usage | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }}, +"myexamples": {{ include.page.examples | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }}, +``` +{% endraw %} + +`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`. All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`. Finally, append your custom fields on to the already existing `docs[i].content`. + +```javascript +const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples]; +docs[i].content = content_to_merge.join(' '); +``` diff --git a/docs/tests/index.md b/docs/tests/index.md deleted file mode 100644 index 27fc4d7..0000000 --- a/docs/tests/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: default -title: Tests -has_children: true -nav_order: 100 ---- - -# Tests - - The main documentation pages of this theme illustrate the use of many of its features, which to some extent tests their implementation. The pages linked below provide further test cases for particular features, and may be useful for regression testing when developing new features. - -The default configuration does not include the test pages. To include them, *commment-out* the following line in `_config.yml`: - -```yaml -, "docs/tests/" -``` -so that it is: -```yaml -# , "docs/tests/" -``` - -(Apparently Jekyll's `include` does *not* override `exclude` for the same folder...) diff --git a/docs/tests/navigation/disambiguation/a.md b/docs/tests/navigation/disambiguation/a.md deleted file mode 100644 index b680fe6..0000000 --- a/docs/tests/navigation/disambiguation/a.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: Tests for disambiguation A -has_children: true ---- - -# A - -A top-level page - -```yaml -title: Tests for disambiguation A -has_children: true -``` diff --git a/docs/tests/navigation/disambiguation/b.md b/docs/tests/navigation/disambiguation/b.md deleted file mode 100644 index 23403e8..0000000 --- a/docs/tests/navigation/disambiguation/b.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: Tests for disambiguation B -has_children: true ---- - -# B - -A top-level page - -```yaml -title: Tests for disambiguation B -has_children: true -``` diff --git a/docs/tests/navigation/disambiguation/ca.md b/docs/tests/navigation/disambiguation/ca.md deleted file mode 100644 index e645044..0000000 --- a/docs/tests/navigation/disambiguation/ca.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Tests for disambiguation C -parent: Tests for disambiguation A -has_children: true ---- - -# C - -A child of page A, and parent of page D - -```yaml -title: Tests for disambiguation C -parent: Tests for disambiguation A -has_children: true -``` diff --git a/docs/tests/navigation/disambiguation/cb.md b/docs/tests/navigation/disambiguation/cb.md deleted file mode 100644 index d15844f..0000000 --- a/docs/tests/navigation/disambiguation/cb.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Tests for disambiguation C -parent: Tests for disambiguation B -has_children: true ---- - -# C - -A child of page B, and parent of page D - -```yaml -title: Tests for disambiguation C -parent: Tests for disambiguation B -has_children: true -``` diff --git a/docs/tests/navigation/disambiguation/dca.md b/docs/tests/navigation/disambiguation/dca.md deleted file mode 100644 index c01dbbb..0000000 --- a/docs/tests/navigation/disambiguation/dca.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Tests for disambiguation D -parent: Tests for disambiguation C -grand_parent: Tests for disambiguation A ---- - -# D - -A grandchild of page A - -```yaml -title: Tests for disambiguation D -parent: Tests for disambiguation C -grand_parent: Tests for disambiguation A -``` diff --git a/docs/tests/navigation/disambiguation/dcb.md b/docs/tests/navigation/disambiguation/dcb.md deleted file mode 100644 index f80d83d..0000000 --- a/docs/tests/navigation/disambiguation/dcb.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Tests for disambiguation D -parent: Tests for disambiguation C -grand_parent: Tests for disambiguation B ---- - -# D - -A grandchild of page B - -```yaml -title: Tests for disambiguation D -parent: Tests for disambiguation C -grand_parent: Tests for disambiguation B -``` diff --git a/docs/tests/navigation/disambiguation/index.md b/docs/tests/navigation/disambiguation/index.md deleted file mode 100644 index 3d8f799..0000000 --- a/docs/tests/navigation/disambiguation/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: Disambiguation -parent: Navigation -grand_parent: Tests ---- - -# Disambiguation - -When different pages with children have the same title, referencing the relevant grandparent in the children disambiguates which page is intended. - -- [Page A](a/) has a child [page with title C](ca/), and a grandchild [page with title D](dca/). -- [Page B](b/) has a child [page with title C](cb/), and a grandchild [page with title D](dcb/). -- The grandchild pages specify their parent and grandparent pages, so there is no ambiguity. diff --git a/docs/tests/navigation/exclusion/0.md b/docs/tests/navigation/exclusion/0.md deleted file mode 100644 index 96634dd..0000000 --- a/docs/tests/navigation/exclusion/0.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Tests for exclusion 0 -has_children: true -nav_exclude: true ---- -# Tests for exclusion 0 - -```yaml -title: Tests for exclusion 0 -has_children: true -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/00.md b/docs/tests/navigation/exclusion/00.md deleted file mode 100644 index 44aadd1..0000000 --- a/docs/tests/navigation/exclusion/00.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Tests for exclusion 00 -parent: Tests for exclusion 0 -has_children: true -nav_exclude: true ---- -# Tests for exclusion 00 - -```yaml -title: Tests for exclusion 00 -parent: Tests for exclusion 0 -has_children: true -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/000.md b/docs/tests/navigation/exclusion/000.md deleted file mode 100644 index 5846671..0000000 --- a/docs/tests/navigation/exclusion/000.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 000 -parent: Tests for exclusion 00 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: true ---- -# Tests for exclusion 000 - -```yaml -title: Tests for exclusion 000 -parent: Tests for exclusion 00 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/001.md b/docs/tests/navigation/exclusion/001.md deleted file mode 100644 index 3afe961..0000000 --- a/docs/tests/navigation/exclusion/001.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 001 -parent: Tests for exclusion 00 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: false ---- -# Tests for exclusion 001 - -```yaml -title: Tests for exclusion 001 -parent: Tests for exclusion 00 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/01.md b/docs/tests/navigation/exclusion/01.md deleted file mode 100644 index 0855b2c..0000000 --- a/docs/tests/navigation/exclusion/01.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Tests for exclusion 01 -parent: Tests for exclusion 0 -has_children: true -nav_exclude: false ---- -# Tests for exclusion 01 - -```yaml -title: Tests for exclusion 01 -parent: Tests for exclusion 0 -has_children: true -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/010.md b/docs/tests/navigation/exclusion/010.md deleted file mode 100644 index c9944ed..0000000 --- a/docs/tests/navigation/exclusion/010.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 010 -parent: Tests for exclusion 01 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: true ---- -# Tests for exclusion 010 - -```yaml -title: Tests for exclusion 010 -parent: Tests for exclusion 01 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/011.md b/docs/tests/navigation/exclusion/011.md deleted file mode 100644 index f8359b4..0000000 --- a/docs/tests/navigation/exclusion/011.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 011 -parent: Tests for exclusion 01 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: false ---- -# Tests for exclusion 011 - -```yaml -title: Tests for exclusion 011 -parent: Tests for exclusion 01 -grand_parent: Tests for exclusion 0 -has_children: false -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/1.md b/docs/tests/navigation/exclusion/1.md deleted file mode 100644 index 0b6bff8..0000000 --- a/docs/tests/navigation/exclusion/1.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Tests for exclusion 1 -has_children: true -nav_exclude: false ---- -# Tests for exclusion 1 - -```yaml -title: Tests for exclusion 1 -has_children: true -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/10.md b/docs/tests/navigation/exclusion/10.md deleted file mode 100644 index 624d115..0000000 --- a/docs/tests/navigation/exclusion/10.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Tests for exclusion 10 -parent: Tests for exclusion 1 -has_children: true -nav_exclude: true ---- -# Tests for exclusion 10 - -```yaml -title: Tests for exclusion 10 -parent: Tests for exclusion 1 -has_children: true -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/100.md b/docs/tests/navigation/exclusion/100.md deleted file mode 100644 index 89a8090..0000000 --- a/docs/tests/navigation/exclusion/100.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 100 -parent: Tests for exclusion 10 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: true ---- -# Tests for exclusion 100 - -```yaml -title: Tests for exclusion 100 -parent: Tests for exclusion 10 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/101.md b/docs/tests/navigation/exclusion/101.md deleted file mode 100644 index 240dac7..0000000 --- a/docs/tests/navigation/exclusion/101.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 101 -parent: Tests for exclusion 10 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: false ---- -# Tests for exclusion 101 - -```yaml -title: Tests for exclusion 101 -parent: Tests for exclusion 10 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/11.md b/docs/tests/navigation/exclusion/11.md deleted file mode 100644 index 04cef63..0000000 --- a/docs/tests/navigation/exclusion/11.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Tests for exclusion 11 -parent: Tests for exclusion 1 -has_children: true -nav_exclude: false ---- -# Tests for exclusion 11 - -```yaml -title: Tests for exclusion 11 -parent: Tests for exclusion 1 -has_children: true -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/110.md b/docs/tests/navigation/exclusion/110.md deleted file mode 100644 index 7c24237..0000000 --- a/docs/tests/navigation/exclusion/110.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 110 -parent: Tests for exclusion 11 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: true ---- -# Tests for exclusion 110 - -```yaml -title: Tests for exclusion 110 -parent: Tests for exclusion 11 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/111.md b/docs/tests/navigation/exclusion/111.md deleted file mode 100644 index 230b55b..0000000 --- a/docs/tests/navigation/exclusion/111.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: default -title: Tests for exclusion 111 -parent: Tests for exclusion 11 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: false ---- -# Tests for exclusion 111 - -```yaml -title: Tests for exclusion 111 -parent: Tests for exclusion 11 -grand_parent: Tests for exclusion 1 -has_children: false -nav_exclude: false -``` diff --git a/docs/tests/navigation/exclusion/excluded.md b/docs/tests/navigation/exclusion/excluded.md deleted file mode 100644 index 5f67d2b..0000000 --- a/docs/tests/navigation/exclusion/excluded.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: default -nav_exclude: true ---- -# Tests for exclusion untitled and excluded - -This page does not have a `title`, and it is explicitly excluded from the navigation - -```yaml -nav_exclude: true -``` diff --git a/docs/tests/navigation/exclusion/index.md b/docs/tests/navigation/exclusion/index.md deleted file mode 100644 index b7d4a3b..0000000 --- a/docs/tests/navigation/exclusion/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: default -title: Exclusion -parent: Navigation -grand_parent: Tests ---- - -# Exclusion - -Pages excluded from the main navigation can have parents and children. Navigation to and between excluded pages can be supported by the auto-generating list of child pages inserted at the bottom of each page, and by links to parents in the breadcrumbs at the top of each page. - -The following tests cover all combinations of excluded and included pages for the top level, child pages, and grandchild pages. The last binary digit in a page title indicates whether the page is included (1) or excluded (0); preceding digits refer to its parent and grandparent. - -## Included in main navigation - -- [Tests for exclusion 1](1/) -- [Tests for exclusion 11](11/) -- [Tests for exclusion 111](111/) - -## Included only in child navigation - -- [Tests for exclusion 110](110/) -- [Tests for exclusion 10](10/) -- [Tests for exclusion 101](101/) -- [Tests for exclusion 100](100/) -- [Tests for exclusion 01](01/) -- [Tests for exclusion 011](011/) -- [Tests for exclusion 010](010/) -- [Tests for exclusion 00](00/) -- [Tests for exclusion 001](001/) -- [Tests for exclusion 000](000/) - -## Not included in main or child navigation - -- [Tests for exclusion 0](0/) -- ["Untitled"](untitled/) diff --git a/docs/tests/navigation/exclusion/untitled.md b/docs/tests/navigation/exclusion/untitled.md deleted file mode 100644 index 4d8b4b4..0000000 --- a/docs/tests/navigation/exclusion/untitled.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: default ---- -# Tests for exclusion untitled - -This page does not have a `title`, and it is excluded from the navigation -- unless it is located in a Jekyll collection (which provides default titles). To exclude a title-less page from the navigation, regardless of whether it is located in a collection, set `nav_exclude: true`. diff --git a/docs/tests/navigation/index.md b/docs/tests/navigation/index.md deleted file mode 100644 index 90c6711..0000000 --- a/docs/tests/navigation/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: default -title: Navigation -parent: Tests -has_children: true ---- - -# Navigation diff --git a/docs/tests/navigation/order/default/10.md b/docs/tests/navigation/order/default/10.md deleted file mode 100644 index 7e1d82a..0000000 --- a/docs/tests/navigation/order/default/10.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: "10" -parent: Default -grand_parent: Tests for order ---- - -# 10 - -```yaml -title: "10" -parent: Default -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/default/2.md b/docs/tests/navigation/order/default/2.md deleted file mode 100644 index 158f49a..0000000 --- a/docs/tests/navigation/order/default/2.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: "2" -parent: Default -grand_parent: Tests for order ---- - -# 2 - -```yaml -title: "2" -parent: Default -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/default/a.md b/docs/tests/navigation/order/default/a.md deleted file mode 100644 index bd7e347..0000000 --- a/docs/tests/navigation/order/default/a.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: A -parent: Default -grand_parent: Tests for order ---- - -# A - -```yaml -title: A -parent: Default -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/default/aa-lower.md b/docs/tests/navigation/order/default/aa-lower.md deleted file mode 100644 index 295ed08..0000000 --- a/docs/tests/navigation/order/default/aa-lower.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: aa -parent: Default -grand_parent: Tests for order ---- - -# aa - -```yaml -title: aa -parent: Default -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/default/aa.md b/docs/tests/navigation/order/default/aa.md deleted file mode 100644 index f100030..0000000 --- a/docs/tests/navigation/order/default/aa.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: Aa -parent: Default -grand_parent: Tests for order ---- - -# Aa - -```yaml -title: Aa -parent: Default -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/default/index.md b/docs/tests/navigation/order/default/index.md deleted file mode 100644 index c276bb3..0000000 --- a/docs/tests/navigation/order/default/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Default -parent: Tests for order -nav_order: 1 -has_children: true ---- - -# Default Order - -When `nav_order` fields are omitted, the pages are ordered alphabetically by their titles. - -By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case). - -Digits precede letters, and numeric titles are ordered lexicographically: `10` precedes `2` (in contrast to explicit numeric `nav_order` values). diff --git a/docs/tests/navigation/order/floats/-1.1.md b/docs/tests/navigation/order/floats/-1.1.md deleted file mode 100644 index ee040c8..0000000 --- a/docs/tests/navigation/order/floats/-1.1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "-1.1" -nav_order: -1.1 -parent: Floats -grand_parent: Tests for order ---- - -# -1.1 - -```yaml -title: "-1.1" -nav_order: -1.1 -parent: Floats -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/floats/0.0.md b/docs/tests/navigation/order/floats/0.0.md deleted file mode 100644 index f5e516d..0000000 --- a/docs/tests/navigation/order/floats/0.0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "0.0" -nav_order: 0.0 -parent: Floats -grand_parent: Tests for order ---- - -# 0.0 - -```yaml -title: "0.0" -nav_order: 0.0 -parent: Floats -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/floats/10.0.md b/docs/tests/navigation/order/floats/10.0.md deleted file mode 100644 index 797f81d..0000000 --- a/docs/tests/navigation/order/floats/10.0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "10.0" -nav_order: 10.0 -parent: Floats -grand_parent: Tests for order ---- - -# 10.0 - -```yaml -title: "10.0" -nav_order: 10.0 -parent: Floats -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/floats/2.2222.md b/docs/tests/navigation/order/floats/2.2222.md deleted file mode 100644 index 8910946..0000000 --- a/docs/tests/navigation/order/floats/2.2222.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "2.2222" -nav_order: 2.2222 -parent: Floats -grand_parent: Tests for order ---- - -# 2.2222 - -```yaml -title: "2.2222" -nav_order: 2.2222 -parent: Floats -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/floats/index.md b/docs/tests/navigation/order/floats/index.md deleted file mode 100644 index 2846629..0000000 --- a/docs/tests/navigation/order/floats/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Floats -parent: Tests for order -nav_order: 4 -has_children: true ---- - -# Floating-Point Order - -When `nav_order` fields are floating-point numbers, the pages are ordered in increasing order of the numerical values. - -Floats include `0.0` and negative values. diff --git a/docs/tests/navigation/order/index.md b/docs/tests/navigation/order/index.md deleted file mode 100644 index 9dbff4a..0000000 --- a/docs/tests/navigation/order/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Order -parent: Navigation -grand_parent: Tests ---- - -# Order - -The value of `nav_order` can be numbers (integers, floats) and/or strings. The following tests illustrate their effects. - -- [Default](default/), using `title` instead of `nav_order` fields. -- [Strings](strings/), lexicographically ordered, possibly case-insensitively. -- [Integers](integers/), numerically ordered. -- [Floats](floats/), numerically ordered. -- [Mixture](mixture/), with numbers before strings. diff --git a/docs/tests/navigation/order/integers/-1.md b/docs/tests/navigation/order/integers/-1.md deleted file mode 100644 index 8b1444e..0000000 --- a/docs/tests/navigation/order/integers/-1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "-1" -nav_order: -1 -parent: Integers -grand_parent: Tests for order ---- - -# -1 - -```yaml -title: "-1" -nav_order: -1 -parent: Integers -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/integers/0.md b/docs/tests/navigation/order/integers/0.md deleted file mode 100644 index 21b1327..0000000 --- a/docs/tests/navigation/order/integers/0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "0" -nav_order: 0 -parent: Integers -grand_parent: Tests for order ---- - -# 0 - -```yaml -title: "0" -nav_order: 0 -parent: Integers -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/integers/10.md b/docs/tests/navigation/order/integers/10.md deleted file mode 100644 index 4157151..0000000 --- a/docs/tests/navigation/order/integers/10.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "10" -nav_order: 10 -parent: Integers -grand_parent: Tests for order ---- - -# 10 - -```yaml -title: "10" -nav_order: 10 -parent: Integers -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/integers/2.md b/docs/tests/navigation/order/integers/2.md deleted file mode 100644 index 2ebb1ca..0000000 --- a/docs/tests/navigation/order/integers/2.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "2" -nav_order: 2 -parent: Integers -grand_parent: Tests for order ---- - -# 2 - -```yaml -title: "2" -nav_order: 2 -parent: Integers -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/integers/index.md b/docs/tests/navigation/order/integers/index.md deleted file mode 100644 index 077cdc5..0000000 --- a/docs/tests/navigation/order/integers/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Integers -parent: Tests for order -nav_order: 3 -has_children: true ---- - -# Integer Order - -When `nav_order` fields are integers, the pages are ordered in increasing order of the numerical values. - -Integers include `0` and negative values. Integers can be reused for top-level pages and for different sets of child pages. diff --git a/docs/tests/navigation/order/mixture/-1.1.md b/docs/tests/navigation/order/mixture/-1.1.md deleted file mode 100644 index 668d642..0000000 --- a/docs/tests/navigation/order/mixture/-1.1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "-1.1" -nav_order: -1.1 -parent: Mixture -grand_parent: Tests for order ---- - -# -1.1 - -```yaml -title: "-1.1" -nav_order: -1.1 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/-1.md b/docs/tests/navigation/order/mixture/-1.md deleted file mode 100644 index e1c5a12..0000000 --- a/docs/tests/navigation/order/mixture/-1.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "-1" -nav_order: -1 -parent: Mixture -grand_parent: Tests for order ---- - -# -1 - -```yaml -title: "-1" -nav_order: -1 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/0.0.md b/docs/tests/navigation/order/mixture/0.0.md deleted file mode 100644 index a2006d8..0000000 --- a/docs/tests/navigation/order/mixture/0.0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "0.0" -nav_order: 0.0 -parent: Mixture -grand_parent: Tests for order ---- - -# 0.0 - -```yaml -title: "0.0" -nav_order: 0.0 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/0.md b/docs/tests/navigation/order/mixture/0.md deleted file mode 100644 index 14f137f..0000000 --- a/docs/tests/navigation/order/mixture/0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "0" -nav_order: 0 -parent: Mixture -grand_parent: Tests for order ---- - -# 0 - -```yaml -title: "0" -nav_order: 0 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/10.0.md b/docs/tests/navigation/order/mixture/10.0.md deleted file mode 100644 index 70308a6..0000000 --- a/docs/tests/navigation/order/mixture/10.0.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "10.0" -nav_order: 10.0 -parent: Mixture -grand_parent: Tests for order ---- - -# 10.0 - -```yaml -title: "10.0" -nav_order: 10.0 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/10.md b/docs/tests/navigation/order/mixture/10.md deleted file mode 100644 index 542ae3f..0000000 --- a/docs/tests/navigation/order/mixture/10.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: "10" -parent: Mixture -grand_parent: Tests for order ---- - -# 10 - -```yaml -title: "10" -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/2.2222.md b/docs/tests/navigation/order/mixture/2.2222.md deleted file mode 100644 index 2520d51..0000000 --- a/docs/tests/navigation/order/mixture/2.2222.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "2.2222" -nav_order: 2.2222 -parent: Mixture -grand_parent: Tests for order ---- - -# 2.2222 - -```yaml -title: "2.2222" -nav_order: 2.2222 -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/2.md b/docs/tests/navigation/order/mixture/2.md deleted file mode 100644 index 2ae4553..0000000 --- a/docs/tests/navigation/order/mixture/2.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: "2" -parent: Mixture -grand_parent: Tests for order ---- - -# 2 - -```yaml -title: "2" -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/a.md b/docs/tests/navigation/order/mixture/a.md deleted file mode 100644 index 342b05f..0000000 --- a/docs/tests/navigation/order/mixture/a.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: A -parent: Mixture -grand_parent: Tests for order ---- - -# A - -```yaml -title: A -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/aa-lower.md b/docs/tests/navigation/order/mixture/aa-lower.md deleted file mode 100644 index 2d63985..0000000 --- a/docs/tests/navigation/order/mixture/aa-lower.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: aa -nav_order: "aa" -parent: Mixture -grand_parent: Tests for order ---- - -# aa - -```yaml -title: aa -nav_order: "aa" -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/aa.md b/docs/tests/navigation/order/mixture/aa.md deleted file mode 100644 index 69cf05f..0000000 --- a/docs/tests/navigation/order/mixture/aa.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Aa -nav_order: "Aa" -parent: Mixture -grand_parent: Tests for order ---- - -# Aa - -```yaml -title: Aa -nav_order: "Aa" -parent: Mixture -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/mixture/index.md b/docs/tests/navigation/order/mixture/index.md deleted file mode 100644 index 24317b2..0000000 --- a/docs/tests/navigation/order/mixture/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: default -title: Mixture -parent: Tests for order -nav_order: 5 -has_children: true ---- - -# Mixed Order - -It seems unlikely that different types of `nav_order` values are needed for the children of the same parent. diff --git a/docs/tests/navigation/order/order.md b/docs/tests/navigation/order/order.md deleted file mode 100644 index 2d8cebf..0000000 --- a/docs/tests/navigation/order/order.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Tests for order -has_children: true ---- - -# Order diff --git a/docs/tests/navigation/order/strings/10.md b/docs/tests/navigation/order/strings/10.md deleted file mode 100644 index 6c3e480..0000000 --- a/docs/tests/navigation/order/strings/10.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "10" -nav_order: "10" -parent: Strings -grand_parent: Tests for order ---- - -# 10 - -```yaml -title: "10" -nav_order: "10" -parent: Strings -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/strings/2.md b/docs/tests/navigation/order/strings/2.md deleted file mode 100644 index 0c96c32..0000000 --- a/docs/tests/navigation/order/strings/2.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: "2" -nav_order: "2" -parent: Strings -grand_parent: Tests for order ---- - -# 2 - -```yaml -title: "2" -nav_order: "2" -parent: Strings -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/strings/a.md b/docs/tests/navigation/order/strings/a.md deleted file mode 100644 index ac1f3bd..0000000 --- a/docs/tests/navigation/order/strings/a.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: A -nav_order: A -parent: Strings -grand_parent: Tests for order ---- - -# A - -```yaml -title: A -nav_order: A -parent: Strings -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/strings/aa-lower.md b/docs/tests/navigation/order/strings/aa-lower.md deleted file mode 100644 index 0cbb0b2..0000000 --- a/docs/tests/navigation/order/strings/aa-lower.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: aa -nav_order: "aa" -parent: Strings -grand_parent: Tests for order ---- - -# aa - -```yaml -title: aa -nav_order: "aa" -parent: Strings -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/strings/aa.md b/docs/tests/navigation/order/strings/aa.md deleted file mode 100644 index 6eaf7a2..0000000 --- a/docs/tests/navigation/order/strings/aa.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: default -title: Aa -nav_order: "Aa" -parent: Strings -grand_parent: Tests for order ---- - -# Aa - -```yaml -title: Aa -nav_order: "Aa" -parent: Strings -grand_parent: Tests for order -``` diff --git a/docs/tests/navigation/order/strings/index.md b/docs/tests/navigation/order/strings/index.md deleted file mode 100644 index 404e3a8..0000000 --- a/docs/tests/navigation/order/strings/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Strings -parent: Tests for order -nav_order: 2 -has_children: true ---- - -# String Order - -By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case). - -Digits precede letters, and numeric titles are ordered lexicographically: `"10"` precedes `"2"` (in contrast to explicit numeric `nav_order` values). diff --git a/docs/tests/styling/dl.md b/docs/tests/styling/dl.md deleted file mode 100644 index 49dc034..0000000 --- a/docs/tests/styling/dl.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -layout: default -title: Description lists -parent: Styling -grand_parent: Tests ---- - -# Description lists - -The first child element of each `dd` element in a `dl` list should be aligned with the preceding `dt` element in the following examples. - -term - -: paragraph text - - paragraph text - -term - -: ### Header - - paragraph text - -term - -: > block quote - - paragraph text - -term - -: ```sh - fenced code block - ``` - - paragraph text - -term - -: + unordered list item - + unordered list item - - paragraph text - -term - -: 1. ordered list item - 2. ordered list item - - paragraph text - -term - -: sub-term - : sub-description - - sub-term - : sub-description - - paragraph text - -term - -: |-----------------+------------+-----------------+----------------| - | Default aligned |Left aligned| Center aligned | Right aligned | - |-----------------|:-----------|:---------------:|---------------:| - | First body part |Second cell | Third cell | fourth cell | - | Second line |foo | **strong** | baz | - | Third line |quux | baz | bar | - |-----------------+------------+-----------------+----------------| - | Second body | | | | - | 2 line | | | | - |=================+============+=================+================| - | Footer row | | | | - |-----------------+------------+-----------------+----------------| - - paragraph text - -term - -: *** - - paragraph text diff --git a/docs/tests/styling/index.md b/docs/tests/styling/index.md deleted file mode 100644 index 12782be..0000000 --- a/docs/tests/styling/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: default -title: Styling -parent: Tests -has_children: true ---- - -# Styling diff --git a/docs/tests/styling/ol.md b/docs/tests/styling/ol.md deleted file mode 100644 index 6e1468d..0000000 --- a/docs/tests/styling/ol.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -layout: default -title: Ordered lists -parent: Styling -grand_parent: Tests ---- - -# Ordered lists - -The first child element of each `li` element in an `ol` list should be aligned with the preceding label in the following examples. - -1. paragraph text - - paragraph text - -1. ### Header - - paragraph text - -1. > block quote - - paragraph text - -1. ```sh - fenced code block - ``` - - paragraph text - -1. + unordered list item - + unordered list item - - paragraph text - -1. 1. ordered list item - 2. ordered list item - - paragraph text - -1. term - : description - - term - : description - - paragraph text - -1. |-----------------+------------+-----------------+----------------| - | Default aligned |Left aligned| Center aligned | Right aligned | - |-----------------|:-----------|:---------------:|---------------:| - | First body part |Second cell | Third cell | fourth cell | - | Second line |foo | **strong** | baz | - | Third line |quux | baz | bar | - |-----------------+------------+-----------------+----------------| - | Second body | | | | - | 2 line | | | | - |=================+============+=================+================| - | Footer row | | | | - |-----------------+------------+-----------------+----------------| - - paragraph text - -1. *** - - paragraph text diff --git a/docs/tests/styling/ul.md b/docs/tests/styling/ul.md deleted file mode 100644 index 070b41a..0000000 --- a/docs/tests/styling/ul.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -layout: default -title: Unordered lists -parent: Styling -grand_parent: Tests ---- - -# Unordered lists - -The first child element of each `li` element in a `ul` list should be aligned with the preceding bullet in the following examples. - -- paragraph text - - paragraph text - -- ### Header - - paragraph text - -- > block quote - - paragraph text - -- ```sh - fenced code block - ``` - - paragraph text - -- + unordered list item - + unordered list item - - paragraph text - -- 1. ordered list item - 2. ordered list item - - paragraph text - -- term - : description - - term - : description - - paragraph text - -- |-----------------+------------+-----------------+----------------| - | Default aligned |Left aligned| Center aligned | Right aligned | - |-----------------|:-----------|:---------------:|---------------:| - | First body part |Second cell | Third cell | fourth cell | - | Second line |foo | **strong** | baz | - | Third line |quux | baz | bar | - |-----------------+------------+-----------------+----------------| - | Second body | | | | - | 2 line | | | | - |=================+============+=================+================| - | Footer row | | | | - |-----------------+------------+-----------------+----------------| - - paragraph text - -- *** - - paragraph text diff --git a/docs/ui-components/buttons.md b/docs/ui-components/buttons.md new file mode 100644 index 0000000..61fb1a2 --- /dev/null +++ b/docs/ui-components/buttons.md @@ -0,0 +1,97 @@ +--- +layout: default +title: Buttons +parent: UI Components +nav_order: 2 +--- + +# Buttons +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +## Basic button styles + +### Links that look like buttons + +
    +[Link button](https://just-the-docs.com){: .btn } + +[Link button](https://just-the-docs.com){: .btn .btn-purple } +[Link button](https://just-the-docs.com){: .btn .btn-blue } +[Link button](https://just-the-docs.com){: .btn .btn-green } + +[Link button](https://just-the-docs.com){: .btn .btn-outline } +
    +```markdown +[Link button](https://just-the-docs.com){: .btn } + +[Link button](https://just-the-docs.com){: .btn .btn-purple } +[Link button](https://just-the-docs.com){: .btn .btn-blue } +[Link button](https://just-the-docs.com){: .btn .btn-green } + +[Link button](https://just-the-docs.com){: .btn .btn-outline } +``` + +### Button element + +GitHub Flavored Markdown does not support the `button` element, so you'll have to use inline HTML for this: + +
    + +
    +```html + +``` + +--- + +## Using utilities with buttons + +### Button size + +Wrap the button in a container that uses the [font-size utility classes]({% link docs/utilities/typography.md %}) to scale buttons: + +
    + +[Big ass button](https://just-the-docs.com){: .btn } + + + +[Tiny ass button](https://just-the-docs.com){: .btn } + +
    +```markdown + +[Link button](https://just-the-docs.com){: .btn } + + + +[Tiny ass button](https://just-the-docs.com){: .btn } + +``` + +### Spacing between buttons + +Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block. + +
    +[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 } +[Button](https://just-the-docs.com){: .btn .btn-blue } + +[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 } +[Button](https://just-the-docs.com){: .btn .btn-blue } +
    +```markdown +[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 } +[Button](https://just-the-docs.com){: .btn .btn-blue } + +[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 } +[Button](https://just-the-docs.com){: .btn .btn-blue } +``` diff --git a/docs/ui-components/callouts.md b/docs/ui-components/callouts.md new file mode 100644 index 0000000..e0ea86f --- /dev/null +++ b/docs/ui-components/callouts.md @@ -0,0 +1,161 @@ +--- +layout: default +title: Callouts +parent: UI Components +nav_order: 7 +--- + +# Callouts +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes). + +Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`. + +{: .warning } +These callout names are *not* pre-defined by the theme: you need to define your own names. + +When you have [configured]({% link docs/configuration.md %}#callouts) the `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix] + +[^postfix]: + You can put the callout markup either before or after its content. + +#### An untitled callout +{: .no_toc } + +```markdown +{: .highlight } +A paragraph +``` + +{: .highlight } +A paragraph + + +#### A single paragraph callout +{: .no_toc } + +```markdown +{: .note } +A paragraph +``` + +{: .note } +A paragraph + +```markdown +{: .note-title } +> My note title +> +> A paragraph with a custom title callout +``` + +{: .note-title } +> My note title +> +> A paragraph with a custom title callout + +#### A multi-paragraph callout +{: .no_toc } + +```markdown +{: .important } +> A paragraph +> +> Another paragraph +> +> The last paragraph +``` + +{: .important } +> A paragraph +> +> Another paragraph +> +> The last paragraph + +```markdown +{: .important-title } +> My important title +> +> A paragraph +> +> Another paragraph +> +> The last paragraph +``` + +{: .important-title } +> My important title +> +> A paragraph +> +> Another paragraph +> +> The last paragraph + +#### An indented callout +{: .no_toc } + +```markdown +> {: .highlight } + A paragraph +``` + +> {: .highlight } + A paragraph + +#### Indented multi-paragraph callouts +{: .no_toc } + +```markdown +> {: .new } +> > A paragraph +> > +> > Another paragraph +> > +> > The last paragraph +``` + +> {: .new } +> > A paragraph +> > +> > Another paragraph +> > +> > The last paragraph + + +#### Nested callouts +{: .no_toc } + +```markdown +{: .important } +> {: .warning } +> A paragraph +``` + +{: .important } +> {: .warning } +> A paragraph + +#### Opaque background +{: .no_toc } + +```markdown +{: .important } +> {: .opaque } +>
    +> {: .warning } +> A paragraph +>
    +``` + +{: .important } +> {: .opaque } +>
    +> {: .warning } +> A paragraph +>
    diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md new file mode 100644 index 0000000..b7b99ad --- /dev/null +++ b/docs/ui-components/code.md @@ -0,0 +1,205 @@ +--- +layout: default +title: Code +parent: UI Components +has_children: true +nav_order: 6 +--- + +# Code +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +## Inline code + +Code can be rendered inline by wrapping it in single back ticks. + +
    +Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +## Heading with `` in it. +{: .no_toc } +
    +```markdown +Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +## Heading with `` in it. +``` + +--- + +## Syntax highlighted code blocks + +Use Jekyll's built-in syntax highlighting with Rouge for code blocks by using three backticks, followed by the language name: + +
    +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l) + return true; +} +``` +
    +{% highlight markdown %} +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l) + return true; +} +``` +{% endhighlight %} + +--- + +## Code blocks with rendered examples + +To demonstrate front end code, sometimes it's useful to show a rendered example of that code. After including the styles from your project that you'll need to show the rendering, you can use a `
    ` with the `code-example` class, followed by the code block syntax. If you want to render your output with Markdown instead of HTML, use the `markdown="1"` attribute to tell Jekyll that the code you are rendering will be in Markdown format... This is about to get meta... + +
    + +
    + +[Link button](https://just-the-docs.com){: .btn } + +
    +```markdown +[Link button](https://just-the-docs.com){: .btn } +``` + +
    +{% highlight markdown %} +
    + +[Link button](https://just-the-docs.com){: .btn } + +
    +```markdown +[Link button](https://just-the-docs.com){: .btn } +``` +{% endhighlight %} + +--- + +## Mermaid diagram code blocks +{: .d-inline-block } + +New (v0.4.0) +{: .label .label-green } + +[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`. + +The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)): + +```yaml +mermaid: + # Version of mermaid library + # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ + version: "9.1.3" +``` + +Additional configuration options are loaded through `_includes/mermaid_config.js`. By default, the contents of the file are the empty object: + +```js +// _includes/mermaid_config.js +{} +``` + +This loads the default settings. + +The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to: + +```js +// _includes/mermaid_config.js +{ + theme: "forest" +} +``` + +Once mermaid is installed, it can be used in markdown files. The markdown for a simple flowchart example might look like the following: + +{% highlight markdown %} +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` +{% endhighlight %} + +which renders: + +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` + +*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.* + +### Using a local mermaid library + +To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g. + +```yaml +mermaid: + version: "10.1.0" + # for (v10+) + path: "/assets/js/mermaid.esm.min.mjs" + # for (=10`, this file is imported directly as an ESM module (rather than as a plain `