diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..d88454b --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: just-the-docs +open_collective: just-the-docs diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml deleted file mode 100644 index 6a1034e..0000000 --- a/.github/release-drafter.yml +++ /dev/null @@ -1,35 +0,0 @@ -references: - - v+ - - main -name-template: "v$RESOLVED_VERSION 🌈" -tag-template: "v$RESOLVED_VERSION" -categories: - - title: "🚀 Features" - labels: - - "feature" - - "enhancement" - - title: "🐛 Bug Fixes" - labels: - - "fix" - - "bugfix" - - "bug" - - title: "🧰 Maintenance" - label: - - "chore" - - "dependencies" -change-template: "- $TITLE @$AUTHOR (#$NUMBER)" -version-resolver: - major: - labels: - - "next-major-release" - minor: - labels: - - "next-minor-release" - patch: - labels: - - "patch" - default: minor -template: | - ## Changes - - $CHANGES diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 938a3ec..f403ead 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,38 +16,79 @@ jobs: matrix: jekyll-version: [3.9, 4.3] os: [ ubuntu-latest, macos-latest, windows-latest ] - ruby-version: [2.7, 3.1] + ruby-version: ["3.0", "3.1", "3.2"] runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Ruby ${{ matrix.ruby-version }} uses: ruby/setup-ruby@v1 with: ruby-version: ${{ matrix.ruby-version }} bundler-cache: false - - name: Bundle Install + - name: Bundle Install (Jekyll ${{ matrix.jekyll-version }}) run: bundle install - - name: Install Jekyll ${{ matrix.jekyll-version }} - run: gem install jekyll -v ${{ matrix.jekyll-version }} + env: + BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }} - name: Init Search run: bundle exec rake search:init + env: + BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }} - name: Build Site run: bundle exec jekyll build + env: + BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }} github-pages-build: name: Build (github-pages gem) runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: '3.1' + ruby-version: "3.2" bundler-cache: false - name: Bundle Install - run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle install + run: bundle install + env: + BUNDLE_GEMFILE: fixtures/Gemfile-github-pages - name: Build Site - run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle exec jekyll build + run: bundle exec jekyll build + env: + BUNDLE_GEMFILE: fixtures/Gemfile-github-pages + + validate: + name: Validate HTML + strategy: + fail-fast: false + matrix: + ruby-version: ["3.2"] + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Setup Ruby ${{ matrix.ruby-version }} + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby-version }} + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + - name: Cache HTMLProofer + id: cache-htmlproofer + uses: actions/cache@v3 + with: + path: tmp/.htmlproofer + key: ${{ runner.os }}-htmlproofer + - name: Build Site + run: bundle exec jekyll build + - name: Test with Nu Validator + uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8 + with: + config: fixtures/html5validator-config.yml + - name: Test with html-proofer + run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/" + env: + NOKOGIRI_USE_SYSTEM_LIBRARIES: true assets: name: Test CSS and JS @@ -58,9 +99,9 @@ jobs: node-version: [18.x] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v1 + uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} - run: npm install diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index bfb8de3..cc7a8fb 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -30,16 +30,16 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Setup Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: '3.1' # Not needed with a .ruby-version file + ruby-version: "3.2" bundler-cache: true # runs 'bundle install' and caches installed gems automatically cache-version: 0 # Increment this number if you need to re-download cached gems - name: Setup Pages id: pages - uses: actions/configure-pages@v2 + uses: actions/configure-pages@v3 - name: Build with Jekyll # Outputs to the './_site' directory by default run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" @@ -47,7 +47,7 @@ jobs: JEKYLL_ENV: production - name: Upload artifact # Automatically uploads an artifact from the './_site' directory by default - uses: actions/upload-pages-artifact@v1 + uses: actions/upload-pages-artifact@v2 # Deployment job deploy: @@ -59,4 +59,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v1 + uses: actions/deploy-pages@v2 diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml index 2446874..338f61d 100644 --- a/.github/workflows/publish-gem.yml +++ b/.github/workflows/publish-gem.yml @@ -9,11 +9,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - name: Set up Ruby 3.1 - uses: actions/setup-ruby@v1 + - uses: actions/checkout@v4 + - name: Setup Ruby 3.2 + uses: ruby/setup-ruby@v1 with: - ruby-version: 3.1 + ruby-version: "3.2" - name: Publish to GPR run: | diff --git a/.gitignore b/.gitignore index 043fa83..c3a1190 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,30 @@ +# Not sure what a .gitignore is? +# See: https://git-scm.com/docs/gitignore + +# The first files are directly copied from Jekyll's first-party docs on `.gitignore` files: +# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control + +# Ignore the default location of the built site, and caches and metadata generated by Jekyll +_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata + +# Ignore folders generated by Bundler +.bundle/ +vendor/ + +# These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers. + +# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code. +# We use Node.js as our runtime, so we ignore node_modules +node_modules + +# .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them. +# See: https://en.wikipedia.org/wiki/.DS_Store +.DS_Store + +# These are legacy globs that typically target Ruby theme developers. We may change these at a later date. *.gem .bundle .ruby-version -.jekyll-cache -.sass-cache -_site -Gemfile.lock -node_modules -.DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c76a86..9dd0a57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,16 +15,300 @@ The project underwent a major maintenance shift in March 2022. {: .note } This website is built from the `HEAD` of the `main` branch of the theme repository. -{: .warning } -This website includes docs for some new features that are not available in `v0.5.0`! - Code changes to `main` that are *not* in the latest release: -- n/a +- N/A -Docs changes in `main` that are *not* in the latest release: +## Release v0.7.0 -- n/a +Hi folks! This is a minor release that adds a new configuration option for opening external links in a new tab and provides many bugfixes (in both correctness and performance) for Just the Docs users with large sites. We anticipate that for most users, this is a straightforward upgrade. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme. + +### Migrating to `v0.7.0` + +**Migration**: users will need to migrate if: + +- they overrode `_includes/nav.html`, which has moved to `_includes/components/nav.html` +- they have an element with the IDs `jtd-nav-activation` or `jtd-head-nav-stylesheet` + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.7.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.7.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.7.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.7.0" +``` + +To use and pin a previous version of the theme, replace the `0.7.0` with the desired release tag. + +### New Features + +- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360] + +### Bugfixes + +- Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356] +- Fixed: improve build time by [@pdmosses] in [#1358] +- Fixed: erroneous parentheses in `site_nav` conditional by [@mattxwang] in [#1366] +- Fixed: navigation scroll to active link regression by [@pdmosses] in [#1367] +- Fixed: invalid CSS rules in head elements by [@pdmosses] in [#1368] +- Fixed: accidental disabling of forward-declared stylesheets by [@mattxwang] in [#1373] + +{: .warning } +[#1358] moved `_includes/nav.html` to the `_includes/components` directory, +Users who were overriding that file will need to adjust their sites accordingly. + +### Documentation: + +- Docs: fix typos in `CHANGELOG` and `MIGRATION` by [@thapasusheel] in [#1377] + +### New Contributors + +- [@CarbonNeuron] made their first contribution in [#1360] +- [@thapasusheel] made their first contribution in [#1377] + +[@CarbonNeuron]: https://github.com/CarbonNeuron +[@thapasusheel]: https://github.com/thapasusheel + +[#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356 +[#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358 +[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360 +[#1366]: https://github.com/just-the-docs/just-the-docs/pull/1366 +[#1367]: https://github.com/just-the-docs/just-the-docs/pull/1367 +[#1368]: https://github.com/just-the-docs/just-the-docs/pull/1368 +[#1373]: https://github.com/just-the-docs/just-the-docs/pull/1373 +[#1377]: https://github.com/just-the-docs/just-the-docs/pull/1377 + +## 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 @@ -38,7 +322,7 @@ As always, we'd love your feedback. [Open an issue](https://github.com/just-the- **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.github.io/just-the-docs/MIGRATION/). +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). ### Using Release `v0.5.0` @@ -78,7 +362,7 @@ To use and pin a previous version of the theme, replace the `0.5.0` with the des 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.github.io/just-the-docs/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`. +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! @@ -179,16 +463,16 @@ We're so excited to release Just the Docs `v0.4.0`. This release has been almost `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.github.io/just-the-docs/docs/ui-components/callouts/), a new design component to highlight content -- [configuring mermaid.js](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library -- [copy code button](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#copy-button) for code snippets -- [external navigation links](https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#external-navigation-links) +- [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.github.io/just-the-docs/docs/customization/#custom-layouts-and-includes) (advanced feature) -- [new custom includes](https://just-the-docs.github.io/just-the-docs/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices +- [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.github.io/just-the-docs/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/) +- 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`.* @@ -221,7 +505,7 @@ 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.github.io/just-the-docs/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. +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. @@ -429,7 +713,7 @@ This RC does not introduce any major user-facing features. It adds more customiz ### 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. +Similar 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: @@ -530,7 +814,7 @@ Have any questions, thoughts, or concerns? We'd love to hear from you! Please [o ### 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`. +Similar 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: @@ -651,7 +935,7 @@ As soon as we get stable test results from major downstream users, we'll push ou ### 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`. +Similar 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: @@ -727,7 +1011,7 @@ The intention of this release candidate is to gather even more feedback on a pot ### 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`. +Similar 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: @@ -815,7 +1099,7 @@ We want your feedback! Are these changes helpful? Are our docs easy to understan ### 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`. +Due to the massive scope of these changes, we're making `v0.4.0.rc1` available 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: @@ -1327,7 +1611,7 @@ fixes #291 #256 #293 #177 ## v0.2.1 -This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version. +This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version. ## v0.2.0 diff --git a/Gemfile b/Gemfile index aef0d56..76bd139 100644 --- a/Gemfile +++ b/Gemfile @@ -3,4 +3,6 @@ gemspec gem "jekyll-github-metadata", ">= 2.15" -gem "webrick", "~> 1.7" +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..8ed4e67 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,150 @@ +PATH + remote: . + specs: + just-the-docs (0.7.0) + 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 index aaacded..f134c7f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -43,11 +43,111 @@ This document contains instructions on how to migrate and upgrade Just the Docs [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %} +## v0.6.x - v0.7.0 + +### POTENTIALLY-BREAKING CHANGES in v0.7.0 + +There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern: + +1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html` + - **explicit migration only necessary if users have overridden `_includes/nav.html`** +2. the addition of ` @@ -26,14 +44,7 @@ - {% for file in site.static_files %} - {% if file.path == site.favicon_ico or file.path == '/favicon.ico' %} - {% assign favicon = true %} - {% endif %} - {% endfor %} - {% if favicon %} - - {% endif %} + {% include_cached favicon.html %} {% seo %} diff --git a/_includes/nav.html b/_includes/nav.html deleted file mode 100644 index e80dfcd..0000000 --- a/_includes/nav.html +++ /dev/null @@ -1,251 +0,0 @@ -{%- comment -%} - The `nav_order` values of pages affect the order in which they are shown in - the navigation panel and in the automatically generated tables of contents. - Sibling pages with the same `nav_order` value may be shown in any order. - Sibling pages with no `nav_order` value are shown after all pages that have - explicit `nav_order` values, ordered by their `title` values. - - The `nav_order` and `title` values can be numbers or strings. To avoid build - failures, we sort numbers and strings separately. We sort numbers by their - values, and strings lexicographically. The case-sensitivity of string sorting - is determined by the configuration setting of `nav_sort`. Pages with no `title` - value are excluded from the navigation. - - Note: Numbers used as `title` or `nav_order` values should not be in quotes, - unless you intend them to be lexicographically ordered. Numbers are written - without spaces or thousands-separators. Negative numbers are preceded by `-`. - Floats are written with the integral and fractional parts separated by `.`. - (Bounds on the magnitude and precision are presumably the same as in Liquid.) -{%- endcomment -%} - -{%- assign title_pages = include.pages - | where_exp: "item", "item.title != nil" -%} - -{%- comment -%} - A page with `nav_exclude: true` does not appear in the main navigation. - If it has a `parent`, it may appear in the parent's table of contents. - If it specifies `has_children: true`, it should appear in the breadcrumbs - of the child pages, but its order in relation to other pages is irrelevant. - Pages that never appear can be removed from the pages that need to be sorted. - This optimisation can be significant on a site with many pages. - - In Jekyll 4, the pages to be sorted can be filtered by: - - {%- assign title_pages = title_pages - | where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%} - - That filter is not allowed in Jekyll 3. The following iterative code gives the - same effect, but it is activated only when it will filter more than 50% of the - pages. -{%- endcomment -%} - -{%- unless title_pages == empty -%} - {%- assign unsorted_pages = title_pages - | where_exp: "item", "item.parent == nil" - | where_exp: "item", "item.nav_exclude == true" -%} - {%- assign title_pages_size = title_pages.size -%} - {%- assign unsorted_pages_percent = unsorted_pages.size - | times: 100 | divided_by: title_pages_size -%} - {%- if unsorted_pages_percent > 50 -%} - {%- assign sorted_pages = "" | split: "" -%} - {%- for item in title_pages -%} - {%- if item.nav_exclude != true or item.parent -%} - {%- assign sorted_pages = sorted_pages | push: item -%} - {%- endif -%} - {%- endfor -%} - {%- assign title_pages = sorted_pages -%} - {%- endif -%} -{%- endunless -%} - -{%- assign nav_order_pages = title_pages - | where_exp: "item", "item.nav_order != nil" -%} -{%- assign title_order_pages = title_pages - | where_exp: "item", "item.nav_order == nil" -%} - -{%- comment -%} - Divide the arrays of `nav_order_pages` and `title_order_pages` according to - the type of value. - - The first character of the result of `jsonify` is `"` only for strings. - Grouping by a single character also ensures the number of groups is small. -{%- endcomment -%} - -{%- assign nav_number_pages = "" | split: "" -%} -{%- assign nav_string_pages = "" | split: "" -%} -{%- assign nav_order_groups = nav_order_pages - | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%} -{%- for group in nav_order_groups -%} - {%- if group.name == '"' -%} - {%- assign nav_string_pages = group.items -%} - {%- else -%} - {%- assign nav_number_pages = nav_number_pages | concat: group.items -%} - {%- endif -%} -{%- endfor -%} - -{%- unless nav_number_pages == empty -%} - {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%} -{%- endunless -%} - -{%- unless nav_string_pages == empty -%} - {%- if site.nav_sort == 'case_insensitive' -%} - {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%} - {%- else -%} - {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%} - {%- endif -%} -{%- endunless -%} - -{%- assign title_number_pages = "" | split: "" -%} -{%- assign title_string_pages = "" | split: "" -%} -{%- assign title_order_groups = title_order_pages - | group_by_exp: "item", "item.title | jsonify | slice: 0" -%} -{%- for group in title_order_groups -%} - {%- if group.name == '"' -%} - {%- assign title_string_pages = group.items -%} - {%- else -%} - {%- assign title_number_pages = title_number_pages | concat: group.items -%} - {%- endif -%} -{%- endfor -%} - -{%- unless title_number_pages == empty -%} - {%- assign title_number_pages = title_number_pages | sort: "title" -%} -{%- endunless -%} - -{%- unless title_string_pages == empty -%} - {%- if site.nav_sort == 'case_insensitive' -%} - {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%} - {%- else -%} - {%- assign title_string_pages = title_string_pages | sort: "title" -%} - {%- endif -%} -{%- endunless -%} - -{%- assign pages_list = nav_number_pages | concat: nav_string_pages - | concat: title_number_pages | concat: title_string_pages -%} - -{%- assign first_level_pages = pages_list - | where_exp: "item", "item.parent == nil" -%} -{%- assign second_level_pages = pages_list - | where_exp: "item", "item.parent != nil" - | where_exp: "item", "item.grand_parent == nil" -%} -{%- assign third_level_pages = pages_list - | where_exp: "item", "item.grand_parent != nil" -%} - -{%- comment -%} - The order of sibling pages in `pages_list` determines the order of display of - links to them in lists of navigation links and in auto-generated TOCs. - - Note that Liquid evaluates conditions from right to left (and it does not allow - the use of parentheses). Some conditions are not so easy to express clearly... - - For example, consider the following condition: - - C: page.collection = = include.key and - page.url = = node.url or - page.grand_parent = = node.title or - page.parent = = node.title and - page.grand_parent = = nil - - Here, `node` is a first-level page. The last part of the condition - -- namely: `page.parent = = node.title and page.grand_parent = = nil` -- - is evaluated first; it holds if and only if `page` is a child of `node`. - - The condition `page.grand_parent = = node.title or ...` holds when - `page` is a grandchild of node, OR `...` holds. - - The condition `page.url = = node.url or ...` holds when - `page` is `node`, OR `...` holds. - - The condition C: `page.collection = = include.key and ...` holds when we are - generating the nav links for a collection that includes `page`, AND `...` holds. -{%- endcomment -%} - - - -{%- comment -%} - `page.collection` is the name of the Jekyll collection that contains the page, - if any, and otherwise nil. Similarly for `include.key`. - - If the current page is in the collection (if any) whose navigation is currently - being generated, the following code sets `first_level_url` to the URL used in - the page's top-level breadcrumb (if any), and `second_level_url` to that used - in the page's second-level breadcrumb (if any). - - For pages with children, the code also sets `toc_list` to the list of child pages, - reversing the order if needed. -{%- endcomment -%} - -{%- if page.collection == include.key -%} - {%- for node in first_level_pages -%} - {%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%} - {%- assign first_level_url = node.url | relative_url -%} - {%- endif -%} - {%- if node.has_children -%} - {%- assign children_list = second_level_pages | where: "parent", node.title -%} - {%- for child in children_list -%} - {%- if child.has_children -%} - {%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%} - {%- assign second_level_url = child.url | relative_url -%} - {%- endif -%} - {%- endif -%} - {%- endfor -%} - {%- endif -%} - {%- endfor -%} - {%- if page.has_children == true and page.has_toc != false -%} - {%- assign toc_list = pages_list - | where: "parent", page.title - | where_exp: "item", "item.grand_parent == page.parent" -%} - {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%} - {%- assign toc_list = toc_list | reverse -%} - {%- endif -%} - {%- endif -%} -{%- endif -%} diff --git a/_includes/sorted_pages.html b/_includes/sorted_pages.html new file mode 100644 index 0000000..659be10 --- /dev/null +++ b/_includes/sorted_pages.html @@ -0,0 +1,109 @@ +{%- comment -%} + Include as: {%- include sorted_pages.html pages=array_of_pages -%} + Depends on: include.pages. + Assigns to: sorted_pages. + Overwrites: + nav_order_pages, title_order_pages, double_quote, empty_array, + nav_number_pages, nav_string_pages, nav_order_groups, group, + title_number_pages, title_string_pages, title_order_groups. +{%- endcomment -%} + +{%- comment -%} + The `nav_order` values of pages affect the order in which they are shown in + the navigation panel and in the automatically generated tables of contents. + Sibling pages with the same `nav_order` value may be shown in any order. + Sibling pages with no `nav_order` value are shown after all pages that have + explicit `nav_order` values, ordered by their `title` values. + + The `nav_order` and `title` values can be numbers or strings. To avoid build + failures, we sort numbers and strings separately. We sort numbers by their + values, and strings lexicographically. The case-sensitivity of string sorting + is determined by the configuration setting of `nav_sort`. Pages with no `title` + value are excluded from the navigation. + + Note: Numbers used as `title` or `nav_order` values should not be in quotes, + unless you intend them to be lexicographically ordered. Numbers are written + without spaces or thousands-separators. Negative numbers are preceded by `-`. + Floats are written with the integral and fractional parts separated by `.`. + (Bounds on the magnitude and precision are presumably the same as in Liquid.) +{%- endcomment -%} + +{%- assign nav_order_pages = include.pages + | where_exp: "item", "item.nav_order != nil" -%} +{%- assign title_order_pages = include.pages + | where_exp: "item", "item.nav_order == nil" -%} + +{%- comment -%} + First, filter `nav_order_pages` and `title_order_pages` according to the type + of value to be used for sorting. + + The first character of the result of filtering with `jsonify` is `"` only for + strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for + numbers, so grouping the pages gives at most two groups. +{%- endcomment -%} + +{%- assign double_quote = '"' -%} +{%- assign empty_array = "" | split: "" -%} + +{%- assign nav_string_pages = empty_array -%} +{%- assign nav_number_pages = empty_array -%} +{%- unless nav_order_pages == empty -%} + {%- assign nav_order_groups = nav_order_pages + | group_by_exp: "item", + "item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%} + {%- for group in nav_order_groups -%} + {%- if group.name == 0 -%} + {%- assign nav_string_pages = group.items -%} + {%- elsif group.name == 1 -%} + {%- assign nav_number_pages = group.items -%} + {%- endif -%} + {%- endfor -%} +{%- endunless -%} + +{%- assign title_string_pages = empty_array -%} +{%- assign title_number_pages = empty_array -%} +{%- unless title_order_pages == empty -%} + {%- assign title_order_groups = title_order_pages + | group_by_exp: "item", + "item.title | jsonify | slice: 0 | remove: double_quote | size" -%} + {%- for group in title_order_groups -%} + {%- if group.name == 0 -%} + {%- assign title_string_pages = group.items -%} + {%- elsif group.name == 1 -%} + {%- assign title_number_pages = group.items -%} + {%- endif -%} + {%- endfor -%} +{%- endunless -%} + +{%- comment -%} + Now sort each array of pages separately, then concatenate the sorted arrays. +{%- endcomment -%} + +{%- unless nav_number_pages == empty -%} + {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%} +{%- endunless -%} + +{%- unless nav_string_pages == empty -%} + {%- if site.nav_sort == 'case_insensitive' -%} + {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%} + {%- else -%} + {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%} + {%- endif -%} +{%- endunless -%} + +{%- unless title_number_pages == empty -%} + {%- assign title_number_pages = title_number_pages | sort: "title" -%} +{%- endunless -%} + +{%- unless title_string_pages == empty -%} + {%- if site.nav_sort == 'case_insensitive' -%} + {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%} + {%- else -%} + {%- assign title_string_pages = title_string_pages | sort: "title" -%} + {%- endif -%} +{%- endunless -%} + +{%- assign sorted_pages = nav_number_pages + | concat: nav_string_pages + | concat: title_number_pages + | concat: title_string_pages -%} diff --git a/_includes/title.html b/_includes/title.html index 8bd3fa8..8f65336 100644 --- a/_includes/title.html +++ b/_includes/title.html @@ -1,5 +1,5 @@ {% if site.logo %} - + {% else %} {{ site.title }} {% endif %} diff --git a/_layouts/default.html b/_layouts/default.html index 3bc0e0a..923c1c1 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -12,21 +12,21 @@ layout: table_wrappers {% include components/sidebar.html %}
{% include components/header.html %} -
+
{% include components/breadcrumbs.html %} -
- {% if site.heading_anchors != false %} - {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} - {% else %} - {{ content }} - {% endif %} - - {% if page.has_children == true and page.has_toc != false %} - {% include components/children_nav.html toc_list=toc_list %} - {% endif %} +
+
+ {% if site.heading_anchors != false %} + {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} + {% else %} + {{ content }} + {% endif %} + {% if page.has_children == true and page.has_toc != false %} + {% include components/children_nav.html %} + {% endif %} +
{% include components/footer.html %} -
{% if site.search_enabled != false %} diff --git a/_layouts/minimal.html b/_layouts/minimal.html index 0fb9511..b12c5db 100644 --- a/_layouts/minimal.html +++ b/_layouts/minimal.html @@ -9,33 +9,7 @@ layout: table_wrappers Skip to main content {% include icons/icons.html %} - {% comment %} - This is a bandaid fix to properly render breadcrumbs; as of now, there is some variable leakage between the sidebar component (which computes parents, grandparents) and the breadcrumbs component. We plan to remove this in a future release to deduplicate code. - - For more context, see https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057014053 - {% endcomment %} - {% capture nav %} - {% assign pages_top_size = site.html_pages - | where_exp:"item", "item.title != nil" - | where_exp:"item", "item.parent == nil" - | where_exp:"item", "item.nav_exclude != true" - | size %} - {% if pages_top_size > 0 %} - {% include nav.html pages=site.html_pages key=nil %} - {% endif %} - {% if site.just_the_docs.collections %} - {% assign collections_size = site.just_the_docs.collections | size %} - {% for collection_entry in site.just_the_docs.collections %} - {% assign collection_key = collection_entry[0] %} - {% assign collection_value = collection_entry[1] %} - {% assign collection = site[collection_key] %} - {% if collection_value.nav_exclude != true %} - {% include nav.html pages=collection key=collection_key %} - {% endif %} - {% endfor %} - {% endif %} - {% endcapture %} -
+
{% include components/breadcrumbs.html %}
{% if site.heading_anchors != false %} @@ -45,7 +19,7 @@ layout: table_wrappers {% endif %} {% if page.has_children == true and page.has_toc != false %} - {% include components/children_nav.html toc_list=toc_list %} + {% include components/children_nav.html %} {% endif %} {% include components/footer.html %} diff --git a/_sass/base.scss b/_sass/base.scss index 0dc1ddb..0068d71 100644 --- a/_sass/base.scss +++ b/_sass/base.scss @@ -1,6 +1,10 @@ // Base element style overrides // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id +:root { + color-scheme: $color-scheme; +} + * { box-sizing: border-box; } @@ -104,6 +108,6 @@ blockquote { // resets user-agent stylesheets for blockquotes margin-block-start: 0; margin-inline-start: 0; - padding-left: 15px; + padding-left: 1rem; border-left: 3px solid $border-color; } diff --git a/_sass/buttons.scss b/_sass/buttons.scss index cd6177e..7953f7f 100644 --- a/_sass/buttons.scss +++ b/_sass/buttons.scss @@ -17,7 +17,9 @@ background-color: $base-button-color; border-width: 0; border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); appearance: none; &:focus { @@ -87,7 +89,9 @@ &:focus { text-decoration: none; outline: none; - box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25); + box-shadow: + inset 0 0 0 2px $grey-dk-100, + 0 0 0 3px rgba(blue, 0.25); } &:focus:hover, @@ -111,3 +115,13 @@ .btn-green { @include btn-color($white, $green-100); } + +.btn-reset { + background: none; + border: none; + margin: 0; + text-align: inherit; + font: inherit; + border-radius: 0; + appearance: none; +} diff --git a/_sass/color_schemes/dark.scss b/_sass/color_schemes/dark.scss index 0e444b7..6d0999b 100644 --- a/_sass/color_schemes/dark.scss +++ b/_sass/color_schemes/dark.scss @@ -1,3 +1,4 @@ +$color-scheme: dark; $body-background-color: $grey-dk-300; $body-heading-color: $grey-lt-000; $body-text-color: $grey-lt-300; diff --git a/_sass/color_schemes/light.scss b/_sass/color_schemes/light.scss index 64bbd3a..799e9c6 100644 --- a/_sass/color_schemes/light.scss +++ b/_sass/color_schemes/light.scss @@ -1,3 +1,4 @@ +$color-scheme: light !default; $body-background-color: $white !default; $body-heading-color: $grey-dk-300 !default; $body-text-color: $grey-dk-100 !default; diff --git a/_sass/labels.scss b/_sass/labels.scss index 85a7ba1..98cc8f9 100644 --- a/_sass/labels.scss +++ b/_sass/labels.scss @@ -1,7 +1,11 @@ // Labels (not the form kind) -.label, -.label-blue { +// this :not() prevents a style clash with Mermaid.js's +// diagram labels, which also use .label +// for more, see https://github.com/just-the-docs/just-the-docs/issues/1272 +// and the accompanying PR +.label:not(g), +.label-blue:not(g) { display: inline-block; padding: 0.16em 0.56em; margin-right: $sp-2; @@ -15,19 +19,19 @@ border-radius: 12px; } -.label-green { +.label-green:not(g) { background-color: $green-200; } -.label-purple { +.label-purple:not(g) { background-color: $purple-100; } -.label-red { +.label-red:not(g) { background-color: $red-200; } -.label-yellow { +.label-yellow:not(g) { color: $grey-dk-200; background-color: $yellow-200; } diff --git a/_sass/print.scss b/_sass/print.scss index 5702f15..ee76a3c 100644 --- a/_sass/print.scss +++ b/_sass/print.scss @@ -21,7 +21,7 @@ } .site-title { - font-size: $root-font-size !important; + font-size: 1rem !important; font-weight: 700 !important; } diff --git a/_sass/search.scss b/_sass/search.scss index 6cfe95e..cdf8d6e 100644 --- a/_sass/search.scss +++ b/_sass/search.scss @@ -23,7 +23,9 @@ height: $sp-8; overflow: hidden; border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); transition: height linear #{$transition-duration * 0.5}; @include mq(md) { @@ -42,7 +44,7 @@ width: 100%; height: 100%; padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5}; - font-size: 16px; + font-size: 1rem; color: $body-text-color; background-color: $search-background-color; border-top: 0; @@ -53,7 +55,7 @@ @include mq(md) { padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5}; - font-size: 14px; + font-size: 0.875rem; background-color: $body-background-color; transition: padding-left linear #{$transition-duration * 0.5}; } @@ -96,7 +98,9 @@ background-color: $search-background-color; border-bottom-right-radius: $border-radius; border-bottom-left-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); @include mq(md) { top: 100%; @@ -230,7 +234,9 @@ background-color: $search-background-color; border: 1px solid rgba($link-color, 0.3); border-radius: #{$sp-9 * 0.5}; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); align-items: center; justify-content: center; } @@ -244,7 +250,9 @@ height: 0; background-color: rgba(0, 0, 0, 0.3); opacity: 0; - transition: opacity ease $transition-duration, width 0s $transition-duration, + transition: + opacity ease $transition-duration, + width 0s $transition-duration, height 0s $transition-duration; } @@ -264,7 +272,9 @@ @include mq(md) { width: $search-results-width; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); } } @@ -290,7 +300,10 @@ width: 100%; height: 100%; opacity: 1; - transition: opacity ease $transition-duration, width 0s, height 0s; + transition: + opacity ease $transition-duration, + width 0s, + height 0s; } @include mq(md) { diff --git a/_sass/support/_functions.scss b/_sass/support/_functions.scss deleted file mode 100644 index 290709a..0000000 --- a/_sass/support/_functions.scss +++ /dev/null @@ -1,9 +0,0 @@ -@function rem($size, $unit: "") { - $rem-size: $size / $root-font-size; - - @if $unit == false { - @return #{$rem-size}; - } @else { - @return #{$rem-size}rem; - } -} diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index 42a1cf8..0b051ff 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -1,9 +1,10 @@ // Typography +// prettier-ignore $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", - roboto, "Helvetica Neue", arial, sans-serif !default; + roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default; $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default; -$root-font-size: 16px !default; // Base font-size for rems +$root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems $body-line-height: 1.4 !default; $content-line-height: 1.6 !default; $body-heading-line-height: 1.25 !default; @@ -11,18 +12,18 @@ $body-heading-line-height: 1.25 !default; // Font size // `-sm` suffix is the size at the small (and above) media query -$font-size-1: 9px !default; -$font-size-1-sm: 10px !default; -$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small -$font-size-3: 12px !default; // h5 -$font-size-4: 14px !default; -$font-size-5: 16px !default; // h3 -$font-size-6: 18px !default; // h2 -$font-size-7: 24px !default; -$font-size-8: 32px !default; // h1 -$font-size-9: 36px !default; -$font-size-10: 42px !default; -$font-size-10-sm: 48px !default; +$font-size-1: 0.5625rem !default; +$font-size-1-sm: 0.625rem !default; +$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small +$font-size-3: 0.75rem !default; // h5 +$font-size-4: 0.875rem !default; +$font-size-5: 1rem !default; // h3 +$font-size-6: 1.125rem !default; // h2 +$font-size-7: 1.5rem !default; +$font-size-8: 2rem !default; // h1 +$font-size-9: 2.25rem !default; +$font-size-10: 2.625rem !default; +$font-size-10-sm: 3rem !default; // Colors @@ -95,22 +96,22 @@ $border-color: $grey-lt-100 !default; $gutter-spacing: $sp-6 !default; $gutter-spacing-sm: $sp-4 !default; -$nav-width: 264px !default; -$nav-width-md: 248px !default; +$nav-width: 16.5rem !default; +$nav-width-md: 15.5rem !default; $nav-list-item-height: $sp-6 !default; $nav-list-item-height-sm: $sp-8 !default; $nav-list-expander-right: true; -$content-width: 800px !default; -$header-height: 60px !default; +$content-width: 50rem !default; +$header-height: 3.75rem !default; $search-results-width: $content-width - $nav-width !default; $transition-duration: 400ms; // Media queries in pixels $media-queries: ( - xs: 320px, - sm: 500px, + xs: 20rem, + sm: 31.25rem, md: $content-width, lg: $content-width + $nav-width, - xl: 1400px, + xl: 87.5rem, ) !default; diff --git a/_sass/support/mixins/_buttons.scss b/_sass/support/mixins/_buttons.scss index e3e6c4f..cd51da3 100644 --- a/_sass/support/mixins/_buttons.scss +++ b/_sass/support/mixins/_buttons.scss @@ -4,7 +4,9 @@ color: $fg; background-color: darken($bg, 2%); background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%)); - box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12); + box-shadow: + 0 1px 3px rgba(0, 0, 0, 0.25), + 0 4px 10px rgba(0, 0, 0, 0.12); &:hover, &.zeroclipboard-is-hover { diff --git a/_sass/support/mixins/_layout.scss b/_sass/support/mixins/_layout.scss index 89b6e11..a9b32ee 100644 --- a/_sass/support/mixins/_layout.scss +++ b/_sass/support/mixins/_layout.scss @@ -12,7 +12,7 @@ // If the key exists in the map @if $value { // Prints a media query based on the value - @media (width >= rem($value)) { + @media (min-width: $value) { @content; } } @else { diff --git a/_sass/support/support.scss b/_sass/support/support.scss index 8131a32..e800592 100644 --- a/_sass/support/support.scss +++ b/_sass/support/support.scss @@ -1,3 +1,2 @@ @import "./variables"; -@import "./functions"; @import "./mixins/mixins"; diff --git a/_sass/tables.scss b/_sass/tables.scss index db8f9de..c5d8491 100644 --- a/_sass/tables.scss +++ b/_sass/tables.scss @@ -8,7 +8,9 @@ margin-bottom: $sp-5; overflow-x: auto; border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.12), + 0 3px 10px rgba(0, 0, 0, 0.08); } table { @@ -21,7 +23,7 @@ th, td { @include fs-3; - min-width: 120px; + min-width: 7.5rem; padding: $sp-2 $sp-3; background-color: $table-background-color; border-bottom: $border rgba($border-color, 0.5); diff --git a/assets/css/just-the-docs-head-nav.css b/assets/css/just-the-docs-head-nav.css new file mode 100644 index 0000000..0cb97b3 --- /dev/null +++ b/assets/css/just-the-docs-head-nav.css @@ -0,0 +1,24 @@ +--- +--- +{%- if site.color_scheme and site.color_scheme != "nil" -%} + {%- assign color_scheme = site.color_scheme -%} +{%- else -%} + {%- assign color_scheme = "light" -%} +{%- endif -%} + +{%- capture newline %} +{% endcapture -%} + +{%- capture scss -%} +{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %} +.site-nav ul li a { + background-image: linear-gradient( + -90deg, + rgba($feedback-color, 1) 0%, + rgba($feedback-color, 0.8) 80%, + rgba($feedback-color, 0) 100% + ); +} +{%- endcapture -%} + +{{ scss | scssify | split: newline | slice: -3, 3 | join: newline }} diff --git a/assets/js/just-the-docs.js b/assets/js/just-the-docs.js index a3253a1..b7e3655 100644 --- a/assets/js/just-the-docs.js +++ b/assets/js/just-the-docs.js @@ -31,7 +31,7 @@ function initNav() { } if (target) { e.preventDefault(); - target.parentNode.classList.toggle('active'); + target.ariaPressed = target.parentNode.classList.toggle('active'); } }); @@ -39,15 +39,19 @@ function initNav() { const mainHeader = document.getElementById('main-header'); const menuButton = document.getElementById('menu-button'); + disableHeadStyleSheets(); + jtd.addEvent(menuButton, 'click', function(e){ e.preventDefault(); if (menuButton.classList.toggle('nav-open')) { siteNav.classList.add('nav-open'); mainHeader.classList.add('nav-open'); + menuButton.ariaPressed = true; } else { siteNav.classList.remove('nav-open'); mainHeader.classList.remove('nav-open'); + menuButton.ariaPressed = false; } }); @@ -64,6 +68,26 @@ function initNav() { {%- endif %} } +// The element is assumed to include the following stylesheets: +// - a to /assets/css/just-the-docs-head-nav.css, +// with id 'jtd-head-nav-stylesheet' +// - a