diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..19e7274 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,14 @@ +# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): bullseye, buster +ARG VARIANT=bullseye +FROM mcr.microsoft.com/vscode/devcontainers/jekyll:0-${VARIANT} + +# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10 +ARG NODE_VERSION="none" +RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi + +# [Optional] Uncomment this section to install additional OS packages. +# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ +# && apt-get -y install --no-install-recommends + +# [Optional] Uncomment this line to install global node packages. +# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 \ No newline at end of file diff --git a/.devcontainer/base.Dockerfile b/.devcontainer/base.Dockerfile new file mode 100644 index 0000000..9e3296a --- /dev/null +++ b/.devcontainer/base.Dockerfile @@ -0,0 +1,26 @@ +# [Choice] Debian OS version (use 2.7-bullseye on local arm64/Apple Silicon): 2.7-bullseye, 2.7-buster +ARG VARIANT=2.7-bullseye +FROM mcr.microsoft.com/vscode/devcontainers/ruby:${VARIANT} +COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers + +# ENV Variables required by Jekyll +ENV LANG=en_US.UTF-8 \ + LANGUAGE=en_US:en \ + TZ=Etc/UTC \ + LC_ALL=en_US.UTF-8 \ + LANG=en_US.UTF-8 \ + LANGUAGE=en_US + +# Install bundler, latest jekyll, and github-pages for older jekyll +RUN gem install bundler jekyll github-pages + +# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10 +ARG NODE_VERSION="none" +RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi + +# [Optional] Uncomment this section to install additional OS packages. +# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ +# && apt-get -y install --no-install-recommends + +# [Optional] Uncomment this line to install global node packages. +# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..5e56136 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,35 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll +{ + "name": "Just the docs", + "build": { + "dockerfile": "Dockerfile", + "args": { + // Update 'VARIANT' to pick a Debian OS version: bullseye, buster + // Use bullseye when on local arm64/Apple Silicon. + "VARIANT": "bullseye", + // Enable Node.js: pick the latest LTS version + "NODE_VERSION": "lts/*" + } + }, + + // Set *default* container specific settings.json values on container create. + "settings": {}, + + // Add the IDs of extensions you want installed when the container is created. + "extensions": ["GitHub.vscode-pull-request-github"], + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + "forwardPorts": [ + // Jekyll server + 4000, + // Live reload server + 35729 + ], + + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "sh .devcontainer/post-create.sh", + + // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode" +} diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100644 index 0000000..8c25f3d --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +# Install the version of Bundler. +if [ -f Gemfile.lock ] && grep "BUNDLED WITH" Gemfile.lock > /dev/null; then + cat Gemfile.lock | tail -n 2 | grep -C2 "BUNDLED WITH" | tail -n 1 | xargs gem install bundler -v +fi + +# If there's a Gemfile, then run `bundle install` +# It's assumed that the Gemfile will install Jekyll too +if [ -f Gemfile ]; then + bundle install +fi 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/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..f3d5c41 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: bug +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..fd77ad0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Ask a question + url: https://github.com/just-the-docs/just-the-docs/discussions + about: Ask questions and discuss with other community members diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..11fc491 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: enhancement +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..c0cd718 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: +- package-ecosystem: npm + directory: "/" + schedule: + interval: daily + time: "10:00" + open-pull-requests-limit: 10 +- package-ecosystem: bundler + directory: "/" + schedule: + interval: daily + time: "10:00" + open-pull-requests-limit: 10 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..f403ead --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,108 @@ +on: + push: + branches: + - main + pull_request: + branches: + - main + +name: CI + +jobs: + jekyll-build: + name: Build (jekyll gem) + strategy: + fail-fast: false + matrix: + jekyll-version: [3.9, 4.3] + os: [ ubuntu-latest, macos-latest, windows-latest ] + ruby-version: ["3.0", "3.1", "3.2"] + runs-on: ${{ matrix.os }} + steps: + - 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 (Jekyll ${{ matrix.jekyll-version }}) + run: bundle install + 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@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.2" + bundler-cache: false + - name: Bundle Install + run: bundle install + env: + BUNDLE_GEMFILE: fixtures/Gemfile-github-pages + - name: Build Site + 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 + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [18.x] + + steps: + - uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v3 + with: + node-version: ${{ matrix.node-version }} + - run: npm install + - run: npm test diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..cc7a8fb --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,62 @@ +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll site to Pages + +on: + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + 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@v3 + - name: Build with Jekyll + # Outputs to the './_site' directory by default + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + # Automatically uploads an artifact from the './_site' directory by default + uses: actions/upload-pages-artifact@v2 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml new file mode 100644 index 0000000..338f61d --- /dev/null +++ b/.github/workflows/publish-gem.yml @@ -0,0 +1,40 @@ +name: Publish Ruby Gem + +on: + workflow_dispatch + +jobs: + build: + name: Publish + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Setup Ruby 3.2 + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.2" + + - name: Publish to GPR + run: | + mkdir -p $HOME/.gem + touch $HOME/.gem/credentials + chmod 0600 $HOME/.gem/credentials + printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials + gem build *.gemspec + gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem + env: + GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}" + OWNER: ${{ github.repository_owner }} + + # Disabled as this does not handle 2FA + # - name: Publish to RubyGems + # run: | + # mkdir -p $HOME/.gem + # touch $HOME/.gem/credentials + # chmod 0600 $HOME/.gem/credentials + # printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials + # gem build *.gemspec + # gem push *.gem + # env: + # GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}" diff --git a/.github/workflows/update_jekyll-anchor-heading.yml b/.github/workflows/update_jekyll-anchor-heading.yml new file mode 100644 index 0000000..4206ee2 --- /dev/null +++ b/.github/workflows/update_jekyll-anchor-heading.yml @@ -0,0 +1,43 @@ +name: Update Vendor plugin - jekyll-anchor-headings +on: + # schedule: + # # once per week + # - cron: "0 15 * * 0" + workflow_dispatch: +jobs: + update-deps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Get latest release information + id: latest-release + uses: pozetroninc/github-action-get-latest-release@master + with: + owner: allejo + repo: jekyll-anchor-headings + excludes: prerelease, draft + + - name: Update jekyll-anchor-headings + id: update + uses: suisei-cn/actions-download-file@v1.3.0 + with: + url: "https://github.com/allejo/jekyll-anchor-headings/releases/download/${{ steps.latest-release.outputs.release }}/anchor_headings.html" + target: _includes/vendor/ + + - name: Create PR + uses: peter-evans/create-pull-request@v4 + with: + commit-message: "chore[dependency]: Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}`" + title: "auto: Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}`" + body: | + Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}` + This is an automated pull request. + branch: update/vendor/jekyll-anchor-headings + delete-branch: true + labels: | + kind/update + area/dependency + add-paths: | + _includes/vendor/anchor_headings.html + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c3a1190 --- /dev/null +++ b/.gitignore @@ -0,0 +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 diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..6ac9c86 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,11 @@ +package-lock.json +_site +assets/css/just-the-docs-default.scss +assets/css/just-the-docs-light.scss +assets/css/just-the-docs-dark.scss +assets/js/vendor/lunr.min.js +assets/js/search-data.json +assets/js/zzzz-search-data.json +assets/js/just-the-docs.js +*.md +_includes/mermaid_config.js diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..6d5d5f3 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,26 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Serve", + "type": "shell", + "command": "bundle exec jekyll serve --livereload", + "group": { + "kind": "test", + "isDefault": true + }, + "isBackground": true + }, + { + "label": "Build", + "type": "shell", + "command": "bundle exec jekyll build", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} diff --git a/404.html b/404.html new file mode 100644 index 0000000..a2d250a --- /dev/null +++ b/404.html @@ -0,0 +1,11 @@ +--- +layout: default +title: 404 +permalink: /404 +nav_exclude: true +search_exclude: true +--- + +

Page not found

+ +

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

diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9dd0a57 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1670 @@ +--- +title: CHANGELOG +layout: default +--- + +# CHANGELOG + +All notable user-facing changes to this project are documented in this file. + +{: .highlight } +The project underwent a major maintenance shift in March 2022. + +## HEAD + +{: .note } +This website is built from the `HEAD` of the `main` branch of the theme repository. + +Code changes to `main` that are *not* in the latest release: + +- N/A + +## Release v0.7.0 + +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 + +Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`. + +We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Migrating to `v0.5.0` + +**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves. + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.5.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.0" +``` + +To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag. + +### Bugfixes + +- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209] +- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208] +- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190] +- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107] +- Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0) + +[#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107 +[#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187 +[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190 +[#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208 +[#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209 + +## Release v0.4.2 + +Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.com/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.2" +``` + +To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag. + +### Bugfixes + +- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166] +- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173] +- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184] +- Removed: unused dark syntax themes by [@mattxwang] in [#1192] + +### Documentation + +- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2) + +[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166 +[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173 +[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182 +[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184 +[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192 + +## Release v0.4.1 + +Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.1" +``` + +To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag. + +### Bugfixes + +- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165] +- Fixed: AsciiDoc code block styling by [@flyx] in [#1168] +- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177] +- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167] + +### Documentation + +- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108] + +### New Contributors + +- [@flyx] made their first contribution in [#1168] +- [@Dima-369] made their first contribution in [#1177] + +[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108 +[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165 +[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167 +[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168 +[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177 + +[@flyx]: https://github.com/flyx +[@Dima-369]: https://github.com/Dima-369 + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1) + +## Release v0.4.0 + +We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme. + +### Brief Overview - Highlighted Changes + +`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes: + +- better support for dark theme: dark highlighting, search input color +- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content +- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library +- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets +- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links) +- major improvements to nav generation efficiency and robustness +- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content) +- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature) +- [new custom includes](https://just-the-docs.com/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices +- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more! +- more documentation for [custom includes](https://just-the-docs.com/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.com/MIGRATION/) + +*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.* + +### Using Release `v0.4.0` + +Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0" +``` + +If you would prefer to not upgrade, you can enforce that explicitly: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Migration Guide and Strategies + +We've developed a new [migration guide](https://just-the-docs.com/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site. + +**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes. + +Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release. + +For support with migrating to `v0.4.0`, [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Roadmap (What's Next?) + +Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future! + +Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release. + +For version `v0.5`, our roadmap includes: + +- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences +- better GDPR compliance for analytics +- multi-level/recursive navigation (unlimited hierarchy of child pages) + +In future versions, we also plan on: + +- adding better dark theme defaults +- adding better internationalization support +- exploring offline PDF generation +- improving accessibility within the theme +- improving search functionality +- refactoring and improving the robustness of our codebase + +Have ideas for what's next, or want to get involved? [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! We're looking for more contributors and maintainers to help us develop the theme. + +### New Features + +- Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +- Added: custom favicon `_includes` by [@burner1024] in [#364] +- Added: set color for search input by [@pdmosses] in [#498] +- Added: search placeholder configuration by [@mattxwang] in [#613] +- Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +- Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +- Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +- Added: mermaid.js support by [@nascosto] in [#857] +- Added: support for external navigation links by [@SPGoding] in [#876] +- Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes + +- Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +- Fixed: nested task lists (#517) by [@pdmosses] in [#855] +- Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +- Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +- Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +- Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +- Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +- Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +- Fixed: allow links to wrap by [@pdmosses] in [#905] +- Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Maintenance + +- Added: VScode devcontainer by [@max06] in [#783] +- Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +- Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +- Updated: new repo path by [@pmarsceill] in [#775] +- Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +- Updated: README by [@pmarsceill] in [#777] +- Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +- Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +- Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] +- Deleted: unused script directory by [@mattxwang] in [#937] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Documentation + +- Added: docs on how to break an `ol` by [@pdmosses] in [#856] +- Added: docs for custom includes by [@nathanjessen] in [#806] +- Added: document caveat about variable dependencies by [@waldyrious] in [#555] +- Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Added: migration guide by [@pdmosses] in [#1059] +- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138] +- Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +- Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +- Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +- Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +- Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +- Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +- Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +- Fixed: spacing in toc example by [@henryiii] in [#835] +- Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +- Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Fixed: typo in changelog links [@koppor] in [#1000] +- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130] +- Fixed: broken relative page links by [@mattxwang] in [#1106] +- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Updated: `README` demo video by [@codewithfan] in [#1097] + +### New Contributors + +- [@AdityaTiwari2102] made their first contribution in [#477] +- [@svrooij] made their first contribution in [#544] +- [@alexsegura] made their first contribution in [#519] +- [@burner1024] made their first contribution in [#364] +- [@JeffGuKang] made their first contribution in [#221] +- [@dougaitken] made their first contribution in [#782] +- [@max06] made their first contribution in [#783] +- [@sehilyi] made their first contribution in [#499] +- [@nathanjessen] made their first contribution in [#473] +- [@waldyrious] made their first contribution in [#549] +- [@MichelleBlanchette] made their first contribution in [#554] +- [@henryiii] made their first contribution in [#835] +- [@jmertic] made their first contribution in [#726] +- [@jacobhq] made their first contribution in [#846] +- [@UnclassedPenguin] made their first contribution in [#814] +- [@alyssais] made their first contribution in [#829] +- [@nascosto] made their first contribution in [#857] +- [@SPGoding] made their first contribution in [#876] +- [@iridazzle] made their first contribution in [#727] +- [@ivanskodje] made their first contribution in [#891] +- [@Eisverygoodletter] made their first contribution in [#893] +- [@robinpokorny] made their first contribution in [#940] +- [@olgarithms] made their first contribution in [#951] +- [@manuelhenke] made their first contribution in [#941] +- [@JPrevost] made their first contribution in [#950] +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +## Pre-release v0.4.0.rc5 + +Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release. + +This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), `lunr` indexing, and loading `mermaid` locally. In addition, it fixes bugs introduced in `.rc4`: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from `v0.3.3`. + +### Trying out pre-release `v0.4.0.rc5` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc5" +``` + +By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes and Maintenance + +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Docs + +- Docs: add a migration guide by [@pdmosses] in [#1059] +- Docs: update `README` demo video by [@codewithfan] in [#1097] +- Docs: update "View Typography Utilities" link by [@agabrys] in [#1130] +- Docs: fix broken relative page links by [@mattxwang] in [#1106] +- Docs: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Docs: label new features introduced in `v0.4` by [@mattxwang] in [#1138] + +### New Contributors + +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +[#1059]: https://github.com/just-the-docs/just-the-docs/pull/1059 +[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068 +[#1097]: https://github.com/just-the-docs/just-the-docs/pull/1097 +[#1106]: https://github.com/just-the-docs/just-the-docs/pull/1106 +[#1123]: https://github.com/just-the-docs/just-the-docs/pull/1123 +[#1124]: https://github.com/just-the-docs/just-the-docs/pull/1124 +[#1128]: https://github.com/just-the-docs/just-the-docs/pull/1128 +[#1130]: https://github.com/just-the-docs/just-the-docs/pull/1130 +[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135 +[#1138]: https://github.com/just-the-docs/just-the-docs/pull/1138 +[#1139]: https://github.com/just-the-docs/just-the-docs/pull/1139 +[#1142]: https://github.com/just-the-docs/just-the-docs/pull/1142 +[#1143]: https://github.com/just-the-docs/just-the-docs/pull/1143 +[#1153]: https://github.com/just-the-docs/just-the-docs/pull/1153 + +[@agabrys]: https://github.com/agabrys +[@codewithfan]: https://github.com/codewithfan +[@diablodale]: https://github.com/diablodale +[@fabrik42]: https://github.com/fabrik42 +[@kevinlin1]: https://github.com/kevinlin1 +[@EricFromCanada]: https://github.com/EricFromCanada +[@m-r-mccormick]: https://github.com/m-r-mccormick + +## Pre-release v0.4.0.rc4 + +Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. **We aim to re-release this as `v0.4.0`, with only few changes**. + +Notable new additions include: + +- modular site components, which split up the site into smaller reusable components; advanced theme users can then remix layouts quickly without duplication +- a "copy code" button to code blocks +- fixing bugs in generated TOCs and navigation from previous prereleases +- various cleanups of CSS and HTML markup + +The roadmap to `v0.4.0` is small. We are only looking to: + +- finish a migration guide, so users can easily upgrade from `v0.3.3` to `v0.4.0` +- fix one last bug relating to callouts and custom colors +- fix any new bugs introduced by this pre-release + +Have any questions, thoughts, or concerns? We'd love to hear from you! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc4` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc4" +``` + +By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] + +### Bugfixes and Maintenance + +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Docs + +- Docs: fix typo in changelog links [@koppor] in [#1000] +- Docs: update homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Docs: update README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Docs: fix two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Docs: Add warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Docs: remove Google Analytics on main site by [@mattxwang] in [#1113] + +### New Contributors + +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4 + +[#945]: https://github.com/just-the-docs/just-the-docs/pull/945 +[#999]: https://github.com/just-the-docs/just-the-docs/pull/999 +[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000 +[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001 +[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010 +[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015 +[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018 +[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019 +[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021 +[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027 +[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029 +[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040 +[#1058]: https://github.com/just-the-docs/just-the-docs/pull/1058 +[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061 +[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065 +[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071 +[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074 +[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076 +[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077 +[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090 +[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091 +[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092 +[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095 +[#1096]: https://github.com/just-the-docs/just-the-docs/pull/1096 +[#1102]: https://github.com/just-the-docs/just-the-docs/pull/1102 +[#1104]: https://github.com/just-the-docs/just-the-docs/pull/1104 +[#1110]: https://github.com/just-the-docs/just-the-docs/pull/1110 +[#1113]: https://github.com/just-the-docs/just-the-docs/pull/1113 + +[@captn3m0]: https://github.com/captn3m0 +[@deseo]: https://github.com/deseo +[@koppor]: https://github.com/koppor +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@simonebortolin]: https://github.com/simonebortolin +[@SConaway]: https://github.com/SConaway +[@Tom-Brouwer]: https://github.com/Tom-Brouwer + +## Pre-release v0.4.0.rc3 + +Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`. + +In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease. + +We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work! + +### Trying out pre-release `v0.4.0.rc3` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc3" +``` + +By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +Broadly, this prerelease is feature-light! + +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] + +### Bugfixes and Experimental Features + +*Note*: experimental nav optimization may be unstable. Please give us feedback! + +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] + +[#965]: https://github.com/just-the-docs/just-the-docs/pull/965 +[#960]: https://github.com/just-the-docs/just-the-docs/pull/960 +[#962]: https://github.com/just-the-docs/just-the-docs/pull/962 +[#964]: https://github.com/just-the-docs/just-the-docs/pull/964 +[#967]: https://github.com/just-the-docs/just-the-docs/pull/967 +[#974]: https://github.com/just-the-docs/just-the-docs/pull/974 +[#980]: https://github.com/just-the-docs/just-the-docs/pull/980 +[#985]: https://github.com/just-the-docs/just-the-docs/pull/985 +[#986]: https://github.com/just-the-docs/just-the-docs/pull/986 +[#992]: https://github.com/just-the-docs/just-the-docs/pull/992 + +[@henryiii]: https://github.com/henryiii + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3 + +## Pre-release v0.4.0.rc2 + +{: .warning } +This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`! + +Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight: + +- significant improvement on build time of navigation panel by [@pdmosses] + - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds! +- improved accessibility features led by [@JPrevost] +- more docs! + +The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know! + +### Trying out pre-release `v0.4.0.rc2` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc2" +``` + +By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] + +[#950]: https://github.com/just-the-docs/just-the-docs/pull/950 +[#944]: https://github.com/just-the-docs/just-the-docs/pull/944 +[#939]: https://github.com/just-the-docs/just-the-docs/pull/939 +[#949]: https://github.com/just-the-docs/just-the-docs/pull/949 +[#941]: https://github.com/just-the-docs/just-the-docs/pull/941 +[#956]: https://github.com/just-the-docs/just-the-docs/pull/956 + +[@alyssais]: https://github.com/alyssais + +### Documentation and Maintenance + +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Deleted: unused script directory by [@mattxwang] in [#937] + +[#935]: https://github.com/just-the-docs/just-the-docs/pull/935 +[#940]: https://github.com/just-the-docs/just-the-docs/pull/940 +[#951]: https://github.com/just-the-docs/just-the-docs/pull/951 +[#955]: https://github.com/just-the-docs/just-the-docs/pull/955 +[#937]: https://github.com/just-the-docs/just-the-docs/pull/937 + +### New Contributors + +* [@robinpokorny] made their first contribution in [#940] +* [@olgarithms] made their first contribution in [#951] +* [@manuelhenke] made their first contribution in [#941] +* [@JPrevost] made their first contribution in [#950] + +[@robinpokorny]: https://github.com/robinpokorny +[@olgarithms]: https://github.com/olgarithms +[@manuelhenke]: https://github.com/manuelhenke +[@JPrevost]: https://github.com/JPrevost + +## Pre-release v0.4.0.rc1 + +### We're back! + +Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include: + +- The new callouts component +- Allowing pages and collections to coexist on the navigation pane +- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements +- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting +- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color +- More documentation, especially on using custom includes +- Updating core dependencies to stable Ruby versions +- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way! + +We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc1` + +Due to the massive scope of these changes, we're making `v0.4.0.rc1` 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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc1" +``` + +### Staying on `v0.3.3` + +If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to `v0.3.3` (i.e. by a `Gemfile.lock` or in `remote_theme`, then there's nothing you need to do. + +If you have not pinned your theme version, you should either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +{: .warning } +Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`. + +### Maintenance + +Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks! + +The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time! + +[@mattxwang]: https://github.com/mattxwang +[@pdmosses]: https://github.com/pdmosses +[@skullface]: https://github.com/skullface +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 + +### Roadmap + +In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs. + +We're also scoping out medium and long-term projects, and want to keep you in the loop. These include: + +- upgrading to Jekyll 4, and stopping support for Jekyll 3 +- versioned docs - issue [#728] +- improved accessibility - issues [#566], [#870] +- internationalization (i18n) - issue [#59] +- recursive/multi-level navigation - PR [#462] +- toggleable dark mode - issue [#234] + +as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome! + +[#728]: https://github.com/just-the-docs/just-the-docs/issues/728 +[#566]: https://github.com/just-the-docs/just-the-docs/issues/566 +[#870]: https://github.com/just-the-docs/just-the-docs/issues/870 +[#59]: https://github.com/just-the-docs/just-the-docs/issues/59 +[#462]: https://github.com/just-the-docs/just-the-docs/pull/462 +[#234]: https://github.com/just-the-docs/just-the-docs/issues/234 + +### Features + +* Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +* Added: custom favicon `_includes` by [@burner1024] in [#364] +* Added: set color for search input by [@pdmosses] in [#498] +* Added: search placeholder configuration by [@mattxwang] in [#613] +* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +* Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +* Added: mermaid.js support by [@nascosto] in [#857] +* Added: support for external navigation links by [@SPGoding] in [#876] +* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +* Fixed: nested task lists (#517) by [@pdmosses] in [#855] +* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +* Fixed: allow links to wrap by [@pdmosses] in [#905] +* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] + +[#578]: https://github.com/just-the-docs/just-the-docs/pull/578 +[#463]: https://github.com/just-the-docs/just-the-docs/pull/463 +[#448]: https://github.com/just-the-docs/just-the-docs/pull/448 +[#466]: https://github.com/just-the-docs/just-the-docs/pull/466 +[#477]: https://github.com/just-the-docs/just-the-docs/pull/477 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#496]: https://github.com/just-the-docs/just-the-docs/pull/496 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#494]: https://github.com/just-the-docs/just-the-docs/pull/494 +[#639]: https://github.com/just-the-docs/just-the-docs/pull/639 +[#544]: https://github.com/just-the-docs/just-the-docs/pull/544 +[#364]: https://github.com/just-the-docs/just-the-docs/pull/364 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#613]: https://github.com/just-the-docs/just-the-docs/pull/613 +[#726]: https://github.com/just-the-docs/just-the-docs/pull/726 +[#474]: https://github.com/just-the-docs/just-the-docs/pull/474 +[#829]: https://github.com/just-the-docs/just-the-docs/pull/829 +[#857]: https://github.com/just-the-docs/just-the-docs/pull/857 +[#876]: https://github.com/just-the-docs/just-the-docs/pull/876 +[#909]: https://github.com/just-the-docs/just-the-docs/pull/909 +[#519]: https://github.com/just-the-docs/just-the-docs/pull/519 +[#855]: https://github.com/just-the-docs/just-the-docs/pull/855 +[#686]: https://github.com/just-the-docs/just-the-docs/pull/686 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#846]: https://github.com/just-the-docs/just-the-docs/pull/846 +[#727]: https://github.com/just-the-docs/just-the-docs/pull/727 +[#889]: https://github.com/just-the-docs/just-the-docs/pull/889 +[#893]: https://github.com/just-the-docs/just-the-docs/pull/893 +[#905]: https://github.com/just-the-docs/just-the-docs/pull/905 +[#898]: https://github.com/just-the-docs/just-the-docs/pull/898 + +### Documentation + +* Added: docs on how to break an `ol` by [@pdmosses] in [#856] +* Added: docs for custom includes by [@nathanjessen] in [#806] +* Added: document caveat about variable dependencies by [@waldyrious] in [#555] +* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +* Fixed: spacing in toc example by [@henryiii] in [#835] +* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] + +[#856]: https://github.com/just-the-docs/just-the-docs/pull/856 +[#806]: https://github.com/just-the-docs/just-the-docs/pull/806 +[#555]: https://github.com/just-the-docs/just-the-docs/pull/555 +[#814]: https://github.com/just-the-docs/just-the-docs/pull/814 +[#778]: https://github.com/just-the-docs/just-the-docs/pull/778 +[#221]: https://github.com/just-the-docs/just-the-docs/pull/221 +[#782]: https://github.com/just-the-docs/just-the-docs/pull/782 +[#549]: https://github.com/just-the-docs/just-the-docs/pull/549 +[#554]: https://github.com/just-the-docs/just-the-docs/pull/554 +[#499]: https://github.com/just-the-docs/just-the-docs/pull/499 +[#473]: https://github.com/just-the-docs/just-the-docs/pull/473 +[#835]: https://github.com/just-the-docs/just-the-docs/pull/835 +[#891]: https://github.com/just-the-docs/just-the-docs/pull/891 +[#906]: https://github.com/just-the-docs/just-the-docs/pull/906 + +### Maintenance + +* Added: VScode devcontainer by [@max06] in [#783] +* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +* Updated: new repo path by [@pmarsceill] in [#775] +* Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +* Updated: README by [@pmarsceill] in [#777] +* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] + +[#783]: https://github.com/just-the-docs/just-the-docs/pull/783 +[#799]: https://github.com/just-the-docs/just-the-docs/pull/799 +[#797]: https://github.com/just-the-docs/just-the-docs/pull/797 +[#775]: https://github.com/just-the-docs/just-the-docs/pull/775 +[#776]: https://github.com/just-the-docs/just-the-docs/pull/776 +[#777]: https://github.com/just-the-docs/just-the-docs/pull/777 +[#790]: https://github.com/just-the-docs/just-the-docs/pull/790 +[#820]: https://github.com/just-the-docs/just-the-docs/pull/820 +[#821]: https://github.com/just-the-docs/just-the-docs/pull/821 + +### Dependencies + +* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627] +* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606] +* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641] +* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640] +* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511] +* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699] +* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766] +* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787] +* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809] +* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864] + +[#627]: https://github.com/just-the-docs/just-the-docs/pull/627 +[#606]: https://github.com/just-the-docs/just-the-docs/pull/606 +[#641]: https://github.com/just-the-docs/just-the-docs/pull/641 +[#640]: https://github.com/just-the-docs/just-the-docs/pull/640 +[#511]: https://github.com/just-the-docs/just-the-docs/pull/511 +[#699]: https://github.com/just-the-docs/just-the-docs/pull/699 +[#766]: https://github.com/just-the-docs/just-the-docs/pull/766 +[#787]: https://github.com/just-the-docs/just-the-docs/pull/787 +[#809]: https://github.com/just-the-docs/just-the-docs/pull/809 +[#864]: https://github.com/just-the-docs/just-the-docs/pull/864 + +### New Contributors + +* [@AdityaTiwari2102] made their first contribution in [#477] +* [@svrooij] made their first contribution in [#544] +* [@alexsegura] made their first contribution in [#519] +* [@burner1024] made their first contribution in [#364] +* [@JeffGuKang] made their first contribution in [#221] +* [@dougaitken] made their first contribution in [#782] +* [@max06] made their first contribution in [#783] +* [@sehilyi] made their first contribution in [#499] +* [@nathanjessen] made their first contribution in [#473] +* [@waldyrious] made their first contribution in [#549] +* [@MichelleBlanchette] made their first contribution in [#554] +* [@henryiii] made their first contribution in [#835] +* [@jmertic] made their first contribution in [#726] +* [@jacobhq] made their first contribution in [#846] +* [@UnclassedPenguin] made their first contribution in [#814] +* [@alyssais] made their first contribution in [#829] +* [@nascosto] made their first contribution in [#857] +* [@SPGoding] made their first contribution in [#876] +* [@iridazzle] made their first contribution in [#727] +* [@ivanskodje] made their first contribution in [#891] +* [@Eisverygoodletter] made their first contribution in [#893] + +[@AdityaTiwari2102]: https://github.com/AdityaTiwari2102 +[@svrooij]: https://github.com/svrooij +[@alexsegura]: https://github.com/alexsegura +[@burner1024]: https://github.com/burner1024 +[@JeffGuKang]: https://github.com/JeffGuKang +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 +[@sehilyi]: https://github.com/sehilyi +[@nathanjessen]: https://github.com/nathanjessen +[@waldyrious]: https://github.com/waldyrious +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@henryiii]: https://github.com/henryiii +[@jmertic]: https://github.com/jmertic +[@jacobhq]: https://github.com/jacobhq +[@UnclassedPenguin]: https://github.com/UnclassedPenguin +[@alyssais]: https://github.com/alyssais +[@nascosto]: https://github.com/nascosto +[@SPGoding]: https://github.com/SPGoding +[@iridazzle]: https://github.com/iridazzle +[@ivanskodje]: https://github.com/ivanskodje +[@Eisverygoodletter]: https://github.com/Eisverygoodletter + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1 + +[@pmarsceill]: https://github.com/pmarsceill + +## v0.3.3 + +### 🚀 Features + +- Add custom header and footer include files @CodeSandwich (#334) + +### 🐛 Bug Fixes + +- Limit the effect of `nav_exclude` to the main navigation @pdmosses (#443) +- Update normalize.scss @pdmosses (#444) +- Update code.scss @pdmosses (#445) +- Fix list alignment @pdmosses (#446) + +### 🧰 Maintenance + +- Bump stylelint-config-primer from 9.0.0 to 9.2.1 @dependabot-preview (#451) +- Bump stylelint from 13.6.1 to 13.7.2 @dependabot-preview (#440) +- Bump @primer/css from 15.1.0 to 15.2.0 @dependabot-preview (#436) +- Bump prettier from 2.1.1 to 2.1.2 @dependabot-preview (#429) + +## v0.3.2 + +### Changes + +- Safe page sorting @pdmosses (#411) +- v0.3.2 @pmarsceill (#388) + +### 🚀 Features + +- make font-sizes sass variables so they can be changed @pdebruic (#361) +- run the site locally inside docker container @fogfish (#398) +- Feature/doc collections @SgtSilvio (#379) +- Adjust dl layout @pdmosses (#401) + +### 🐛 Bug Fixes + +- Add site.gh_edit_source to "Edit this page on GitHub" link @mrfleap (#418) +- Inhibit text-transform for code in h4 @pdmosses (#404) +- Fix native font stack precedence issue on Windows systems. @hvianna (#331) +- Support for the linenos option on highlighted code @pdmosses (#375) +- Update anchor_headings.html @pdmosses (#399) +- Fix https @marksie1988 (#359) + +### 🧰 Maintenance + +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#427) +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#419) +- [Security] Bump lodash from 4.17.15 to 4.17.19 @dependabot-preview (#389) +- Bump @primer/css from 14.4.0 to 15.1.0 @dependabot-preview (#402) +- Bump lodash from 4.17.15 to 4.17.19 @dependabot (#384) +- Bump @primer/css from 14.4.0 to 15.0.0 @dependabot-preview (#371) + + +## v0.3.1 + +### Changes + +### 🐛 Bug Fixes + +- Improve accessibility by adding label to Anchor links. @mscoutermarsh (#376) + +### 🧰 Maintenance + +- Remove collapsible TOC on nav doc @pmarsceill (#368) +- Pdmosses collapsible toc @pmarsceill (#367) + + +## v0.3.0 + +### Changes + +- v0.2.9 @pmarsceill (#306) + +### 🚀 Features + +- Add print styles @pmarsceill (#362) +- Navigation improvements and search sections @SgtSilvio (#352) + +### 🐛 Bug Fixes + +- Remove constraint with jekyll 4.1.0 @PierrickMartos (#348) + +### 🧰 Maintenance + +- Bump version numbers @pmarsceill (#360) +- Bump stylelint from 13.3.3 to 13.6.1 @dependabot-preview (#343) +- Bump stylelint-config-prettier from 8.0.1 to 8.0.2 @dependabot-preview (#349) + + +## v0.2.9 + +### Bug fixes +- Horizontal Alignment #103 @pmarsceill +- Code snippet in headers do not inherit font size #140 @pmarsceill +- Fix duplicated title and description tags #294 @iefserge +- Update nav.html for handling nav_exclude #282 @blawqchain +- Fix duplicate entries in nav.html and default.html #239 @KasparEtter +- Don't show pages with no title (e.g. redirects in nav) https://github.com/pmarsceill/just-the-docs/pull/295/commits/672de29f2e332a9350af7237e4fb6693c848989e @SgtSilvio +- [SEARCH RAKE] Fix search generator #319 @RoiArthurB + +### Enhancements +- Improvement/custom themes #186 @SgtSilvio +- feat: adds "edit this page" and "page last modified" to footer #217 @malsf21 +- feat: adds option to open aux links in new tab #229 @malsf21 +- Default nav order #236 @pdmosses +- Enable IP anonymization in Google Analytics (GDPR) #250 @r-brown + +closes #240 #308 #266 #140 #103 + +## v0.2.8 + +### Bugfixes +- bugfix in search.rake #218 @tiaitsch85 + +### Dependency and security updates: + +- Update jekyll requirement from ~> 3.8.5 to >= 3.8.5, < 4.1.0 #197 @dependabot-preview +- Update rake requirement from ~> 12.3.1 to >= 12.3.1, < 13.1.0 #227 @dependabot-preview +- Bump stylelint-config-primer from 8.0.0 to 9.0.0 #247 @dependabot-preview +- Update bundler requirement from ~> 2.0.1 to ~> 2.1.4 #268 @dependabot-preview +- Bump @primer/css from 12.7.0 to 14.3.0 #296 @dependabot-preview + +### Operations + +- Update CI to test multiple versions of Jekyll +- Update CI to check the rake command that builds the search file + +fixes #291 #256 #293 #177 + +## v0.2.7 + +### Bugs fixed +- Anchor headings are now displayed on hover, not only on heading hover +- Deduplicated anchor heading svg +- If last page of `site.html_pages` was excluded from search, search json breaks +- Config variable should be `blanklines` not `blank_lines` for html compression +- `list-style-none` does not hide bullets on `ul` + +### Enhancements +- Summary for child pages appears in generated TOC +- Site logo configuration supported replacing title text with image +- Allow custom CSS overrides (new scss partial at the end of the cascade) separate from variable overrides. +- Configuration around search strings added to allow search for hyphenated words + +### Maintenance +- Update docs to suggest using index.md as section page filename +- Bump @primer/css from 12.6.0 to 12.7.0 +- Bump mixin-deep from 1.3.1 to 1.3.2 +- Bump stylelint-config-primer from 7.0.1 to 8.0.0 + +### PR included +- #98 by @stefanoborini Introduces the possibility for a summary in the table of contents +- #141 by @ghabs Fix trailing comma bug in search-data.json +- #153 by @jacobherrington Change button copy on theme preview +- #181 by @m3nu Recommend using index.md as parent page for sections +- #183 by @SgtSilvio Improve heading anchors +- #187 by @SgtSilvio Improvement/site logo +- #200 Bump mixin-deep from 1.3.1 to 1.3.2 +- #203 by @pdmosses Search config +- #205 by @pdmosses Fix blank_lines var to blanklines in config.yml +- #206 by @iamcarrico Allow for custom overrides by the user +- #208 Bump @primer/css from 12.6.0 to 12.7.0 +- #213 Bump mixin-deep from 1.3.1 to 1.3.2 +- #214 Bump stylelint-config-primer from 7.0.1 to 8.0.0 +- #215 Bump @primer/css from 12.6.0 to 12.7.0 + +## v0.2.6 + +### Bugs fixed +- Google Analytics tag has been updated #162 +- ~BaseURL has been modified #109~ Reverted -- seems the existing implementation worked +- Titles can now wrap fixes #106 + +### Enhancements +- Search now displays content preview #135 +- Custom footer content added #179 +- Now using GitHub Actions for CI #170 + +### Maintenance +- lunrjs upgraded #135 +- Nav generation is optimized #159 +- Stylelint upgrade #143 +- Stylelint config primer upgrade #149 +- Lodash upgrade #160 + +### PR included +~#109 by @daviddarnes - Fix baseurl link~ Reverted +#135 by @SgtSilvio - Upgrades lunr.js, improves search UI, adds heading anchors +#152 by @yavorg - Improves syntax highlighting for js readablity +#159 by @julienduchesne - Optimizes nav generation +#162 by @nergmada - Modifies the google analytics code to match the new tags used by GA + + +## v0.2.5 + +### Bugs fixed + +- Duplicate title tag when Jekyll SEO Plugin gem is used #125 #126 + +### Enhancements + +- Favicon support added #118 + +### Maintenance +- Bump stylelint-config-primer from 6.0.0 to 7.0.0 #123 +- Bump @primer/css from 12.2.3 to 12.3.1 #129 +- Add workflow to publish to GPR +- Fix workflow to publish to Ruby Gems + +## v0.2.4 + +### Bugs + +- #102 Remove unnecessary console.log() @JoeNyland +- #97 Import custom Sass variable overrides before default variables are defined @montchr and @ptvandi + +### Additions +- #117 Add links to docs for setting up GH pages locally @gnarea +- #95 Add SEO and 'lang' param for `_config` @gebeto + +## v0.2.3 + +### Enhancements +- Adds ability to use Google Analytics tracking by @pmarsceill + +### Bug fixes +- Fixes 404 error for "/assets/js//search-data.json" by @stephenedmondson +- Fixes #80 Single quotes in the string were unescaped and ruby attempted variable substitution of amp within it (which failed) by @novelistparty +- Fixes bug that would only show 2 or more search results (not one) by @ilivewithian +- Fixes a typo on the layout example by @woernfl +- Fixes #78 Page scroll position too far down on load by @pmarsceill +- Fixds ability to nest ul in ol without breaking style or counters + +### Dependency updates +- Bumps stylelint dependency from 9.9.0 to 9.10.1 + +## v0.2.2 + +- Bumps stylelint-config-primer to 3.0.1 #44 +- Bumps bundler req to 2.0.1 #61 +- Adds custom 404 page +- Excludes package-lock.json from jekyll build #47 +- Fixes keyboard scrolling / focus #48 +- Adds ARIA roles to navigation elements +- Adds support for optional page description metadata (if present in yaml front matter) +- Addresses some issues with search in #46 +- Option to hide TOC on parent pages if turned off in page's YAML front matter #30 +- Option to suppress an item from being indexed by search if present in page's YAML front matter #32 + +## v0.2.1 + +This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version. + +## v0.2.0 + +Adds: +- Dark mode via `color_scheme` parameter +- Ability to exclude a page from the main nav with `nav_exclude` parameter closes #21 +- Ability for create children of children pages (3 nav levels) closes #25 + +Changes: +- Permalink structure for tiered navigation has been updated +- Some colors have been updated for consistency / accessibility + +## v0.1.6 + +### Added + +- Support for task list styles #19 +- Configuration docs +- Configuration option to enable / disable search +- Normalize.scss dependency pulled into project #16 # + +### Fixed + +- Layout bug in navigation #17 + +## v0.1.5 + +Major changes: + +- Fixed bug where the rake task would fail when the assets/js directory didn't exist + +## v0.1.4 + +Major changes: +- Adds Rake as a runtime dependency +- Definition list styled +- Sidebar and support cleaned up for smaller screen support +- Updated some stale docs + +## v0.1.3 + +Major changes: +- Fix path problems, typos, and general clean-up for OSS. + +## v0.1.2 + +Fix paths when deployed to gh-pages + +## v0.1.1 + +Major updates: +- Adds search to mobile nav +- Pulls footer to bottom of the page on mobile (not hidden in nav) + +Minor updates: +- Cleans up h1 typography spacing diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a57ebc6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +patrick.marsceill@gmail.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..a499513 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM ruby:2.7 + +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +WORKDIR /usr/src/app + +COPY Gemfile just-the-docs.gemspec ./ +RUN gem install bundler && bundle install + +EXPOSE 4000 diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..76bd139 --- /dev/null +++ b/Gemfile @@ -0,0 +1,8 @@ +source "https://rubygems.org" +gemspec + +gem "jekyll-github-metadata", ">= 2.15" + +gem "jekyll-include-cache", group: :jekyll_plugins + +gem "html-proofer", "~> 5.0", :group => :development diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..e71b6d0 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,150 @@ +PATH + remote: . + specs: + just-the-docs (0.6.2) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + +GEM + remote: https://rubygems.org/ + specs: + Ascii85 (1.1.0) + addressable (2.8.4) + public_suffix (>= 2.0.2, < 6.0) + afm (0.2.2) + async (2.6.3) + console (~> 1.10) + fiber-annotation + io-event (~> 1.1) + timers (~> 4.1) + colorator (1.1.0) + concurrent-ruby (1.2.2) + console (1.23.2) + fiber-annotation + fiber-local + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + faraday (2.7.10) + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.15.5) + fiber-annotation (0.2.0) + fiber-local (1.0.0) + forwardable-extended (2.6.0) + google-protobuf (3.23.4-arm64-darwin) + google-protobuf (3.23.4-x86_64-linux) + hashery (2.1.2) + html-proofer (5.0.8) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + io-event (1.2.3) + jekyll (4.3.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-github-metadata (2.16.0) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + nokogiri (1.15.4-arm64-darwin) + racc (~> 1.4) + nokogiri (1.15.4-x86_64-linux) + racc (~> 1.4) + octokit (6.1.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + pdf-reader (2.11.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.0.3) + racc (1.7.1) + rainbow (3.1.1) + rake (13.0.6) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.6) + rouge (4.1.2) + ruby-rc4 (0.1.5) + ruby2_keywords (0.0.5) + safe_yaml (1.0.5) + sass-embedded (1.64.1-arm64-darwin) + google-protobuf (~> 3.23) + sass-embedded (1.64.1-x86_64-linux-gnu) + google-protobuf (~> 3.23) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + timers (4.3.5) + ttfunk (1.7.0) + typhoeus (1.4.0) + ethon (>= 0.9.0) + unicode-display_width (2.4.2) + webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.6.11) + +PLATFORMS + arm64-darwin + x86_64-linux + +DEPENDENCIES + bundler (>= 2.3.5) + html-proofer (~> 5.0) + jekyll-github-metadata (>= 2.15) + jekyll-include-cache + just-the-docs! + +BUNDLED WITH + 2.4.13 diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..9e81a6c --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Patrick Marsceill + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..f134c7f --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,521 @@ +--- +title: Migration and Upgrading +layout: default +--- + +# Migrating and Upgrading + +Summary +: A site that uses `just-the-docs` (as a theme or as a remote theme) automatically + switches to a new release, unless it is pinned to a previous version. + + This migration guide draws attention to: + + - changes that might break your site, + - features added in the latest release, and + - features that have become deprecated (and are likely to be removed in a future release). + +This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`. + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +{::options toc_levels="2..4" /} + +{: .warning } +> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your +> website is built using the current `main` branch of the theme, which may include +> changes made after the latest release; see the [CHANGELOG]. +> +> If your configuration states `theme: just_the_docs` and your `Gemfile` specifies +> `gem "just-the-docs"`, your website is always built using the latest release. + +{: .note } +> If you have cloned/forked and customised the theme repo, +> and pull the changes of a new release to your clone, +> you may need to resolve merge conflicts. + +[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %} + +## v0.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 ` + +{% else %} + +{% if site.mermaid.path %} + +{% else %} + +{% endif %} + + + +{% endif %} diff --git a/_includes/components/nav.html b/_includes/components/nav.html new file mode 100644 index 0000000..aa5af38 --- /dev/null +++ b/_includes/components/nav.html @@ -0,0 +1,75 @@ +{%- comment -%} + Include as: {%- include components/nav.html pages=pages -%} + Depends on: include.pages. + Results in: HTML for the navigation panel. + Includes: + sorted_pages.html + Overwrites: + nav_pages, first_level_pages, second_level_pages, third_level_pages, + node, children_list, child, grand_children_list, grand_child. +{%- endcomment -%} + +{%- assign nav_pages = include.pages + | where_exp: "item", "item.title != nil" + | where_exp: "item", "item.nav_exclude != true" -%} + +{%- include sorted_pages.html pages = nav_pages -%} + +{%- comment -%} + It might be more efficient to sort the pages at each level separately. +{%- endcomment -%} + +{%- assign first_level_pages = sorted_pages + | where_exp: "item", "item.parent == nil" -%} +{%- assign second_level_pages = sorted_pages + | where_exp: "item", "item.parent != nil" + | where_exp: "item", "item.grand_parent == nil" -%} +{%- assign third_level_pages = sorted_pages + | where_exp: "item", "item.grand_parent != nil" -%} + + diff --git a/_includes/components/search_footer.html b/_includes/components/search_footer.html new file mode 100644 index 0000000..d448fdb --- /dev/null +++ b/_includes/components/search_footer.html @@ -0,0 +1,7 @@ +{% if site.search.button %} + +{% endif %} + +
diff --git a/_includes/components/search_header.html b/_includes/components/search_header.html new file mode 100644 index 0000000..3562124 --- /dev/null +++ b/_includes/components/search_header.html @@ -0,0 +1,9 @@ +{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %} + + diff --git a/_includes/components/sidebar.html b/_includes/components/sidebar.html new file mode 100644 index 0000000..13c755b --- /dev/null +++ b/_includes/components/sidebar.html @@ -0,0 +1,32 @@ +{%- comment -%} + Include as: {%- include components/sidebar.html -%} + Depends on: page(?), site. + Results in: HTML for the side bar. + Includes: + title.html, components/site_nav.html, nav_footer_custom.html + Overwrites: + nav_footer_custom. + Should not be cached, because nav_footer_custom.html might depend on page. +{%- endcomment -%} + + diff --git a/_includes/components/site_nav.html b/_includes/components/site_nav.html new file mode 100644 index 0000000..12a9ffc --- /dev/null +++ b/_includes/components/site_nav.html @@ -0,0 +1,67 @@ +{%- comment -%} + Include as: {%- include_cached components/site_nav.html -%} + Depends on: site. + Results in: HTML for the site-nav. + Includes: + components/nav.html + Overwrites: + pages_top_size, collections_size, collection_entry, + collection_key, collection_value, collection. +{%- endcomment -%} + + diff --git a/_includes/css/activation.scss.liquid b/_includes/css/activation.scss.liquid new file mode 100644 index 0000000..a32392e --- /dev/null +++ b/_includes/css/activation.scss.liquid @@ -0,0 +1,281 @@ +{%- comment -%} + Include as: {%- include css/activation.scss.liquid -%} + Depends on: page, site. + Results in: page-dependent (non-nested) CSS rules for inclusion in a head style element, + which needs to be suppressed when JS is enabled. + Includes: + sorted_pages.html. + Overwrites: + activation_no_nav_link, activation_pages, activation_pages_top_size, activation_page, activation_title, + activation_first_level, activation_second_level, activation_third_level, + activation_first_level_reversed, activation_second_level_reversed, + activation_first_level_index, activation_second_level_index, activation_third_level_index, + activation_index, activation_collection_prefix, activation_other_collection_prefix. + Should not be cached, because it depends on page. + (For a site with only top-level pages, the rendering of this file is always empty. + This property could be detected, and used to reduce the build time for such sites.) +{%- endcomment -%} + +{%- comment -%} + The CSS rules in activation_no_nav_link are for use on pages excluded from the main navigation. + - The first rule ensures that no nav-link has a background image. + - The other two rules ensure that all folding collections are expanded. +{%- endcomment -%} + +{%- capture activation_no_nav_link %} +.site-nav ul li a { + background-image: none; +} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li > button svg { + transform: rotate(-90deg); +} +.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list { + display: block; +} +{%- endif %} +{% endcapture -%} + +{%- if page.title == nil or page.nav_exclude == true -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- assign activation_pages = site[page.collection] + | default: site.html_pages + | where_exp: "item", "item.title != nil" + | where_exp: "item", "item.nav_exclude != true" -%} + +{%- assign activation_first_level_index = nil -%} +{%- assign activation_second_level_index = nil -%} +{%- assign activation_third_level_index = nil -%} +{%- assign activation_first_level_reversed = nil -%} +{%- assign activation_second_level_reversed = nil -%} + +{%- comment -%} + The generated CSS depends on the position of the current page in each level in + the navigation. +{%- endcomment -%} + +{%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%} +{%- assign activation_first_level = activation_pages + | where_exp: "item", "item.parent == nil" -%} +{%- include sorted_pages.html pages = activation_first_level -%} +{%- for activation_page in sorted_pages -%} + {%- if activation_page.title == activation_title -%} + {%- assign activation_first_level_index = forloop.index -%} + {%- assign activation_first_level_reversed = activation_page.child_nav_order -%} + {%- break -%} + {%- endif -%} +{%- endfor -%} + +{%- if activation_first_level_index == nil -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- if page.grand_parent -%} + {%- assign activation_title = page.parent -%} + {%- assign activation_second_level = activation_pages + | where_exp: "item", "item.grand_parent == nil" + | where_exp: "item", "item.parent == page.grand_parent" -%} +{%- elsif page.parent -%} + {%- assign activation_title = page.title -%} + {%- assign activation_second_level = activation_pages + | where_exp: "item", "item.grand_parent == nil" + | where_exp: "item", "item.parent == page.parent" -%} +{%- endif -%} +{%- if page.parent -%} + {%- include sorted_pages.html pages = activation_second_level -%} + {%- for activation_page in sorted_pages -%} + {%- if activation_page.title == activation_title -%} + {%- assign activation_second_level_index = forloop.index -%} + {%- assign activation_second_level_reversed = activation_page.child_nav_order -%} + {%- if activation_first_level_reversed -%} + {%- assign activation_second_level_index = sorted_pages | size | plus: 1 | minus: activation_second_level_index -%} + {%- endif -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} +{%- endif -%} + +{%- if page.grand_parent -%} + {%- assign activation_third_level = activation_pages + | where_exp: "item", "item.parent == page.parent" + | where_exp: "item", "item.grand_parent == page.grand_parent" -%} + {%- include sorted_pages.html pages = activation_third_level -%} + {%- assign activation_third_level = sorted_pages -%} + {%- for activation_page in sorted_pages -%} + {%- if activation_page.title == page.title -%} + {%- assign activation_third_level_index = forloop.index -%} + {%- if activation_second_level_reversed -%} + {%- assign activation_third_level_index = sorted_pages | size | plus: 1 | minus: activation_third_level_index -%} + {%- endif -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} +{%- endif -%} + +{%- if activation_second_level_index == nil and activation_third_level_index -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- comment -%} + The site-nav is: + - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages + - an optional ul.nav-list with li.nav-list-item.externals + - any number of just-the-docs.collections + + A non-foldable collection is: + - a div.nav-category with the collection name, followed by: + - a ul.nav-list with li.nav-list-items for its top-level pages + + A foldable collection is: + - a ul.nav-list.nav-category-list with a single li.nav-list-item containing: + - an optional button with the expander svg + - a div.nav-category with the collection name + - a ul.nav-list with li.nav-list-items for its top-level pages + + The generated CSS uses: + - activation_collection_prefix, to select the site-nav > ul.nav-list for the page + - activation_other_collection_prefix, to select all the other site-nav > ul.nav-lists +{%- endcomment -%} + +{%- if page.collection == nil -%} + + {%- capture activation_collection_prefix -%} + .site-nav > ul.nav-list:first-child + {%- endcapture -%} + + {%- capture activation_other_collection_prefix -%} + .site-nav > ul.nav-list:not(:first-child) + {%- endcapture -%} + +{%- else -%} + + {%- for activation_collection in site.just_the_docs.collections -%} + {%- if activation_collection[0] == page.collection -%} + {%- assign activation_index = forloop.index -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} + + {%- assign activation_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 activation_pages_top_size > 0 -%} + {%- assign activation_index = activation_index | plus: 1 -%} + {%- endif -%} + + {%- if site.nav_external_links -%} + {%- assign activation_index = activation_index | plus: 1 -%} + {%- endif -%} + + {%- capture activation_collection_prefix -%} + .site-nav > ul:nth-of-type({{ activation_index }}) + {%- if site.just_the_docs.collections[page.collection].nav_fold %} > li > ul + {%- endif -%} + {%- endcapture -%} + + {%- capture activation_other_collection_prefix -%} + .site-nav > ul:not(:nth-of-type({{ activation_index }})) + {%- endcapture -%} + +{%- endif -%} + +{%- comment -%} + The required background image of the link to the current page may involve SCSS. + To avoid page-dependent SCSS, all nav links initially have that background image. + The following rule removes the image from the links to all parents, siblings, + and children of the current page. +{%- endcomment %} + +{% if activation_third_level_index -%} + +{{ activation_collection_prefix }} > li > a, +{{ activation_collection_prefix }} > li > ul > li > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ activation_third_level_index }})) > a { + background-image: none; +} + +{%- elsif activation_second_level_index -%} + +{{ activation_collection_prefix }} > li > a, +{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ activation_second_level_index }})) > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li > a { + background-image: none; +} + +{%- else -%} + +{{ activation_collection_prefix }} > li:not(:nth-child({{ activation_first_level_index }})) > a, +{{ activation_collection_prefix }} > li > ul > li > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li > a { + background-image: none; +} + +{%- endif %} + +{%- comment -%} + The following rule removes the image from the links to pages in other collections. +{%- endcomment %} + +{{ activation_other_collection_prefix }} a, +.site-nav li.external a { + background-image: none; +} + +{%- comment -%} + The following rule styles the link to the current page. +{%- endcomment %} + +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) +{%- if activation_second_level_index %} > ul > li:nth-child({{ activation_second_level_index }}) +{%- if activation_third_level_index %} > ul > li:nth-child({{ activation_third_level_index }}) +{%- endif -%} +{%- endif %} > a { + font-weight: 600; + text-decoration: none; +} + +{%- comment -%} + The following rules unfold all collections, and display the links to any children + of the current page. + + To avoid dependence on the SCSS variable nav-list-expander-right, the direction + of the rotation of the expander icon is fixed, and corresponds to the appearance + when nav-list-expander-right is true. This results in a minor visual difference + between the appearance of active expander icons when JS is enabled/disabled and + nav-list-expander-right is false, which seems unavoidable. +{%- endcomment %} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li > button svg, +{% endif -%} +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > button svg +{%- if activation_second_level_index -%}, +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > ul > li:nth-child({{ activation_second_level_index }}) > button svg +{%- endif %} { + transform: rotate(-90deg); +} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list, +{% endif -%} +{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list +{%- if activation_second_level_index %}, +{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list > li.nav-list-item:nth-child({{ activation_second_level_index }}) > ul.nav-list +{%- endif %} { + display: block; +} + +{%- endif -%} +{%- endif -%} +{%- endif -%} diff --git a/_includes/css/callouts.scss.liquid b/_includes/css/callouts.scss.liquid new file mode 100644 index 0000000..e99600e --- /dev/null +++ b/_includes/css/callouts.scss.liquid @@ -0,0 +1,93 @@ +{%- comment -%} + {% include css/callouts.scss.liquid color_scheme = string %} + produces SCSS for all the callouts in site.callouts. For the "dark" + color scheme, the levels of the text and background colors are reversed. +{%- endcomment -%} + +{%- assign callout_background_hue = "000" -%} +{%- assign callout_color_hue = "300" -%} +{%- if site.callouts_level == "loud" or include.color_scheme == "dark" and site.callouts_level != "quiet" -%} + {%- assign callout_background_hue = "300" -%} + {%- assign callout_color_hue = "000" -%} +{%- endif -%} + +div.opaque { + background-color: $body-background-color; +} + +{%- for callout in site.callouts %} + +{%- assign callout_opacity = callout[1].opacity | default: site.callouts_opacity | default: 0.2 -%} + +p.{{ callout[0] }}, blockquote.{{ callout[0] }} { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + {% if callout[1].title %} + &::before { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + content: "{{ callout[1].title }}"; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } + {% endif %} + > .{{ callout[0] }}-title { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +p.{{ callout[0] }}-title, blockquote.{{ callout[0] }}-title { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + > p:first-child { + margin-top: 0; + margin-bottom: 0; + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +blockquote.{{ callout[0] }} { + margin-left: 0; + margin-right: 0; + + > p:first-child { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +blockquote.{{ callout[0] }}-title { + margin-left: 0; + margin-right: 0; + + > p:nth-child(2) { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +{% endfor -%} diff --git a/_includes/css/custom.scss.liquid b/_includes/css/custom.scss.liquid new file mode 100644 index 0000000..2ad1576 --- /dev/null +++ b/_includes/css/custom.scss.liquid @@ -0,0 +1 @@ +@import "./custom/custom"; diff --git a/_includes/css/just-the-docs.scss.liquid b/_includes/css/just-the-docs.scss.liquid new file mode 100644 index 0000000..2eb480d --- /dev/null +++ b/_includes/css/just-the-docs.scss.liquid @@ -0,0 +1,12 @@ +{% if site.logo %} +$logo: "{{ site.logo | relative_url }}"; +{% endif %} +@import "./support/support"; +@import "./custom/setup"; +@import "./color_schemes/light"; +{% unless include.color_scheme == "light" %} +@import "./color_schemes/{{ include.color_scheme }}"; +{% endunless %} +@import "./modules"; +{% include css/callouts.scss.liquid color_scheme = include.color_scheme %} +{% include css/custom.scss.liquid %} diff --git a/_includes/favicon.html b/_includes/favicon.html new file mode 100644 index 0000000..7d2a53d --- /dev/null +++ b/_includes/favicon.html @@ -0,0 +1,23 @@ +{%- comment -%} + Include as: {%- include_cached favicon.html -%} + Depends on: site.static_files. + Results in: HTML for a link to an existing `favicon.ico` file. + Overwrites: + file. + + The endoflife.date site has 226 pages and 3410 static files. @marcwrobel pointed + out that the time taken by evaluating the code in this file on every page when + building that site was significant, and suggested making it optional. As it is + page-independent, it can easily be cached. Doing that reduced the time taken by + rendering `_includes/head.html` from 15.294s to 10.760s, thereby reducing the + total build time from 26.074s to 21.656s -- a saving of about 17%. +{%- endcomment -%} + +{% 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 %} diff --git a/_includes/fix_linenos.html b/_includes/fix_linenos.html new file mode 100644 index 0000000..6243fb0 --- /dev/null +++ b/_includes/fix_linenos.html @@ -0,0 +1,65 @@ +{%- comment -%} +This file can be used to fix the HTML produced by Jekyll for highlighted +code with line numbers. + +It works with `{% highlight some_language linenos %}...{% endhighlight %}` +and with the Kramdown option to add line numbers to fenced code. + +The implementation was derived from the workaround provided by +Dmitry Hrabrov (DeXP) at +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901 + +EXPLANATION + +The HTML produced by Rouge highlighting with lie numbers is of the form +`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML +with `pre`. This wrapping is not only unnecessary, but also transforms +the conforming HTML produced by Rouge to non-conforming HTML, which +results in HTML validation error reports. + +The fix removes the outer `pre` tags whenever they contain the pattern +``. + +Apart from avoiding HTML validation errors, the fix allows the use of +the [Jekyll layout for compressing HTML](http://jch.penibelst.de), +which relies on `pre` tags not being nested, according to +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 + +USAGE + +(Any names can be used for `some_var` and `some_language`.) + +{% capture some_var %} +{% highlight some_language linenos %} +Some code +{% endhighlight %} +{% endcapture %} +{% include fix_linenos.html code=some_var %} + +For code fences: + +{% capture some_var %} +```some_language +Some code +``` +{% endcapture %} +{% assign some_var = some_var | markdownify %} +{% include fix_linenos.html code=some_var %} + +CAVEATS + +The above does not work when `Some code` happens to contain the matched string +`
`. + +The use of this file overwrites the variable `fix_linenos_code` with `nil`. + +{%- endcomment -%} + +{% assign fix_linenos_code = include.code %} +{% if fix_linenos_code contains '
' %} + {% assign fix_linenos_code = fix_linenos_code | replace: '
', '
' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "
", "" %} +{% endif %} +{{ fix_linenos_code }} +{% assign fix_linenos_code = nil %} diff --git a/_includes/footer_custom.html b/_includes/footer_custom.html new file mode 100644 index 0000000..64e08c2 --- /dev/null +++ b/_includes/footer_custom.html @@ -0,0 +1,3 @@ +{%- if site.footer_content -%} +

{{ site.footer_content }}

+{%- endif -%} diff --git a/_includes/head.html b/_includes/head.html new file mode 100644 index 0000000..6cd1d52 --- /dev/null +++ b/_includes/head.html @@ -0,0 +1,53 @@ +{%- comment -%} + Include as: {%- include head.html -%} + Depends on: site.ga_tracking, site.ga_tracking_anonymize_ip, + site.search_enabled, site.static_files, site.favicon_ico. + Results in: HTML for the head element. + Includes: + css/activation.scss.liquid, head_custom.html. + Overwrites: + ga_tracking_ids, ga_property, file, favicon. + Should not be cached, because included files depend on page. +{%- endcomment -%} + + + + + + + + + + + + {% if site.ga_tracking != nil %} + {% assign ga_tracking_ids = site.ga_tracking | split: "," %} + + + {% endif %} + + {% if site.search_enabled != false %} + + {% endif %} + + + + + + {% include_cached favicon.html %} + + {% seo %} + + {% include head_custom.html %} + + diff --git a/_includes/head_custom.html b/_includes/head_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_includes/header_custom.html b/_includes/header_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_includes/icons/code_copy.html b/_includes/icons/code_copy.html new file mode 100644 index 0000000..fb6421f --- /dev/null +++ b/_includes/icons/code_copy.html @@ -0,0 +1,15 @@ + + + Copy + + + + + + + Copied + + + + + diff --git a/_includes/icons/document.html b/_includes/icons/document.html new file mode 100644 index 0000000..c09e8a5 --- /dev/null +++ b/_includes/icons/document.html @@ -0,0 +1,6 @@ + + Document + + + + diff --git a/_includes/icons/expand.html b/_includes/icons/expand.html new file mode 100644 index 0000000..79921a5 --- /dev/null +++ b/_includes/icons/expand.html @@ -0,0 +1,6 @@ + + Expand + + + + diff --git a/_includes/icons/external_link.html b/_includes/icons/external_link.html new file mode 100644 index 0000000..1592be6 --- /dev/null +++ b/_includes/icons/external_link.html @@ -0,0 +1,5 @@ + + + (external link) + + diff --git a/_includes/icons/icons.html b/_includes/icons/icons.html new file mode 100644 index 0000000..007a495 --- /dev/null +++ b/_includes/icons/icons.html @@ -0,0 +1,13 @@ + + {% include icons/link.html %} + {% include icons/menu.html %} + {% include icons/expand.html %} + {% include icons/external_link.html %} + {% if site.search_enabled != false %} + {% include icons/document.html %} + {% include icons/search.html %} + {% endif %} + {% if site.enable_copy_code_button != false %} + {% include icons/code_copy.html %} + {% endif %} + diff --git a/_includes/icons/link.html b/_includes/icons/link.html new file mode 100644 index 0000000..de24be7 --- /dev/null +++ b/_includes/icons/link.html @@ -0,0 +1,6 @@ + + Link + + + + diff --git a/_includes/icons/menu.html b/_includes/icons/menu.html new file mode 100644 index 0000000..d256575 --- /dev/null +++ b/_includes/icons/menu.html @@ -0,0 +1,6 @@ + + Menu + + + + diff --git a/_includes/icons/search.html b/_includes/icons/search.html new file mode 100644 index 0000000..8f72c6a --- /dev/null +++ b/_includes/icons/search.html @@ -0,0 +1,6 @@ + + Search + + + + diff --git a/_includes/js/custom.js b/_includes/js/custom.js new file mode 100644 index 0000000..e69de29 diff --git a/_includes/lunr/custom-data.json b/_includes/lunr/custom-data.json new file mode 100644 index 0000000..e69de29 diff --git a/_includes/lunr/custom-index.js b/_includes/lunr/custom-index.js new file mode 100644 index 0000000..e69de29 diff --git a/_includes/mermaid_config.js b/_includes/mermaid_config.js new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/_includes/mermaid_config.js @@ -0,0 +1 @@ +{} diff --git a/_includes/nav_footer_custom.html b/_includes/nav_footer_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_includes/search_placeholder_custom.html b/_includes/search_placeholder_custom.html new file mode 100644 index 0000000..2885058 --- /dev/null +++ b/_includes/search_placeholder_custom.html @@ -0,0 +1 @@ +Search {{site.title}} 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 new file mode 100644 index 0000000..8f65336 --- /dev/null +++ b/_includes/title.html @@ -0,0 +1,5 @@ +{% if site.logo %} + +{% else %} + {{ site.title }} +{% endif %} diff --git a/_includes/toc_heading_custom.html b/_includes/toc_heading_custom.html new file mode 100644 index 0000000..82a7700 --- /dev/null +++ b/_includes/toc_heading_custom.html @@ -0,0 +1 @@ +

Table of contents

diff --git a/_layouts/about.html b/_layouts/about.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_layouts/about.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..923c1c1 --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,41 @@ +--- +layout: table_wrappers +--- + + + + +{% include head.html %} + + Skip to main content + {% include icons/icons.html %} + {% 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 %} + {% endif %} +
+ {% include components/footer.html %} +
+
+ {% if site.search_enabled != false %} + {% include components/search_footer.html %} + {% endif %} +
+ + {% if site.mermaid %} + {% include components/mermaid.html %} + {% endif %} + + diff --git a/_layouts/home.html b/_layouts/home.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_layouts/home.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_layouts/minimal.html b/_layouts/minimal.html new file mode 100644 index 0000000..b12c5db --- /dev/null +++ b/_layouts/minimal.html @@ -0,0 +1,34 @@ +--- +layout: table_wrappers +--- + + + + +{% include head.html %} + + Skip to main content + {% include icons/icons.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 %} + {% endif %} + + {% include components/footer.html %} + +
+
+ + {% if site.mermaid %} + {% include components/mermaid.html %} + {% endif %} + + diff --git a/_layouts/page.html b/_layouts/page.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_layouts/page.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_layouts/post.html b/_layouts/post.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_layouts/post.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_layouts/table_wrappers.html b/_layouts/table_wrappers.html new file mode 100644 index 0000000..3f8f226 --- /dev/null +++ b/_layouts/table_wrappers.html @@ -0,0 +1,7 @@ +--- +layout: vendor/compress +--- + +{% assign content_ = content | replace: '', '
' %} +{{ content_ }} diff --git a/_sass/404.html b/_sass/404.html new file mode 100644 index 0000000..a2d250a --- /dev/null +++ b/_sass/404.html @@ -0,0 +1,11 @@ +--- +layout: default +title: 404 +permalink: /404 +nav_exclude: true +search_exclude: true +--- + +

Page not found

+ +

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

diff --git a/_sass/CHANGELOG.md b/_sass/CHANGELOG.md new file mode 100644 index 0000000..9dd0a57 --- /dev/null +++ b/_sass/CHANGELOG.md @@ -0,0 +1,1670 @@ +--- +title: CHANGELOG +layout: default +--- + +# CHANGELOG + +All notable user-facing changes to this project are documented in this file. + +{: .highlight } +The project underwent a major maintenance shift in March 2022. + +## HEAD + +{: .note } +This website is built from the `HEAD` of the `main` branch of the theme repository. + +Code changes to `main` that are *not* in the latest release: + +- N/A + +## Release v0.7.0 + +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 + +Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`. + +We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Migrating to `v0.5.0` + +**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves. + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.5.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.0" +``` + +To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag. + +### Bugfixes + +- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209] +- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208] +- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190] +- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107] +- Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0) + +[#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107 +[#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187 +[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190 +[#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208 +[#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209 + +## Release v0.4.2 + +Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.com/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.2" +``` + +To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag. + +### Bugfixes + +- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166] +- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173] +- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184] +- Removed: unused dark syntax themes by [@mattxwang] in [#1192] + +### Documentation + +- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2) + +[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166 +[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173 +[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182 +[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184 +[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192 + +## Release v0.4.1 + +Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.1" +``` + +To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag. + +### Bugfixes + +- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165] +- Fixed: AsciiDoc code block styling by [@flyx] in [#1168] +- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177] +- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167] + +### Documentation + +- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108] + +### New Contributors + +- [@flyx] made their first contribution in [#1168] +- [@Dima-369] made their first contribution in [#1177] + +[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108 +[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165 +[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167 +[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168 +[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177 + +[@flyx]: https://github.com/flyx +[@Dima-369]: https://github.com/Dima-369 + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1) + +## Release v0.4.0 + +We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme. + +### Brief Overview - Highlighted Changes + +`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes: + +- better support for dark theme: dark highlighting, search input color +- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content +- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library +- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets +- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links) +- major improvements to nav generation efficiency and robustness +- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content) +- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature) +- [new custom includes](https://just-the-docs.com/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices +- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more! +- more documentation for [custom includes](https://just-the-docs.com/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.com/MIGRATION/) + +*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.* + +### Using Release `v0.4.0` + +Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0" +``` + +If you would prefer to not upgrade, you can enforce that explicitly: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Migration Guide and Strategies + +We've developed a new [migration guide](https://just-the-docs.com/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site. + +**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes. + +Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release. + +For support with migrating to `v0.4.0`, [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Roadmap (What's Next?) + +Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future! + +Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release. + +For version `v0.5`, our roadmap includes: + +- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences +- better GDPR compliance for analytics +- multi-level/recursive navigation (unlimited hierarchy of child pages) + +In future versions, we also plan on: + +- adding better dark theme defaults +- adding better internationalization support +- exploring offline PDF generation +- improving accessibility within the theme +- improving search functionality +- refactoring and improving the robustness of our codebase + +Have ideas for what's next, or want to get involved? [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! We're looking for more contributors and maintainers to help us develop the theme. + +### New Features + +- Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +- Added: custom favicon `_includes` by [@burner1024] in [#364] +- Added: set color for search input by [@pdmosses] in [#498] +- Added: search placeholder configuration by [@mattxwang] in [#613] +- Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +- Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +- Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +- Added: mermaid.js support by [@nascosto] in [#857] +- Added: support for external navigation links by [@SPGoding] in [#876] +- Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes + +- Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +- Fixed: nested task lists (#517) by [@pdmosses] in [#855] +- Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +- Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +- Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +- Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +- Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +- Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +- Fixed: allow links to wrap by [@pdmosses] in [#905] +- Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Maintenance + +- Added: VScode devcontainer by [@max06] in [#783] +- Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +- Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +- Updated: new repo path by [@pmarsceill] in [#775] +- Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +- Updated: README by [@pmarsceill] in [#777] +- Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +- Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +- Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] +- Deleted: unused script directory by [@mattxwang] in [#937] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Documentation + +- Added: docs on how to break an `ol` by [@pdmosses] in [#856] +- Added: docs for custom includes by [@nathanjessen] in [#806] +- Added: document caveat about variable dependencies by [@waldyrious] in [#555] +- Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Added: migration guide by [@pdmosses] in [#1059] +- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138] +- Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +- Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +- Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +- Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +- Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +- Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +- Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +- Fixed: spacing in toc example by [@henryiii] in [#835] +- Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +- Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Fixed: typo in changelog links [@koppor] in [#1000] +- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130] +- Fixed: broken relative page links by [@mattxwang] in [#1106] +- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Updated: `README` demo video by [@codewithfan] in [#1097] + +### New Contributors + +- [@AdityaTiwari2102] made their first contribution in [#477] +- [@svrooij] made their first contribution in [#544] +- [@alexsegura] made their first contribution in [#519] +- [@burner1024] made their first contribution in [#364] +- [@JeffGuKang] made their first contribution in [#221] +- [@dougaitken] made their first contribution in [#782] +- [@max06] made their first contribution in [#783] +- [@sehilyi] made their first contribution in [#499] +- [@nathanjessen] made their first contribution in [#473] +- [@waldyrious] made their first contribution in [#549] +- [@MichelleBlanchette] made their first contribution in [#554] +- [@henryiii] made their first contribution in [#835] +- [@jmertic] made their first contribution in [#726] +- [@jacobhq] made their first contribution in [#846] +- [@UnclassedPenguin] made their first contribution in [#814] +- [@alyssais] made their first contribution in [#829] +- [@nascosto] made their first contribution in [#857] +- [@SPGoding] made their first contribution in [#876] +- [@iridazzle] made their first contribution in [#727] +- [@ivanskodje] made their first contribution in [#891] +- [@Eisverygoodletter] made their first contribution in [#893] +- [@robinpokorny] made their first contribution in [#940] +- [@olgarithms] made their first contribution in [#951] +- [@manuelhenke] made their first contribution in [#941] +- [@JPrevost] made their first contribution in [#950] +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +## Pre-release v0.4.0.rc5 + +Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release. + +This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), `lunr` indexing, and loading `mermaid` locally. In addition, it fixes bugs introduced in `.rc4`: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from `v0.3.3`. + +### Trying out pre-release `v0.4.0.rc5` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc5" +``` + +By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes and Maintenance + +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Docs + +- Docs: add a migration guide by [@pdmosses] in [#1059] +- Docs: update `README` demo video by [@codewithfan] in [#1097] +- Docs: update "View Typography Utilities" link by [@agabrys] in [#1130] +- Docs: fix broken relative page links by [@mattxwang] in [#1106] +- Docs: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Docs: label new features introduced in `v0.4` by [@mattxwang] in [#1138] + +### New Contributors + +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +[#1059]: https://github.com/just-the-docs/just-the-docs/pull/1059 +[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068 +[#1097]: https://github.com/just-the-docs/just-the-docs/pull/1097 +[#1106]: https://github.com/just-the-docs/just-the-docs/pull/1106 +[#1123]: https://github.com/just-the-docs/just-the-docs/pull/1123 +[#1124]: https://github.com/just-the-docs/just-the-docs/pull/1124 +[#1128]: https://github.com/just-the-docs/just-the-docs/pull/1128 +[#1130]: https://github.com/just-the-docs/just-the-docs/pull/1130 +[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135 +[#1138]: https://github.com/just-the-docs/just-the-docs/pull/1138 +[#1139]: https://github.com/just-the-docs/just-the-docs/pull/1139 +[#1142]: https://github.com/just-the-docs/just-the-docs/pull/1142 +[#1143]: https://github.com/just-the-docs/just-the-docs/pull/1143 +[#1153]: https://github.com/just-the-docs/just-the-docs/pull/1153 + +[@agabrys]: https://github.com/agabrys +[@codewithfan]: https://github.com/codewithfan +[@diablodale]: https://github.com/diablodale +[@fabrik42]: https://github.com/fabrik42 +[@kevinlin1]: https://github.com/kevinlin1 +[@EricFromCanada]: https://github.com/EricFromCanada +[@m-r-mccormick]: https://github.com/m-r-mccormick + +## Pre-release v0.4.0.rc4 + +Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. **We aim to re-release this as `v0.4.0`, with only few changes**. + +Notable new additions include: + +- modular site components, which split up the site into smaller reusable components; advanced theme users can then remix layouts quickly without duplication +- a "copy code" button to code blocks +- fixing bugs in generated TOCs and navigation from previous prereleases +- various cleanups of CSS and HTML markup + +The roadmap to `v0.4.0` is small. We are only looking to: + +- finish a migration guide, so users can easily upgrade from `v0.3.3` to `v0.4.0` +- fix one last bug relating to callouts and custom colors +- fix any new bugs introduced by this pre-release + +Have any questions, thoughts, or concerns? We'd love to hear from you! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc4` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc4" +``` + +By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] + +### Bugfixes and Maintenance + +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Docs + +- Docs: fix typo in changelog links [@koppor] in [#1000] +- Docs: update homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Docs: update README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Docs: fix two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Docs: Add warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Docs: remove Google Analytics on main site by [@mattxwang] in [#1113] + +### New Contributors + +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4 + +[#945]: https://github.com/just-the-docs/just-the-docs/pull/945 +[#999]: https://github.com/just-the-docs/just-the-docs/pull/999 +[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000 +[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001 +[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010 +[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015 +[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018 +[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019 +[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021 +[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027 +[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029 +[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040 +[#1058]: https://github.com/just-the-docs/just-the-docs/pull/1058 +[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061 +[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065 +[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071 +[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074 +[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076 +[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077 +[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090 +[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091 +[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092 +[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095 +[#1096]: https://github.com/just-the-docs/just-the-docs/pull/1096 +[#1102]: https://github.com/just-the-docs/just-the-docs/pull/1102 +[#1104]: https://github.com/just-the-docs/just-the-docs/pull/1104 +[#1110]: https://github.com/just-the-docs/just-the-docs/pull/1110 +[#1113]: https://github.com/just-the-docs/just-the-docs/pull/1113 + +[@captn3m0]: https://github.com/captn3m0 +[@deseo]: https://github.com/deseo +[@koppor]: https://github.com/koppor +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@simonebortolin]: https://github.com/simonebortolin +[@SConaway]: https://github.com/SConaway +[@Tom-Brouwer]: https://github.com/Tom-Brouwer + +## Pre-release v0.4.0.rc3 + +Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`. + +In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease. + +We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work! + +### Trying out pre-release `v0.4.0.rc3` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc3" +``` + +By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +Broadly, this prerelease is feature-light! + +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] + +### Bugfixes and Experimental Features + +*Note*: experimental nav optimization may be unstable. Please give us feedback! + +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] + +[#965]: https://github.com/just-the-docs/just-the-docs/pull/965 +[#960]: https://github.com/just-the-docs/just-the-docs/pull/960 +[#962]: https://github.com/just-the-docs/just-the-docs/pull/962 +[#964]: https://github.com/just-the-docs/just-the-docs/pull/964 +[#967]: https://github.com/just-the-docs/just-the-docs/pull/967 +[#974]: https://github.com/just-the-docs/just-the-docs/pull/974 +[#980]: https://github.com/just-the-docs/just-the-docs/pull/980 +[#985]: https://github.com/just-the-docs/just-the-docs/pull/985 +[#986]: https://github.com/just-the-docs/just-the-docs/pull/986 +[#992]: https://github.com/just-the-docs/just-the-docs/pull/992 + +[@henryiii]: https://github.com/henryiii + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3 + +## Pre-release v0.4.0.rc2 + +{: .warning } +This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`! + +Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight: + +- significant improvement on build time of navigation panel by [@pdmosses] + - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds! +- improved accessibility features led by [@JPrevost] +- more docs! + +The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know! + +### Trying out pre-release `v0.4.0.rc2` + +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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc2" +``` + +By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] + +[#950]: https://github.com/just-the-docs/just-the-docs/pull/950 +[#944]: https://github.com/just-the-docs/just-the-docs/pull/944 +[#939]: https://github.com/just-the-docs/just-the-docs/pull/939 +[#949]: https://github.com/just-the-docs/just-the-docs/pull/949 +[#941]: https://github.com/just-the-docs/just-the-docs/pull/941 +[#956]: https://github.com/just-the-docs/just-the-docs/pull/956 + +[@alyssais]: https://github.com/alyssais + +### Documentation and Maintenance + +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Deleted: unused script directory by [@mattxwang] in [#937] + +[#935]: https://github.com/just-the-docs/just-the-docs/pull/935 +[#940]: https://github.com/just-the-docs/just-the-docs/pull/940 +[#951]: https://github.com/just-the-docs/just-the-docs/pull/951 +[#955]: https://github.com/just-the-docs/just-the-docs/pull/955 +[#937]: https://github.com/just-the-docs/just-the-docs/pull/937 + +### New Contributors + +* [@robinpokorny] made their first contribution in [#940] +* [@olgarithms] made their first contribution in [#951] +* [@manuelhenke] made their first contribution in [#941] +* [@JPrevost] made their first contribution in [#950] + +[@robinpokorny]: https://github.com/robinpokorny +[@olgarithms]: https://github.com/olgarithms +[@manuelhenke]: https://github.com/manuelhenke +[@JPrevost]: https://github.com/JPrevost + +## Pre-release v0.4.0.rc1 + +### We're back! + +Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include: + +- The new callouts component +- Allowing pages and collections to coexist on the navigation pane +- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements +- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting +- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color +- More documentation, especially on using custom includes +- Updating core dependencies to stable Ruby versions +- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way! + +We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc1` + +Due to the massive scope of these changes, we're making `v0.4.0.rc1` 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: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc1" +``` + +### Staying on `v0.3.3` + +If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to `v0.3.3` (i.e. by a `Gemfile.lock` or in `remote_theme`, then there's nothing you need to do. + +If you have not pinned your theme version, you should either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +{: .warning } +Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`. + +### Maintenance + +Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks! + +The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time! + +[@mattxwang]: https://github.com/mattxwang +[@pdmosses]: https://github.com/pdmosses +[@skullface]: https://github.com/skullface +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 + +### Roadmap + +In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs. + +We're also scoping out medium and long-term projects, and want to keep you in the loop. These include: + +- upgrading to Jekyll 4, and stopping support for Jekyll 3 +- versioned docs - issue [#728] +- improved accessibility - issues [#566], [#870] +- internationalization (i18n) - issue [#59] +- recursive/multi-level navigation - PR [#462] +- toggleable dark mode - issue [#234] + +as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome! + +[#728]: https://github.com/just-the-docs/just-the-docs/issues/728 +[#566]: https://github.com/just-the-docs/just-the-docs/issues/566 +[#870]: https://github.com/just-the-docs/just-the-docs/issues/870 +[#59]: https://github.com/just-the-docs/just-the-docs/issues/59 +[#462]: https://github.com/just-the-docs/just-the-docs/pull/462 +[#234]: https://github.com/just-the-docs/just-the-docs/issues/234 + +### Features + +* Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +* Added: custom favicon `_includes` by [@burner1024] in [#364] +* Added: set color for search input by [@pdmosses] in [#498] +* Added: search placeholder configuration by [@mattxwang] in [#613] +* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +* Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +* Added: mermaid.js support by [@nascosto] in [#857] +* Added: support for external navigation links by [@SPGoding] in [#876] +* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +* Fixed: nested task lists (#517) by [@pdmosses] in [#855] +* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +* Fixed: allow links to wrap by [@pdmosses] in [#905] +* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] + +[#578]: https://github.com/just-the-docs/just-the-docs/pull/578 +[#463]: https://github.com/just-the-docs/just-the-docs/pull/463 +[#448]: https://github.com/just-the-docs/just-the-docs/pull/448 +[#466]: https://github.com/just-the-docs/just-the-docs/pull/466 +[#477]: https://github.com/just-the-docs/just-the-docs/pull/477 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#496]: https://github.com/just-the-docs/just-the-docs/pull/496 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#494]: https://github.com/just-the-docs/just-the-docs/pull/494 +[#639]: https://github.com/just-the-docs/just-the-docs/pull/639 +[#544]: https://github.com/just-the-docs/just-the-docs/pull/544 +[#364]: https://github.com/just-the-docs/just-the-docs/pull/364 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#613]: https://github.com/just-the-docs/just-the-docs/pull/613 +[#726]: https://github.com/just-the-docs/just-the-docs/pull/726 +[#474]: https://github.com/just-the-docs/just-the-docs/pull/474 +[#829]: https://github.com/just-the-docs/just-the-docs/pull/829 +[#857]: https://github.com/just-the-docs/just-the-docs/pull/857 +[#876]: https://github.com/just-the-docs/just-the-docs/pull/876 +[#909]: https://github.com/just-the-docs/just-the-docs/pull/909 +[#519]: https://github.com/just-the-docs/just-the-docs/pull/519 +[#855]: https://github.com/just-the-docs/just-the-docs/pull/855 +[#686]: https://github.com/just-the-docs/just-the-docs/pull/686 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#846]: https://github.com/just-the-docs/just-the-docs/pull/846 +[#727]: https://github.com/just-the-docs/just-the-docs/pull/727 +[#889]: https://github.com/just-the-docs/just-the-docs/pull/889 +[#893]: https://github.com/just-the-docs/just-the-docs/pull/893 +[#905]: https://github.com/just-the-docs/just-the-docs/pull/905 +[#898]: https://github.com/just-the-docs/just-the-docs/pull/898 + +### Documentation + +* Added: docs on how to break an `ol` by [@pdmosses] in [#856] +* Added: docs for custom includes by [@nathanjessen] in [#806] +* Added: document caveat about variable dependencies by [@waldyrious] in [#555] +* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +* Fixed: spacing in toc example by [@henryiii] in [#835] +* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] + +[#856]: https://github.com/just-the-docs/just-the-docs/pull/856 +[#806]: https://github.com/just-the-docs/just-the-docs/pull/806 +[#555]: https://github.com/just-the-docs/just-the-docs/pull/555 +[#814]: https://github.com/just-the-docs/just-the-docs/pull/814 +[#778]: https://github.com/just-the-docs/just-the-docs/pull/778 +[#221]: https://github.com/just-the-docs/just-the-docs/pull/221 +[#782]: https://github.com/just-the-docs/just-the-docs/pull/782 +[#549]: https://github.com/just-the-docs/just-the-docs/pull/549 +[#554]: https://github.com/just-the-docs/just-the-docs/pull/554 +[#499]: https://github.com/just-the-docs/just-the-docs/pull/499 +[#473]: https://github.com/just-the-docs/just-the-docs/pull/473 +[#835]: https://github.com/just-the-docs/just-the-docs/pull/835 +[#891]: https://github.com/just-the-docs/just-the-docs/pull/891 +[#906]: https://github.com/just-the-docs/just-the-docs/pull/906 + +### Maintenance + +* Added: VScode devcontainer by [@max06] in [#783] +* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +* Updated: new repo path by [@pmarsceill] in [#775] +* Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +* Updated: README by [@pmarsceill] in [#777] +* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] + +[#783]: https://github.com/just-the-docs/just-the-docs/pull/783 +[#799]: https://github.com/just-the-docs/just-the-docs/pull/799 +[#797]: https://github.com/just-the-docs/just-the-docs/pull/797 +[#775]: https://github.com/just-the-docs/just-the-docs/pull/775 +[#776]: https://github.com/just-the-docs/just-the-docs/pull/776 +[#777]: https://github.com/just-the-docs/just-the-docs/pull/777 +[#790]: https://github.com/just-the-docs/just-the-docs/pull/790 +[#820]: https://github.com/just-the-docs/just-the-docs/pull/820 +[#821]: https://github.com/just-the-docs/just-the-docs/pull/821 + +### Dependencies + +* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627] +* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606] +* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641] +* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640] +* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511] +* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699] +* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766] +* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787] +* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809] +* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864] + +[#627]: https://github.com/just-the-docs/just-the-docs/pull/627 +[#606]: https://github.com/just-the-docs/just-the-docs/pull/606 +[#641]: https://github.com/just-the-docs/just-the-docs/pull/641 +[#640]: https://github.com/just-the-docs/just-the-docs/pull/640 +[#511]: https://github.com/just-the-docs/just-the-docs/pull/511 +[#699]: https://github.com/just-the-docs/just-the-docs/pull/699 +[#766]: https://github.com/just-the-docs/just-the-docs/pull/766 +[#787]: https://github.com/just-the-docs/just-the-docs/pull/787 +[#809]: https://github.com/just-the-docs/just-the-docs/pull/809 +[#864]: https://github.com/just-the-docs/just-the-docs/pull/864 + +### New Contributors + +* [@AdityaTiwari2102] made their first contribution in [#477] +* [@svrooij] made their first contribution in [#544] +* [@alexsegura] made their first contribution in [#519] +* [@burner1024] made their first contribution in [#364] +* [@JeffGuKang] made their first contribution in [#221] +* [@dougaitken] made their first contribution in [#782] +* [@max06] made their first contribution in [#783] +* [@sehilyi] made their first contribution in [#499] +* [@nathanjessen] made their first contribution in [#473] +* [@waldyrious] made their first contribution in [#549] +* [@MichelleBlanchette] made their first contribution in [#554] +* [@henryiii] made their first contribution in [#835] +* [@jmertic] made their first contribution in [#726] +* [@jacobhq] made their first contribution in [#846] +* [@UnclassedPenguin] made their first contribution in [#814] +* [@alyssais] made their first contribution in [#829] +* [@nascosto] made their first contribution in [#857] +* [@SPGoding] made their first contribution in [#876] +* [@iridazzle] made their first contribution in [#727] +* [@ivanskodje] made their first contribution in [#891] +* [@Eisverygoodletter] made their first contribution in [#893] + +[@AdityaTiwari2102]: https://github.com/AdityaTiwari2102 +[@svrooij]: https://github.com/svrooij +[@alexsegura]: https://github.com/alexsegura +[@burner1024]: https://github.com/burner1024 +[@JeffGuKang]: https://github.com/JeffGuKang +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 +[@sehilyi]: https://github.com/sehilyi +[@nathanjessen]: https://github.com/nathanjessen +[@waldyrious]: https://github.com/waldyrious +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@henryiii]: https://github.com/henryiii +[@jmertic]: https://github.com/jmertic +[@jacobhq]: https://github.com/jacobhq +[@UnclassedPenguin]: https://github.com/UnclassedPenguin +[@alyssais]: https://github.com/alyssais +[@nascosto]: https://github.com/nascosto +[@SPGoding]: https://github.com/SPGoding +[@iridazzle]: https://github.com/iridazzle +[@ivanskodje]: https://github.com/ivanskodje +[@Eisverygoodletter]: https://github.com/Eisverygoodletter + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1 + +[@pmarsceill]: https://github.com/pmarsceill + +## v0.3.3 + +### 🚀 Features + +- Add custom header and footer include files @CodeSandwich (#334) + +### 🐛 Bug Fixes + +- Limit the effect of `nav_exclude` to the main navigation @pdmosses (#443) +- Update normalize.scss @pdmosses (#444) +- Update code.scss @pdmosses (#445) +- Fix list alignment @pdmosses (#446) + +### 🧰 Maintenance + +- Bump stylelint-config-primer from 9.0.0 to 9.2.1 @dependabot-preview (#451) +- Bump stylelint from 13.6.1 to 13.7.2 @dependabot-preview (#440) +- Bump @primer/css from 15.1.0 to 15.2.0 @dependabot-preview (#436) +- Bump prettier from 2.1.1 to 2.1.2 @dependabot-preview (#429) + +## v0.3.2 + +### Changes + +- Safe page sorting @pdmosses (#411) +- v0.3.2 @pmarsceill (#388) + +### 🚀 Features + +- make font-sizes sass variables so they can be changed @pdebruic (#361) +- run the site locally inside docker container @fogfish (#398) +- Feature/doc collections @SgtSilvio (#379) +- Adjust dl layout @pdmosses (#401) + +### 🐛 Bug Fixes + +- Add site.gh_edit_source to "Edit this page on GitHub" link @mrfleap (#418) +- Inhibit text-transform for code in h4 @pdmosses (#404) +- Fix native font stack precedence issue on Windows systems. @hvianna (#331) +- Support for the linenos option on highlighted code @pdmosses (#375) +- Update anchor_headings.html @pdmosses (#399) +- Fix https @marksie1988 (#359) + +### 🧰 Maintenance + +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#427) +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#419) +- [Security] Bump lodash from 4.17.15 to 4.17.19 @dependabot-preview (#389) +- Bump @primer/css from 14.4.0 to 15.1.0 @dependabot-preview (#402) +- Bump lodash from 4.17.15 to 4.17.19 @dependabot (#384) +- Bump @primer/css from 14.4.0 to 15.0.0 @dependabot-preview (#371) + + +## v0.3.1 + +### Changes + +### 🐛 Bug Fixes + +- Improve accessibility by adding label to Anchor links. @mscoutermarsh (#376) + +### 🧰 Maintenance + +- Remove collapsible TOC on nav doc @pmarsceill (#368) +- Pdmosses collapsible toc @pmarsceill (#367) + + +## v0.3.0 + +### Changes + +- v0.2.9 @pmarsceill (#306) + +### 🚀 Features + +- Add print styles @pmarsceill (#362) +- Navigation improvements and search sections @SgtSilvio (#352) + +### 🐛 Bug Fixes + +- Remove constraint with jekyll 4.1.0 @PierrickMartos (#348) + +### 🧰 Maintenance + +- Bump version numbers @pmarsceill (#360) +- Bump stylelint from 13.3.3 to 13.6.1 @dependabot-preview (#343) +- Bump stylelint-config-prettier from 8.0.1 to 8.0.2 @dependabot-preview (#349) + + +## v0.2.9 + +### Bug fixes +- Horizontal Alignment #103 @pmarsceill +- Code snippet in headers do not inherit font size #140 @pmarsceill +- Fix duplicated title and description tags #294 @iefserge +- Update nav.html for handling nav_exclude #282 @blawqchain +- Fix duplicate entries in nav.html and default.html #239 @KasparEtter +- Don't show pages with no title (e.g. redirects in nav) https://github.com/pmarsceill/just-the-docs/pull/295/commits/672de29f2e332a9350af7237e4fb6693c848989e @SgtSilvio +- [SEARCH RAKE] Fix search generator #319 @RoiArthurB + +### Enhancements +- Improvement/custom themes #186 @SgtSilvio +- feat: adds "edit this page" and "page last modified" to footer #217 @malsf21 +- feat: adds option to open aux links in new tab #229 @malsf21 +- Default nav order #236 @pdmosses +- Enable IP anonymization in Google Analytics (GDPR) #250 @r-brown + +closes #240 #308 #266 #140 #103 + +## v0.2.8 + +### Bugfixes +- bugfix in search.rake #218 @tiaitsch85 + +### Dependency and security updates: + +- Update jekyll requirement from ~> 3.8.5 to >= 3.8.5, < 4.1.0 #197 @dependabot-preview +- Update rake requirement from ~> 12.3.1 to >= 12.3.1, < 13.1.0 #227 @dependabot-preview +- Bump stylelint-config-primer from 8.0.0 to 9.0.0 #247 @dependabot-preview +- Update bundler requirement from ~> 2.0.1 to ~> 2.1.4 #268 @dependabot-preview +- Bump @primer/css from 12.7.0 to 14.3.0 #296 @dependabot-preview + +### Operations + +- Update CI to test multiple versions of Jekyll +- Update CI to check the rake command that builds the search file + +fixes #291 #256 #293 #177 + +## v0.2.7 + +### Bugs fixed +- Anchor headings are now displayed on hover, not only on heading hover +- Deduplicated anchor heading svg +- If last page of `site.html_pages` was excluded from search, search json breaks +- Config variable should be `blanklines` not `blank_lines` for html compression +- `list-style-none` does not hide bullets on `ul` + +### Enhancements +- Summary for child pages appears in generated TOC +- Site logo configuration supported replacing title text with image +- Allow custom CSS overrides (new scss partial at the end of the cascade) separate from variable overrides. +- Configuration around search strings added to allow search for hyphenated words + +### Maintenance +- Update docs to suggest using index.md as section page filename +- Bump @primer/css from 12.6.0 to 12.7.0 +- Bump mixin-deep from 1.3.1 to 1.3.2 +- Bump stylelint-config-primer from 7.0.1 to 8.0.0 + +### PR included +- #98 by @stefanoborini Introduces the possibility for a summary in the table of contents +- #141 by @ghabs Fix trailing comma bug in search-data.json +- #153 by @jacobherrington Change button copy on theme preview +- #181 by @m3nu Recommend using index.md as parent page for sections +- #183 by @SgtSilvio Improve heading anchors +- #187 by @SgtSilvio Improvement/site logo +- #200 Bump mixin-deep from 1.3.1 to 1.3.2 +- #203 by @pdmosses Search config +- #205 by @pdmosses Fix blank_lines var to blanklines in config.yml +- #206 by @iamcarrico Allow for custom overrides by the user +- #208 Bump @primer/css from 12.6.0 to 12.7.0 +- #213 Bump mixin-deep from 1.3.1 to 1.3.2 +- #214 Bump stylelint-config-primer from 7.0.1 to 8.0.0 +- #215 Bump @primer/css from 12.6.0 to 12.7.0 + +## v0.2.6 + +### Bugs fixed +- Google Analytics tag has been updated #162 +- ~BaseURL has been modified #109~ Reverted -- seems the existing implementation worked +- Titles can now wrap fixes #106 + +### Enhancements +- Search now displays content preview #135 +- Custom footer content added #179 +- Now using GitHub Actions for CI #170 + +### Maintenance +- lunrjs upgraded #135 +- Nav generation is optimized #159 +- Stylelint upgrade #143 +- Stylelint config primer upgrade #149 +- Lodash upgrade #160 + +### PR included +~#109 by @daviddarnes - Fix baseurl link~ Reverted +#135 by @SgtSilvio - Upgrades lunr.js, improves search UI, adds heading anchors +#152 by @yavorg - Improves syntax highlighting for js readablity +#159 by @julienduchesne - Optimizes nav generation +#162 by @nergmada - Modifies the google analytics code to match the new tags used by GA + + +## v0.2.5 + +### Bugs fixed + +- Duplicate title tag when Jekyll SEO Plugin gem is used #125 #126 + +### Enhancements + +- Favicon support added #118 + +### Maintenance +- Bump stylelint-config-primer from 6.0.0 to 7.0.0 #123 +- Bump @primer/css from 12.2.3 to 12.3.1 #129 +- Add workflow to publish to GPR +- Fix workflow to publish to Ruby Gems + +## v0.2.4 + +### Bugs + +- #102 Remove unnecessary console.log() @JoeNyland +- #97 Import custom Sass variable overrides before default variables are defined @montchr and @ptvandi + +### Additions +- #117 Add links to docs for setting up GH pages locally @gnarea +- #95 Add SEO and 'lang' param for `_config` @gebeto + +## v0.2.3 + +### Enhancements +- Adds ability to use Google Analytics tracking by @pmarsceill + +### Bug fixes +- Fixes 404 error for "/assets/js//search-data.json" by @stephenedmondson +- Fixes #80 Single quotes in the string were unescaped and ruby attempted variable substitution of amp within it (which failed) by @novelistparty +- Fixes bug that would only show 2 or more search results (not one) by @ilivewithian +- Fixes a typo on the layout example by @woernfl +- Fixes #78 Page scroll position too far down on load by @pmarsceill +- Fixds ability to nest ul in ol without breaking style or counters + +### Dependency updates +- Bumps stylelint dependency from 9.9.0 to 9.10.1 + +## v0.2.2 + +- Bumps stylelint-config-primer to 3.0.1 #44 +- Bumps bundler req to 2.0.1 #61 +- Adds custom 404 page +- Excludes package-lock.json from jekyll build #47 +- Fixes keyboard scrolling / focus #48 +- Adds ARIA roles to navigation elements +- Adds support for optional page description metadata (if present in yaml front matter) +- Addresses some issues with search in #46 +- Option to hide TOC on parent pages if turned off in page's YAML front matter #30 +- Option to suppress an item from being indexed by search if present in page's YAML front matter #32 + +## v0.2.1 + +This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version. + +## v0.2.0 + +Adds: +- Dark mode via `color_scheme` parameter +- Ability to exclude a page from the main nav with `nav_exclude` parameter closes #21 +- Ability for create children of children pages (3 nav levels) closes #25 + +Changes: +- Permalink structure for tiered navigation has been updated +- Some colors have been updated for consistency / accessibility + +## v0.1.6 + +### Added + +- Support for task list styles #19 +- Configuration docs +- Configuration option to enable / disable search +- Normalize.scss dependency pulled into project #16 # + +### Fixed + +- Layout bug in navigation #17 + +## v0.1.5 + +Major changes: + +- Fixed bug where the rake task would fail when the assets/js directory didn't exist + +## v0.1.4 + +Major changes: +- Adds Rake as a runtime dependency +- Definition list styled +- Sidebar and support cleaned up for smaller screen support +- Updated some stale docs + +## v0.1.3 + +Major changes: +- Fix path problems, typos, and general clean-up for OSS. + +## v0.1.2 + +Fix paths when deployed to gh-pages + +## v0.1.1 + +Major updates: +- Adds search to mobile nav +- Pulls footer to bottom of the page on mobile (not hidden in nav) + +Minor updates: +- Cleans up h1 typography spacing diff --git a/_sass/CODE_OF_CONDUCT.md b/_sass/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a57ebc6 --- /dev/null +++ b/_sass/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +patrick.marsceill@gmail.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/_sass/Dockerfile b/_sass/Dockerfile new file mode 100644 index 0000000..a499513 --- /dev/null +++ b/_sass/Dockerfile @@ -0,0 +1,12 @@ +FROM ruby:2.7 + +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +WORKDIR /usr/src/app + +COPY Gemfile just-the-docs.gemspec ./ +RUN gem install bundler && bundle install + +EXPOSE 4000 diff --git a/_sass/Gemfile b/_sass/Gemfile new file mode 100644 index 0000000..76bd139 --- /dev/null +++ b/_sass/Gemfile @@ -0,0 +1,8 @@ +source "https://rubygems.org" +gemspec + +gem "jekyll-github-metadata", ">= 2.15" + +gem "jekyll-include-cache", group: :jekyll_plugins + +gem "html-proofer", "~> 5.0", :group => :development diff --git a/_sass/Gemfile.lock b/_sass/Gemfile.lock new file mode 100644 index 0000000..e71b6d0 --- /dev/null +++ b/_sass/Gemfile.lock @@ -0,0 +1,150 @@ +PATH + remote: . + specs: + just-the-docs (0.6.2) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + +GEM + remote: https://rubygems.org/ + specs: + Ascii85 (1.1.0) + addressable (2.8.4) + public_suffix (>= 2.0.2, < 6.0) + afm (0.2.2) + async (2.6.3) + console (~> 1.10) + fiber-annotation + io-event (~> 1.1) + timers (~> 4.1) + colorator (1.1.0) + concurrent-ruby (1.2.2) + console (1.23.2) + fiber-annotation + fiber-local + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + faraday (2.7.10) + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.15.5) + fiber-annotation (0.2.0) + fiber-local (1.0.0) + forwardable-extended (2.6.0) + google-protobuf (3.23.4-arm64-darwin) + google-protobuf (3.23.4-x86_64-linux) + hashery (2.1.2) + html-proofer (5.0.8) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + io-event (1.2.3) + jekyll (4.3.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-github-metadata (2.16.0) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + nokogiri (1.15.4-arm64-darwin) + racc (~> 1.4) + nokogiri (1.15.4-x86_64-linux) + racc (~> 1.4) + octokit (6.1.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + pdf-reader (2.11.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.0.3) + racc (1.7.1) + rainbow (3.1.1) + rake (13.0.6) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.6) + rouge (4.1.2) + ruby-rc4 (0.1.5) + ruby2_keywords (0.0.5) + safe_yaml (1.0.5) + sass-embedded (1.64.1-arm64-darwin) + google-protobuf (~> 3.23) + sass-embedded (1.64.1-x86_64-linux-gnu) + google-protobuf (~> 3.23) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + timers (4.3.5) + ttfunk (1.7.0) + typhoeus (1.4.0) + ethon (>= 0.9.0) + unicode-display_width (2.4.2) + webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.6.11) + +PLATFORMS + arm64-darwin + x86_64-linux + +DEPENDENCIES + bundler (>= 2.3.5) + html-proofer (~> 5.0) + jekyll-github-metadata (>= 2.15) + jekyll-include-cache + just-the-docs! + +BUNDLED WITH + 2.4.13 diff --git a/_sass/LICENSE.txt b/_sass/LICENSE.txt new file mode 100644 index 0000000..9e81a6c --- /dev/null +++ b/_sass/LICENSE.txt @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Patrick Marsceill + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/_sass/MIGRATION.md b/_sass/MIGRATION.md new file mode 100644 index 0000000..f134c7f --- /dev/null +++ b/_sass/MIGRATION.md @@ -0,0 +1,521 @@ +--- +title: Migration and Upgrading +layout: default +--- + +# Migrating and Upgrading + +Summary +: A site that uses `just-the-docs` (as a theme or as a remote theme) automatically + switches to a new release, unless it is pinned to a previous version. + + This migration guide draws attention to: + + - changes that might break your site, + - features added in the latest release, and + - features that have become deprecated (and are likely to be removed in a future release). + +This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`. + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +{::options toc_levels="2..4" /} + +{: .warning } +> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your +> website is built using the current `main` branch of the theme, which may include +> changes made after the latest release; see the [CHANGELOG]. +> +> If your configuration states `theme: just_the_docs` and your `Gemfile` specifies +> `gem "just-the-docs"`, your website is always built using the latest release. + +{: .note } +> If you have cloned/forked and customised the theme repo, +> and pull the changes of a new release to your clone, +> you may need to resolve merge conflicts. + +[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %} + +## v0.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 ` + +{% else %} + +{% if site.mermaid.path %} + +{% else %} + +{% endif %} + + + +{% endif %} diff --git a/_sass/_includes/components/nav.html b/_sass/_includes/components/nav.html new file mode 100644 index 0000000..aa5af38 --- /dev/null +++ b/_sass/_includes/components/nav.html @@ -0,0 +1,75 @@ +{%- comment -%} + Include as: {%- include components/nav.html pages=pages -%} + Depends on: include.pages. + Results in: HTML for the navigation panel. + Includes: + sorted_pages.html + Overwrites: + nav_pages, first_level_pages, second_level_pages, third_level_pages, + node, children_list, child, grand_children_list, grand_child. +{%- endcomment -%} + +{%- assign nav_pages = include.pages + | where_exp: "item", "item.title != nil" + | where_exp: "item", "item.nav_exclude != true" -%} + +{%- include sorted_pages.html pages = nav_pages -%} + +{%- comment -%} + It might be more efficient to sort the pages at each level separately. +{%- endcomment -%} + +{%- assign first_level_pages = sorted_pages + | where_exp: "item", "item.parent == nil" -%} +{%- assign second_level_pages = sorted_pages + | where_exp: "item", "item.parent != nil" + | where_exp: "item", "item.grand_parent == nil" -%} +{%- assign third_level_pages = sorted_pages + | where_exp: "item", "item.grand_parent != nil" -%} + + diff --git a/_sass/_includes/components/search_footer.html b/_sass/_includes/components/search_footer.html new file mode 100644 index 0000000..d448fdb --- /dev/null +++ b/_sass/_includes/components/search_footer.html @@ -0,0 +1,7 @@ +{% if site.search.button %} + +{% endif %} + +
diff --git a/_sass/_includes/components/search_header.html b/_sass/_includes/components/search_header.html new file mode 100644 index 0000000..3562124 --- /dev/null +++ b/_sass/_includes/components/search_header.html @@ -0,0 +1,9 @@ +{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %} + + diff --git a/_sass/_includes/components/sidebar.html b/_sass/_includes/components/sidebar.html new file mode 100644 index 0000000..13c755b --- /dev/null +++ b/_sass/_includes/components/sidebar.html @@ -0,0 +1,32 @@ +{%- comment -%} + Include as: {%- include components/sidebar.html -%} + Depends on: page(?), site. + Results in: HTML for the side bar. + Includes: + title.html, components/site_nav.html, nav_footer_custom.html + Overwrites: + nav_footer_custom. + Should not be cached, because nav_footer_custom.html might depend on page. +{%- endcomment -%} + + diff --git a/_sass/_includes/components/site_nav.html b/_sass/_includes/components/site_nav.html new file mode 100644 index 0000000..12a9ffc --- /dev/null +++ b/_sass/_includes/components/site_nav.html @@ -0,0 +1,67 @@ +{%- comment -%} + Include as: {%- include_cached components/site_nav.html -%} + Depends on: site. + Results in: HTML for the site-nav. + Includes: + components/nav.html + Overwrites: + pages_top_size, collections_size, collection_entry, + collection_key, collection_value, collection. +{%- endcomment -%} + + diff --git a/_sass/_includes/css/activation.scss.liquid b/_sass/_includes/css/activation.scss.liquid new file mode 100644 index 0000000..a32392e --- /dev/null +++ b/_sass/_includes/css/activation.scss.liquid @@ -0,0 +1,281 @@ +{%- comment -%} + Include as: {%- include css/activation.scss.liquid -%} + Depends on: page, site. + Results in: page-dependent (non-nested) CSS rules for inclusion in a head style element, + which needs to be suppressed when JS is enabled. + Includes: + sorted_pages.html. + Overwrites: + activation_no_nav_link, activation_pages, activation_pages_top_size, activation_page, activation_title, + activation_first_level, activation_second_level, activation_third_level, + activation_first_level_reversed, activation_second_level_reversed, + activation_first_level_index, activation_second_level_index, activation_third_level_index, + activation_index, activation_collection_prefix, activation_other_collection_prefix. + Should not be cached, because it depends on page. + (For a site with only top-level pages, the rendering of this file is always empty. + This property could be detected, and used to reduce the build time for such sites.) +{%- endcomment -%} + +{%- comment -%} + The CSS rules in activation_no_nav_link are for use on pages excluded from the main navigation. + - The first rule ensures that no nav-link has a background image. + - The other two rules ensure that all folding collections are expanded. +{%- endcomment -%} + +{%- capture activation_no_nav_link %} +.site-nav ul li a { + background-image: none; +} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li > button svg { + transform: rotate(-90deg); +} +.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list { + display: block; +} +{%- endif %} +{% endcapture -%} + +{%- if page.title == nil or page.nav_exclude == true -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- assign activation_pages = site[page.collection] + | default: site.html_pages + | where_exp: "item", "item.title != nil" + | where_exp: "item", "item.nav_exclude != true" -%} + +{%- assign activation_first_level_index = nil -%} +{%- assign activation_second_level_index = nil -%} +{%- assign activation_third_level_index = nil -%} +{%- assign activation_first_level_reversed = nil -%} +{%- assign activation_second_level_reversed = nil -%} + +{%- comment -%} + The generated CSS depends on the position of the current page in each level in + the navigation. +{%- endcomment -%} + +{%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%} +{%- assign activation_first_level = activation_pages + | where_exp: "item", "item.parent == nil" -%} +{%- include sorted_pages.html pages = activation_first_level -%} +{%- for activation_page in sorted_pages -%} + {%- if activation_page.title == activation_title -%} + {%- assign activation_first_level_index = forloop.index -%} + {%- assign activation_first_level_reversed = activation_page.child_nav_order -%} + {%- break -%} + {%- endif -%} +{%- endfor -%} + +{%- if activation_first_level_index == nil -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- if page.grand_parent -%} + {%- assign activation_title = page.parent -%} + {%- assign activation_second_level = activation_pages + | where_exp: "item", "item.grand_parent == nil" + | where_exp: "item", "item.parent == page.grand_parent" -%} +{%- elsif page.parent -%} + {%- assign activation_title = page.title -%} + {%- assign activation_second_level = activation_pages + | where_exp: "item", "item.grand_parent == nil" + | where_exp: "item", "item.parent == page.parent" -%} +{%- endif -%} +{%- if page.parent -%} + {%- include sorted_pages.html pages = activation_second_level -%} + {%- for activation_page in sorted_pages -%} + {%- if activation_page.title == activation_title -%} + {%- assign activation_second_level_index = forloop.index -%} + {%- assign activation_second_level_reversed = activation_page.child_nav_order -%} + {%- if activation_first_level_reversed -%} + {%- assign activation_second_level_index = sorted_pages | size | plus: 1 | minus: activation_second_level_index -%} + {%- endif -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} +{%- endif -%} + +{%- if page.grand_parent -%} + {%- assign activation_third_level = activation_pages + | where_exp: "item", "item.parent == page.parent" + | where_exp: "item", "item.grand_parent == page.grand_parent" -%} + {%- include sorted_pages.html pages = activation_third_level -%} + {%- assign activation_third_level = sorted_pages -%} + {%- for activation_page in sorted_pages -%} + {%- if activation_page.title == page.title -%} + {%- assign activation_third_level_index = forloop.index -%} + {%- if activation_second_level_reversed -%} + {%- assign activation_third_level_index = sorted_pages | size | plus: 1 | minus: activation_third_level_index -%} + {%- endif -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} +{%- endif -%} + +{%- if activation_second_level_index == nil and activation_third_level_index -%} + +{{ activation_no_nav_link }} + +{%- else -%} + +{%- comment -%} + The site-nav is: + - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages + - an optional ul.nav-list with li.nav-list-item.externals + - any number of just-the-docs.collections + + A non-foldable collection is: + - a div.nav-category with the collection name, followed by: + - a ul.nav-list with li.nav-list-items for its top-level pages + + A foldable collection is: + - a ul.nav-list.nav-category-list with a single li.nav-list-item containing: + - an optional button with the expander svg + - a div.nav-category with the collection name + - a ul.nav-list with li.nav-list-items for its top-level pages + + The generated CSS uses: + - activation_collection_prefix, to select the site-nav > ul.nav-list for the page + - activation_other_collection_prefix, to select all the other site-nav > ul.nav-lists +{%- endcomment -%} + +{%- if page.collection == nil -%} + + {%- capture activation_collection_prefix -%} + .site-nav > ul.nav-list:first-child + {%- endcapture -%} + + {%- capture activation_other_collection_prefix -%} + .site-nav > ul.nav-list:not(:first-child) + {%- endcapture -%} + +{%- else -%} + + {%- for activation_collection in site.just_the_docs.collections -%} + {%- if activation_collection[0] == page.collection -%} + {%- assign activation_index = forloop.index -%} + {%- break -%} + {%- endif -%} + {%- endfor -%} + + {%- assign activation_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 activation_pages_top_size > 0 -%} + {%- assign activation_index = activation_index | plus: 1 -%} + {%- endif -%} + + {%- if site.nav_external_links -%} + {%- assign activation_index = activation_index | plus: 1 -%} + {%- endif -%} + + {%- capture activation_collection_prefix -%} + .site-nav > ul:nth-of-type({{ activation_index }}) + {%- if site.just_the_docs.collections[page.collection].nav_fold %} > li > ul + {%- endif -%} + {%- endcapture -%} + + {%- capture activation_other_collection_prefix -%} + .site-nav > ul:not(:nth-of-type({{ activation_index }})) + {%- endcapture -%} + +{%- endif -%} + +{%- comment -%} + The required background image of the link to the current page may involve SCSS. + To avoid page-dependent SCSS, all nav links initially have that background image. + The following rule removes the image from the links to all parents, siblings, + and children of the current page. +{%- endcomment %} + +{% if activation_third_level_index -%} + +{{ activation_collection_prefix }} > li > a, +{{ activation_collection_prefix }} > li > ul > li > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ activation_third_level_index }})) > a { + background-image: none; +} + +{%- elsif activation_second_level_index -%} + +{{ activation_collection_prefix }} > li > a, +{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ activation_second_level_index }})) > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li > a { + background-image: none; +} + +{%- else -%} + +{{ activation_collection_prefix }} > li:not(:nth-child({{ activation_first_level_index }})) > a, +{{ activation_collection_prefix }} > li > ul > li > a, +{{ activation_collection_prefix }} > li > ul > li > ul > li > a { + background-image: none; +} + +{%- endif %} + +{%- comment -%} + The following rule removes the image from the links to pages in other collections. +{%- endcomment %} + +{{ activation_other_collection_prefix }} a, +.site-nav li.external a { + background-image: none; +} + +{%- comment -%} + The following rule styles the link to the current page. +{%- endcomment %} + +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) +{%- if activation_second_level_index %} > ul > li:nth-child({{ activation_second_level_index }}) +{%- if activation_third_level_index %} > ul > li:nth-child({{ activation_third_level_index }}) +{%- endif -%} +{%- endif %} > a { + font-weight: 600; + text-decoration: none; +} + +{%- comment -%} + The following rules unfold all collections, and display the links to any children + of the current page. + + To avoid dependence on the SCSS variable nav-list-expander-right, the direction + of the rotation of the expander icon is fixed, and corresponds to the appearance + when nav-list-expander-right is true. This results in a minor visual difference + between the appearance of active expander icons when JS is enabled/disabled and + nav-list-expander-right is false, which seems unavoidable. +{%- endcomment %} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li > button svg, +{% endif -%} +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > button svg +{%- if activation_second_level_index -%}, +{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > ul > li:nth-child({{ activation_second_level_index }}) > button svg +{%- endif %} { + transform: rotate(-90deg); +} + +{%- if site.just_the_docs.collections %} +.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list, +{% endif -%} +{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list +{%- if activation_second_level_index %}, +{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list > li.nav-list-item:nth-child({{ activation_second_level_index }}) > ul.nav-list +{%- endif %} { + display: block; +} + +{%- endif -%} +{%- endif -%} +{%- endif -%} diff --git a/_sass/_includes/css/callouts.scss.liquid b/_sass/_includes/css/callouts.scss.liquid new file mode 100644 index 0000000..e99600e --- /dev/null +++ b/_sass/_includes/css/callouts.scss.liquid @@ -0,0 +1,93 @@ +{%- comment -%} + {% include css/callouts.scss.liquid color_scheme = string %} + produces SCSS for all the callouts in site.callouts. For the "dark" + color scheme, the levels of the text and background colors are reversed. +{%- endcomment -%} + +{%- assign callout_background_hue = "000" -%} +{%- assign callout_color_hue = "300" -%} +{%- if site.callouts_level == "loud" or include.color_scheme == "dark" and site.callouts_level != "quiet" -%} + {%- assign callout_background_hue = "300" -%} + {%- assign callout_color_hue = "000" -%} +{%- endif -%} + +div.opaque { + background-color: $body-background-color; +} + +{%- for callout in site.callouts %} + +{%- assign callout_opacity = callout[1].opacity | default: site.callouts_opacity | default: 0.2 -%} + +p.{{ callout[0] }}, blockquote.{{ callout[0] }} { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + {% if callout[1].title %} + &::before { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + content: "{{ callout[1].title }}"; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } + {% endif %} + > .{{ callout[0] }}-title { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +p.{{ callout[0] }}-title, blockquote.{{ callout[0] }}-title { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + > p:first-child { + margin-top: 0; + margin-bottom: 0; + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +blockquote.{{ callout[0] }} { + margin-left: 0; + margin-right: 0; + + > p:first-child { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +blockquote.{{ callout[0] }}-title { + margin-left: 0; + margin-right: 0; + + > p:nth-child(2) { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +{% endfor -%} diff --git a/_sass/_includes/css/custom.scss.liquid b/_sass/_includes/css/custom.scss.liquid new file mode 100644 index 0000000..2ad1576 --- /dev/null +++ b/_sass/_includes/css/custom.scss.liquid @@ -0,0 +1 @@ +@import "./custom/custom"; diff --git a/_sass/_includes/css/just-the-docs.scss.liquid b/_sass/_includes/css/just-the-docs.scss.liquid new file mode 100644 index 0000000..2eb480d --- /dev/null +++ b/_sass/_includes/css/just-the-docs.scss.liquid @@ -0,0 +1,12 @@ +{% if site.logo %} +$logo: "{{ site.logo | relative_url }}"; +{% endif %} +@import "./support/support"; +@import "./custom/setup"; +@import "./color_schemes/light"; +{% unless include.color_scheme == "light" %} +@import "./color_schemes/{{ include.color_scheme }}"; +{% endunless %} +@import "./modules"; +{% include css/callouts.scss.liquid color_scheme = include.color_scheme %} +{% include css/custom.scss.liquid %} diff --git a/_sass/_includes/favicon.html b/_sass/_includes/favicon.html new file mode 100644 index 0000000..7d2a53d --- /dev/null +++ b/_sass/_includes/favicon.html @@ -0,0 +1,23 @@ +{%- comment -%} + Include as: {%- include_cached favicon.html -%} + Depends on: site.static_files. + Results in: HTML for a link to an existing `favicon.ico` file. + Overwrites: + file. + + The endoflife.date site has 226 pages and 3410 static files. @marcwrobel pointed + out that the time taken by evaluating the code in this file on every page when + building that site was significant, and suggested making it optional. As it is + page-independent, it can easily be cached. Doing that reduced the time taken by + rendering `_includes/head.html` from 15.294s to 10.760s, thereby reducing the + total build time from 26.074s to 21.656s -- a saving of about 17%. +{%- endcomment -%} + +{% 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 %} diff --git a/_sass/_includes/fix_linenos.html b/_sass/_includes/fix_linenos.html new file mode 100644 index 0000000..6243fb0 --- /dev/null +++ b/_sass/_includes/fix_linenos.html @@ -0,0 +1,65 @@ +{%- comment -%} +This file can be used to fix the HTML produced by Jekyll for highlighted +code with line numbers. + +It works with `{% highlight some_language linenos %}...{% endhighlight %}` +and with the Kramdown option to add line numbers to fenced code. + +The implementation was derived from the workaround provided by +Dmitry Hrabrov (DeXP) at +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901 + +EXPLANATION + +The HTML produced by Rouge highlighting with lie numbers is of the form +`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML +with `pre`. This wrapping is not only unnecessary, but also transforms +the conforming HTML produced by Rouge to non-conforming HTML, which +results in HTML validation error reports. + +The fix removes the outer `pre` tags whenever they contain the pattern +``. + +Apart from avoiding HTML validation errors, the fix allows the use of +the [Jekyll layout for compressing HTML](http://jch.penibelst.de), +which relies on `pre` tags not being nested, according to +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 + +USAGE + +(Any names can be used for `some_var` and `some_language`.) + +{% capture some_var %} +{% highlight some_language linenos %} +Some code +{% endhighlight %} +{% endcapture %} +{% include fix_linenos.html code=some_var %} + +For code fences: + +{% capture some_var %} +```some_language +Some code +``` +{% endcapture %} +{% assign some_var = some_var | markdownify %} +{% include fix_linenos.html code=some_var %} + +CAVEATS + +The above does not work when `Some code` happens to contain the matched string +`
`. + +The use of this file overwrites the variable `fix_linenos_code` with `nil`. + +{%- endcomment -%} + +{% assign fix_linenos_code = include.code %} +{% if fix_linenos_code contains '
' %} + {% assign fix_linenos_code = fix_linenos_code | replace: '
', '
' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "
", "" %} +{% endif %} +{{ fix_linenos_code }} +{% assign fix_linenos_code = nil %} diff --git a/_sass/_includes/footer_custom.html b/_sass/_includes/footer_custom.html new file mode 100644 index 0000000..64e08c2 --- /dev/null +++ b/_sass/_includes/footer_custom.html @@ -0,0 +1,3 @@ +{%- if site.footer_content -%} +

{{ site.footer_content }}

+{%- endif -%} diff --git a/_sass/_includes/head.html b/_sass/_includes/head.html new file mode 100644 index 0000000..6cd1d52 --- /dev/null +++ b/_sass/_includes/head.html @@ -0,0 +1,53 @@ +{%- comment -%} + Include as: {%- include head.html -%} + Depends on: site.ga_tracking, site.ga_tracking_anonymize_ip, + site.search_enabled, site.static_files, site.favicon_ico. + Results in: HTML for the head element. + Includes: + css/activation.scss.liquid, head_custom.html. + Overwrites: + ga_tracking_ids, ga_property, file, favicon. + Should not be cached, because included files depend on page. +{%- endcomment -%} + + + + + + + + + + + + {% if site.ga_tracking != nil %} + {% assign ga_tracking_ids = site.ga_tracking | split: "," %} + + + {% endif %} + + {% if site.search_enabled != false %} + + {% endif %} + + + + + + {% include_cached favicon.html %} + + {% seo %} + + {% include head_custom.html %} + + diff --git a/_sass/_includes/head_custom.html b/_sass/_includes/head_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/header_custom.html b/_sass/_includes/header_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/icons/code_copy.html b/_sass/_includes/icons/code_copy.html new file mode 100644 index 0000000..fb6421f --- /dev/null +++ b/_sass/_includes/icons/code_copy.html @@ -0,0 +1,15 @@ + + + Copy + + + + + + + Copied + + + + + diff --git a/_sass/_includes/icons/document.html b/_sass/_includes/icons/document.html new file mode 100644 index 0000000..c09e8a5 --- /dev/null +++ b/_sass/_includes/icons/document.html @@ -0,0 +1,6 @@ + + Document + + + + diff --git a/_sass/_includes/icons/expand.html b/_sass/_includes/icons/expand.html new file mode 100644 index 0000000..79921a5 --- /dev/null +++ b/_sass/_includes/icons/expand.html @@ -0,0 +1,6 @@ + + Expand + + + + diff --git a/_sass/_includes/icons/external_link.html b/_sass/_includes/icons/external_link.html new file mode 100644 index 0000000..1592be6 --- /dev/null +++ b/_sass/_includes/icons/external_link.html @@ -0,0 +1,5 @@ + + + (external link) + + diff --git a/_sass/_includes/icons/icons.html b/_sass/_includes/icons/icons.html new file mode 100644 index 0000000..007a495 --- /dev/null +++ b/_sass/_includes/icons/icons.html @@ -0,0 +1,13 @@ + + {% include icons/link.html %} + {% include icons/menu.html %} + {% include icons/expand.html %} + {% include icons/external_link.html %} + {% if site.search_enabled != false %} + {% include icons/document.html %} + {% include icons/search.html %} + {% endif %} + {% if site.enable_copy_code_button != false %} + {% include icons/code_copy.html %} + {% endif %} + diff --git a/_sass/_includes/icons/link.html b/_sass/_includes/icons/link.html new file mode 100644 index 0000000..de24be7 --- /dev/null +++ b/_sass/_includes/icons/link.html @@ -0,0 +1,6 @@ + + Link + + + + diff --git a/_sass/_includes/icons/menu.html b/_sass/_includes/icons/menu.html new file mode 100644 index 0000000..d256575 --- /dev/null +++ b/_sass/_includes/icons/menu.html @@ -0,0 +1,6 @@ + + Menu + + + + diff --git a/_sass/_includes/icons/search.html b/_sass/_includes/icons/search.html new file mode 100644 index 0000000..8f72c6a --- /dev/null +++ b/_sass/_includes/icons/search.html @@ -0,0 +1,6 @@ + + Search + + + + diff --git a/_sass/_includes/js/custom.js b/_sass/_includes/js/custom.js new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/lunr/custom-data.json b/_sass/_includes/lunr/custom-data.json new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/lunr/custom-index.js b/_sass/_includes/lunr/custom-index.js new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/mermaid_config.js b/_sass/_includes/mermaid_config.js new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/_sass/_includes/mermaid_config.js @@ -0,0 +1 @@ +{} diff --git a/_sass/_includes/nav_footer_custom.html b/_sass/_includes/nav_footer_custom.html new file mode 100644 index 0000000..e69de29 diff --git a/_sass/_includes/search_placeholder_custom.html b/_sass/_includes/search_placeholder_custom.html new file mode 100644 index 0000000..2885058 --- /dev/null +++ b/_sass/_includes/search_placeholder_custom.html @@ -0,0 +1 @@ +Search {{site.title}} diff --git a/_sass/_includes/sorted_pages.html b/_sass/_includes/sorted_pages.html new file mode 100644 index 0000000..659be10 --- /dev/null +++ b/_sass/_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/_sass/_includes/title.html b/_sass/_includes/title.html new file mode 100644 index 0000000..8f65336 --- /dev/null +++ b/_sass/_includes/title.html @@ -0,0 +1,5 @@ +{% if site.logo %} + +{% else %} + {{ site.title }} +{% endif %} diff --git a/_sass/_includes/toc_heading_custom.html b/_sass/_includes/toc_heading_custom.html new file mode 100644 index 0000000..82a7700 --- /dev/null +++ b/_sass/_includes/toc_heading_custom.html @@ -0,0 +1 @@ +

Table of contents

diff --git a/_sass/_layouts/about.html b/_sass/_layouts/about.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_sass/_layouts/about.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_sass/_layouts/default.html b/_sass/_layouts/default.html new file mode 100644 index 0000000..923c1c1 --- /dev/null +++ b/_sass/_layouts/default.html @@ -0,0 +1,41 @@ +--- +layout: table_wrappers +--- + + + + +{% include head.html %} + + Skip to main content + {% include icons/icons.html %} + {% 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 %} + {% endif %} +
+ {% include components/footer.html %} +
+
+ {% if site.search_enabled != false %} + {% include components/search_footer.html %} + {% endif %} +
+ + {% if site.mermaid %} + {% include components/mermaid.html %} + {% endif %} + + diff --git a/_sass/_layouts/home.html b/_sass/_layouts/home.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_sass/_layouts/home.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_sass/_layouts/minimal.html b/_sass/_layouts/minimal.html new file mode 100644 index 0000000..b12c5db --- /dev/null +++ b/_sass/_layouts/minimal.html @@ -0,0 +1,34 @@ +--- +layout: table_wrappers +--- + + + + +{% include head.html %} + + Skip to main content + {% include icons/icons.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 %} + {% endif %} + + {% include components/footer.html %} + +
+
+ + {% if site.mermaid %} + {% include components/mermaid.html %} + {% endif %} + + diff --git a/_sass/_layouts/page.html b/_sass/_layouts/page.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_sass/_layouts/page.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_sass/_layouts/post.html b/_sass/_layouts/post.html new file mode 100644 index 0000000..5e71126 --- /dev/null +++ b/_sass/_layouts/post.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{{ content }} diff --git a/_sass/_layouts/table_wrappers.html b/_sass/_layouts/table_wrappers.html new file mode 100644 index 0000000..3f8f226 --- /dev/null +++ b/_sass/_layouts/table_wrappers.html @@ -0,0 +1,7 @@ +--- +layout: vendor/compress +--- + +{% assign content_ = content | replace: '', '
' %} +{{ content_ }} diff --git a/_sass/assets/css/just-the-docs-dark.scss b/_sass/assets/css/just-the-docs-dark.scss new file mode 100644 index 0000000..ac92fb1 --- /dev/null +++ b/_sass/assets/css/just-the-docs-dark.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="dark" %} diff --git a/_sass/assets/css/just-the-docs-default.scss b/_sass/assets/css/just-the-docs-default.scss new file mode 100644 index 0000000..63fde26 --- /dev/null +++ b/_sass/assets/css/just-the-docs-default.scss @@ -0,0 +1,8 @@ +--- +--- +{% if site.color_scheme and site.color_scheme != "nil" %} + {% assign color_scheme = site.color_scheme %} +{% else %} + {% assign color_scheme = "light" %} +{% endif %} +{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %} diff --git a/_sass/assets/css/just-the-docs-head-nav.css b/_sass/assets/css/just-the-docs-head-nav.css new file mode 100644 index 0000000..0cb97b3 --- /dev/null +++ b/_sass/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/_sass/assets/css/just-the-docs-light.scss b/_sass/assets/css/just-the-docs-light.scss new file mode 100644 index 0000000..ac69688 --- /dev/null +++ b/_sass/assets/css/just-the-docs-light.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="light" %} diff --git a/_sass/assets/images/large-image.jpg b/_sass/assets/images/large-image.jpg new file mode 100644 index 0000000..c007781 Binary files /dev/null and b/_sass/assets/images/large-image.jpg differ diff --git a/_sass/assets/images/small-image.jpg b/_sass/assets/images/small-image.jpg new file mode 100644 index 0000000..5bf58a9 Binary files /dev/null and b/_sass/assets/images/small-image.jpg differ diff --git a/_sass/assets/js/just-the-docs.js b/_sass/assets/js/just-the-docs.js new file mode 100644 index 0000000..b7e3655 --- /dev/null +++ b/_sass/assets/js/just-the-docs.js @@ -0,0 +1,587 @@ +--- +--- +(function (jtd, undefined) { + +// Event handling + +jtd.addEvent = function(el, type, handler) { + if (el.attachEvent) el.attachEvent('on'+type, handler); else el.addEventListener(type, handler); +} +jtd.removeEvent = function(el, type, handler) { + if (el.detachEvent) el.detachEvent('on'+type, handler); else el.removeEventListener(type, handler); +} +jtd.onReady = function(ready) { + // in case the document is already rendered + if (document.readyState!='loading') ready(); + // modern browsers + else if (document.addEventListener) document.addEventListener('DOMContentLoaded', ready); + // IE <= 8 + else document.attachEvent('onreadystatechange', function(){ + if (document.readyState=='complete') ready(); + }); +} + +// Show/hide mobile menu + +function initNav() { + jtd.addEvent(document, 'click', function(e){ + var target = e.target; + while (target && !(target.classList && target.classList.contains('nav-list-expander'))) { + target = target.parentNode; + } + if (target) { + e.preventDefault(); + target.ariaPressed = target.parentNode.classList.toggle('active'); + } + }); + + const siteNav = document.getElementById('site-nav'); + 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; + } + }); + + {%- if site.search_enabled != false and site.search.button %} + const searchInput = document.getElementById('search-input'); + const searchButton = document.getElementById('search-button'); + + jtd.addEvent(searchButton, 'click', function(e){ + e.preventDefault(); + + mainHeader.classList.add('nav-open'); + searchInput.focus(); + }); + {%- 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