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..155338e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,7 @@ 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 @@ -25,14 +25,18 @@ jobs: 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) @@ -42,12 +46,50 @@ jobs: - 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@v3 + - 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@v2 + 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@c7bb77a0fe3b0458583de50fd0f4dd819569b8a9 + with: + root: _site + blacklist: line-numbers + - 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 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index bfb8de3..7204f12 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -34,7 +34,7 @@ jobs: - 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 diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml index 2446874..fd833c5 100644 --- a/.github/workflows/publish-gem.yml +++ b/.github/workflows/publish-gem.yml @@ -10,10 +10,10 @@ jobs: steps: - uses: actions/checkout@v3 - - name: Set up Ruby 3.1 - uses: actions/setup-ruby@v1 + - 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 577b3f8..835f1d4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,33 @@ +# 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 + +# We also use Storybook to test regressions in changes; we ignore the build output. +storybook-static + +# .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 -*.log -storybook-static diff --git a/CHANGELOG.md b/CHANGELOG.md index b7b0c70..4900381 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,25 +15,219 @@ 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: -- Fixed: disable copy code button in insecure contexts [@rmoff] in [#1226] +- Fixed: Windows emoji font fallback by [@flanakin] in [#1337] -Docs changes in `main` that are *not* in the latest release: +[#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 @@ -49,7 +243,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` @@ -89,7 +283,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! @@ -190,16 +384,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`.* @@ -232,7 +426,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. 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..e8f60c8 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,150 @@ +PATH + remote: . + specs: + just-the-docs (0.6.1) + 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..eca953d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -43,6 +43,78 @@ This document contains instructions on how to migrate and upgrade Just the Docs [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 @@ -71,7 +143,7 @@ For those users, we suggest moving those variables and functions to each relevan The theme repo is now at . The name of its default branch is now `main`. -The theme docs website is now published at . +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]. @@ -84,7 +156,7 @@ 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.github.io/just-the-docs +[home page]: https://just-the-docs.com #### Deploy previews diff --git a/README.md b/README.md index 7876f7b..d8b76b8 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

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!

+

See it in action!




@@ -102,7 +102,7 @@ The theme is available as open source under the terms of the [MIT License](http: [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.github.io/just-the-docs/ +[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 diff --git a/_config.yml b/_config.yml index edab376..dccfcf3 100644 --- a/_config.yml +++ b/_config.yml @@ -15,8 +15,8 @@ # in the templates via {{ site.myvariable }}. title: Just the Docs description: A Jekyll theme for documentation -baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog -url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com +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 @@ -103,7 +103,7 @@ heading_anchors: true # Aux links for the upper right navigation aux_links: "Just the Docs on GitHub": - - "//github.com/just-the-docs/just-the-docs" + - "https://github.com/just-the-docs/just-the-docs" # Makes Aux links open in a new tab. Default is false aux_links_new_tab: false @@ -169,6 +169,7 @@ callouts: plugins: - jekyll-seo-tag - jekyll-github-metadata + - jekyll-include-cache kramdown: syntax_highlighter_opts: diff --git a/_includes/components/breadcrumbs.html b/_includes/components/breadcrumbs.html index f1bc488..82ad6bd 100644 --- a/_includes/components/breadcrumbs.html +++ b/_includes/components/breadcrumbs.html @@ -1,15 +1,43 @@ -{% unless page.url == "/" %} - {% if page.parent %} - - {% endif %} -{% endunless %} +{%- 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/_includes/components/children_nav.html b/_includes/components/children_nav.html index e76f98d..ce2482a 100644 --- a/_includes/components/children_nav.html +++ b/_includes/components/children_nav.html @@ -1,9 +1,33 @@ +{%- 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 include.toc_list %} -
  • - {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} -
    • - {% endfor %} +{% for child in sorted_pages %} +
  • + {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} +
    • +{% endfor %}
diff --git a/_includes/components/search_footer.html b/_includes/components/search_footer.html index fb4fe51..d448fdb 100644 --- a/_includes/components/search_footer.html +++ b/_includes/components/search_footer.html @@ -1,7 +1,7 @@ {% if site.search.button %} - - - + {% endif %}
diff --git a/_includes/components/search_header.html b/_includes/components/search_header.html index 98425d5..3562124 100644 --- a/_includes/components/search_header.html +++ b/_includes/components/search_header.html @@ -1,6 +1,6 @@ {% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %} -
+