mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-09 21:41:23 -06:00
Merge branch 'main' into custom-schemes
This commit is contained in:
Matt Wang
GitHub
commit
720b0ebf9f
2
.github/FUNDING.yml
vendored
Normal file
2
.github/FUNDING.yml
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
github: just-the-docs
|
||||
open_collective: just-the-docs
|
||||
35
.github/release-drafter.yml
vendored
35
.github/release-drafter.yml
vendored
@ -1,35 +0,0 @@
|
||||
references:
|
||||
- v+
|
||||
- main
|
||||
name-template: "v$RESOLVED_VERSION 🌈"
|
||||
tag-template: "v$RESOLVED_VERSION"
|
||||
categories:
|
||||
- title: "🚀 Features"
|
||||
labels:
|
||||
- "feature"
|
||||
- "enhancement"
|
||||
- title: "🐛 Bug Fixes"
|
||||
labels:
|
||||
- "fix"
|
||||
- "bugfix"
|
||||
- "bug"
|
||||
- title: "🧰 Maintenance"
|
||||
label:
|
||||
- "chore"
|
||||
- "dependencies"
|
||||
change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
|
||||
version-resolver:
|
||||
major:
|
||||
labels:
|
||||
- "next-major-release"
|
||||
minor:
|
||||
labels:
|
||||
- "next-minor-release"
|
||||
patch:
|
||||
labels:
|
||||
- "patch"
|
||||
default: minor
|
||||
template: |
|
||||
## Changes
|
||||
|
||||
$CHANGES
|
||||
63
.github/workflows/ci.yml
vendored
63
.github/workflows/ci.yml
vendored
@ -16,38 +16,79 @@ jobs:
|
||||
matrix:
|
||||
jekyll-version: [3.9, 4.3]
|
||||
os: [ ubuntu-latest, macos-latest, windows-latest ]
|
||||
ruby-version: [2.7, 3.1]
|
||||
ruby-version: ["3.0", "3.1", "3.2"]
|
||||
runs-on: ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/checkout@v4
|
||||
- name: Setup Ruby ${{ matrix.ruby-version }}
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: ${{ matrix.ruby-version }}
|
||||
bundler-cache: false
|
||||
- name: Bundle Install
|
||||
- name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
|
||||
run: bundle install
|
||||
- name: Install Jekyll ${{ matrix.jekyll-version }}
|
||||
run: gem install jekyll -v ${{ matrix.jekyll-version }}
|
||||
env:
|
||||
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
||||
- name: Init Search
|
||||
run: bundle exec rake search:init
|
||||
env:
|
||||
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
||||
- name: Build Site
|
||||
run: bundle exec jekyll build
|
||||
env:
|
||||
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
||||
|
||||
github-pages-build:
|
||||
name: Build (github-pages gem)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/checkout@v4
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: '3.1'
|
||||
ruby-version: "3.2"
|
||||
bundler-cache: false
|
||||
- name: Bundle Install
|
||||
run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle install
|
||||
run: bundle install
|
||||
env:
|
||||
BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
|
||||
- name: Build Site
|
||||
run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle exec jekyll build
|
||||
run: bundle exec jekyll build
|
||||
env:
|
||||
BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
|
||||
|
||||
validate:
|
||||
name: Validate HTML
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
ruby-version: ["3.2"]
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Setup Ruby ${{ matrix.ruby-version }}
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: ${{ matrix.ruby-version }}
|
||||
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
|
||||
cache-version: 0 # Increment this number if you need to re-download cached gems
|
||||
- name: Cache HTMLProofer
|
||||
id: cache-htmlproofer
|
||||
uses: actions/cache@v3
|
||||
with:
|
||||
path: tmp/.htmlproofer
|
||||
key: ${{ runner.os }}-htmlproofer
|
||||
- name: Build Site
|
||||
run: bundle exec jekyll build
|
||||
- name: Test with Nu Validator
|
||||
uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8
|
||||
with:
|
||||
config: fixtures/html5validator-config.yml
|
||||
- name: Test with html-proofer
|
||||
run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
|
||||
env:
|
||||
NOKOGIRI_USE_SYSTEM_LIBRARIES: true
|
||||
|
||||
assets:
|
||||
name: Test CSS and JS
|
||||
@ -58,9 +99,9 @@ jobs:
|
||||
node-version: [18.x]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/checkout@v4
|
||||
- name: Use Node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v1
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
- run: npm install
|
||||
|
||||
10
.github/workflows/deploy.yml
vendored
10
.github/workflows/deploy.yml
vendored
@ -30,16 +30,16 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
uses: actions/checkout@v4
|
||||
- name: Setup Ruby
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: '3.1' # Not needed with a .ruby-version file
|
||||
ruby-version: "3.2"
|
||||
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
|
||||
cache-version: 0 # Increment this number if you need to re-download cached gems
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v2
|
||||
uses: actions/configure-pages@v3
|
||||
- name: Build with Jekyll
|
||||
# Outputs to the './_site' directory by default
|
||||
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
|
||||
@ -47,7 +47,7 @@ jobs:
|
||||
JEKYLL_ENV: production
|
||||
- name: Upload artifact
|
||||
# Automatically uploads an artifact from the './_site' directory by default
|
||||
uses: actions/upload-pages-artifact@v1
|
||||
uses: actions/upload-pages-artifact@v2
|
||||
|
||||
# Deployment job
|
||||
deploy:
|
||||
@ -59,4 +59,4 @@ jobs:
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v1
|
||||
uses: actions/deploy-pages@v2
|
||||
|
||||
8
.github/workflows/publish-gem.yml
vendored
8
.github/workflows/publish-gem.yml
vendored
@ -9,11 +9,11 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Set up Ruby 3.1
|
||||
uses: actions/setup-ruby@v1
|
||||
- uses: actions/checkout@v4
|
||||
- name: Setup Ruby 3.2
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: 3.1
|
||||
ruby-version: "3.2"
|
||||
|
||||
- name: Publish to GPR
|
||||
run: |
|
||||
|
||||
33
.gitignore
vendored
33
.gitignore
vendored
@ -1,9 +1,30 @@
|
||||
# Not sure what a .gitignore is?
|
||||
# See: https://git-scm.com/docs/gitignore
|
||||
|
||||
# The first files are directly copied from Jekyll's first-party docs on `.gitignore` files:
|
||||
# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control
|
||||
|
||||
# Ignore the default location of the built site, and caches and metadata generated by Jekyll
|
||||
_site/
|
||||
.sass-cache/
|
||||
.jekyll-cache/
|
||||
.jekyll-metadata
|
||||
|
||||
# Ignore folders generated by Bundler
|
||||
.bundle/
|
||||
vendor/
|
||||
|
||||
# These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers.
|
||||
|
||||
# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code.
|
||||
# We use Node.js as our runtime, so we ignore node_modules
|
||||
node_modules
|
||||
|
||||
# .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them.
|
||||
# See: https://en.wikipedia.org/wiki/.DS_Store
|
||||
.DS_Store
|
||||
|
||||
# These are legacy globs that typically target Ruby theme developers. We may change these at a later date.
|
||||
*.gem
|
||||
.bundle
|
||||
.ruby-version
|
||||
.jekyll-cache
|
||||
.sass-cache
|
||||
_site
|
||||
Gemfile.lock
|
||||
node_modules
|
||||
.DS_Store
|
||||
|
||||
328
CHANGELOG.md
328
CHANGELOG.md
@ -15,16 +15,300 @@ The project underwent a major maintenance shift in March 2022.
|
||||
{: .note }
|
||||
This website is built from the `HEAD` of the `main` branch of the theme repository.
|
||||
|
||||
{: .warning }
|
||||
This website includes docs for some new features that are not available in `v0.5.0`!
|
||||
|
||||
Code changes to `main` that are *not* in the latest release:
|
||||
|
||||
- n/a
|
||||
- N/A
|
||||
|
||||
Docs changes in `main` that are *not* in the latest release:
|
||||
## Release v0.7.0
|
||||
|
||||
- n/a
|
||||
Hi folks! This is a minor release that adds a new configuration option for opening external links in a new tab and provides many bugfixes (in both correctness and performance) for Just the Docs users with large sites. We anticipate that for most users, this is a straightforward upgrade. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
|
||||
|
||||
### Migrating to `v0.7.0`
|
||||
|
||||
**Migration**: users will need to migrate if:
|
||||
|
||||
- they overrode `_includes/nav.html`, which has moved to `_includes/components/nav.html`
|
||||
- they have an element with the IDs `jtd-nav-activation` or `jtd-head-nav-stylesheet`
|
||||
|
||||
For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
|
||||
|
||||
### Using Release `v0.7.0`
|
||||
|
||||
Users who have not pinned the theme version will be **automatically upgraded to `v0.7.0` the next time they build their site**.
|
||||
|
||||
To use this release explicitly as a remote theme:
|
||||
|
||||
```yml
|
||||
remote_theme: just-the-docs/just-the-docs@v0.7.0
|
||||
```
|
||||
|
||||
To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
|
||||
|
||||
```ruby
|
||||
gem "just-the-docs", "0.7.0"
|
||||
```
|
||||
|
||||
To use and pin a previous version of the theme, replace the `0.7.0` with the desired release tag.
|
||||
|
||||
### New Features
|
||||
|
||||
- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360]
|
||||
|
||||
### Bugfixes
|
||||
|
||||
- Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356]
|
||||
- Fixed: improve build time by [@pdmosses] in [#1358]
|
||||
- Fixed: erroneous parentheses in `site_nav` conditional by [@mattxwang] in [#1366]
|
||||
- Fixed: navigation scroll to active link regression by [@pdmosses] in [#1367]
|
||||
- Fixed: invalid CSS rules in head elements by [@pdmosses] in [#1368]
|
||||
- Fixed: accidental disabling of forward-declared stylesheets by [@mattxwang] in [#1373]
|
||||
|
||||
{: .warning }
|
||||
[#1358] moved `_includes/nav.html` to the `_includes/components` directory,
|
||||
Users who were overriding that file will need to adjust their sites accordingly.
|
||||
|
||||
### Documentation:
|
||||
|
||||
- Docs: fix typos in `CHANGELOG` and `MIGRATION` by [@thapasusheel] in [#1377]
|
||||
|
||||
### New Contributors
|
||||
|
||||
- [@CarbonNeuron] made their first contribution in [#1360]
|
||||
- [@thapasusheel] made their first contribution in [#1377]
|
||||
|
||||
[@CarbonNeuron]: https://github.com/CarbonNeuron
|
||||
[@thapasusheel]: https://github.com/thapasusheel
|
||||
|
||||
[#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356
|
||||
[#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358
|
||||
[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360
|
||||
[#1366]: https://github.com/just-the-docs/just-the-docs/pull/1366
|
||||
[#1367]: https://github.com/just-the-docs/just-the-docs/pull/1367
|
||||
[#1368]: https://github.com/just-the-docs/just-the-docs/pull/1368
|
||||
[#1373]: https://github.com/just-the-docs/just-the-docs/pull/1373
|
||||
[#1377]: https://github.com/just-the-docs/just-the-docs/pull/1377
|
||||
|
||||
## Release v0.6.2
|
||||
|
||||
Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6.
|
||||
|
||||
### Bugfixes
|
||||
|
||||
- Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
|
||||
- Removed: unused `.passive` toggle in navigation by [@pdmosses] in [#1335]
|
||||
|
||||
[#1335]: https://github.com/just-the-docs/just-the-docs/pull/1335
|
||||
[#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337
|
||||
|
||||
### New Contributors
|
||||
|
||||
- [@flanakin] made their first contribution in [#1337]
|
||||
|
||||
[@flanakin]: https://github.com/flanakin
|
||||
|
||||
## Release v0.6.1
|
||||
|
||||
Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation.
|
||||
|
||||
### Bugfixes
|
||||
|
||||
- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332]
|
||||
|
||||
[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332
|
||||
|
||||
## Release v0.6.0
|
||||
|
||||
Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
|
||||
|
||||
### Migrating to `v0.6.0`
|
||||
|
||||
**Migration**: users will need to migrate if:
|
||||
|
||||
- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid`
|
||||
- they have code that refers to `#main-content-wrap`
|
||||
- they override the default `light` theme's code, or the theme-loading logic
|
||||
- they have different favicons for different pages
|
||||
|
||||
For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
|
||||
|
||||
### Using Release `v0.6.0`
|
||||
|
||||
Users who have not pinned the theme version will be **automatically upgraded to `v0.6.0` the next time they build their site**.
|
||||
|
||||
To use this release explicitly as a remote theme:
|
||||
|
||||
```yml
|
||||
remote_theme: just-the-docs/just-the-docs@v0.6.0
|
||||
```
|
||||
|
||||
To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
|
||||
|
||||
```ruby
|
||||
gem "just-the-docs", "0.6.0"
|
||||
```
|
||||
|
||||
To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag.
|
||||
|
||||
### New Features and Bugfixes
|
||||
|
||||
- Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280]
|
||||
- Fixed: build times for large sites by [@pdmosses] in [#1244]
|
||||
- Fixed: missing closing `</button>` 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: <https://just-the-docs.com>. We've also retroactively published the theme docs website for version `v0.3.3` at <https://v0-3-3-docs.just-the-docs.com/>. Thank you to our GitHub sponsors for funding our domain name!
|
||||
|
||||
### Using Release `v0.5.2`
|
||||
|
||||
Users who have not pinned the theme version will be **automatically upgraded to `v0.5.2` the next time they build their site**.
|
||||
|
||||
To use this release explicitly as a remote theme:
|
||||
|
||||
```yml
|
||||
remote_theme: just-the-docs/just-the-docs@v0.5.2
|
||||
```
|
||||
|
||||
To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
|
||||
|
||||
```ruby
|
||||
gem "just-the-docs", "0.5.2"
|
||||
```
|
||||
|
||||
To use and pin a previous version of the theme, replace the `0.5.2` with the desired release tag.
|
||||
|
||||
### Bugfixes
|
||||
|
||||
- Fixed: liquid variable leakage in navigation components by [@pdmosses] in [#1243]
|
||||
- Fixed: ARIA roles and labels for search, header, logo, mobile menu button, and main content by [@joelhawksley] in [#1259]
|
||||
- Fixed: ARIA labels for all anchors with `href="#"`; adds `aria-pressed` information for toggles by [@mattxwang] in [#1262]
|
||||
|
||||
### New Contributors
|
||||
|
||||
- [@joelhawksley] made their first contribution in [#1259]
|
||||
|
||||
[@joelhawksley]: https://github.com/joelhawksley
|
||||
|
||||
[#1243]: https://github.com/just-the-docs/just-the-docs/pull/1243
|
||||
[#1259]: https://github.com/just-the-docs/just-the-docs/pull/1259
|
||||
[#1262]: https://github.com/just-the-docs/just-the-docs/pull/1262
|
||||
|
||||
## Release v0.5.1
|
||||
|
||||
Hi all, this is a very small minor patch release that has two small behavioral bugfixes: fixing a regression introduced in `v0.5.0` on Safari versions `<16.4` (broken media query), and the copy code button providing incorrect feedback in insecure browser contexts. This should be a smooth upgrade with no breaking changes.
|
||||
|
||||
As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
|
||||
|
||||
### Using Release `v0.5.1`
|
||||
|
||||
Users who have not pinned the theme version will be **automatically upgraded to `v0.5.1` the next time they build their site**.
|
||||
|
||||
To use this release explicitly as a remote theme:
|
||||
|
||||
```yml
|
||||
remote_theme: just-the-docs/just-the-docs@v0.5.1
|
||||
```
|
||||
|
||||
To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
|
||||
|
||||
```ruby
|
||||
gem "just-the-docs", "0.5.1"
|
||||
```
|
||||
|
||||
To use and pin a previous version of the theme, replace the `0.5.1` with the desired release tag.
|
||||
|
||||
### Bugfixes
|
||||
|
||||
|
||||
- Fixed: disable copy code button in insecure contexts [@rmoff] in [#1226]
|
||||
- Fixed: context-based media feature not supported by Safari `<16.4` by [@mattxwang] in [#1240]
|
||||
|
||||
### Documentation
|
||||
|
||||
- Added: document copy code button requiring secure context by [@rmoff] in [#1225]
|
||||
- Fixed: typo ("them" → "theme") in MIGRATION.md by [@waldyrious] in [#1219]
|
||||
- Fixed: `font-weight` typo (Utilities > Typography) by [@mattxwang] in [#1229]
|
||||
- Fixed: `just the docs` typo in migration guide by [@mattxwang] in [#1230]
|
||||
|
||||
### New Contributors
|
||||
- [@rmoff] made their first contribution in [#1225]
|
||||
|
||||
[#1219]: https://github.com/just-the-docs/just-the-docs/pull/1219
|
||||
[#1225]: https://github.com/just-the-docs/just-the-docs/pull/1225
|
||||
[#1226]: https://github.com/just-the-docs/just-the-docs/pull/1226
|
||||
[#1229]: https://github.com/just-the-docs/just-the-docs/pull/1229
|
||||
[#1230]: https://github.com/just-the-docs/just-the-docs/pull/1230
|
||||
[#1240]: https://github.com/just-the-docs/just-the-docs/pull/1240
|
||||
|
||||
[@rmoff]: https://github.com/rmoff
|
||||
|
||||
## Release v0.5.0
|
||||
|
||||
@ -38,7 +322,7 @@ As always, we'd love your feedback. [Open an issue](https://github.com/just-the-
|
||||
|
||||
**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves.
|
||||
|
||||
For more, refer to the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/).
|
||||
For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
|
||||
|
||||
### Using Release `v0.5.0`
|
||||
|
||||
@ -78,7 +362,7 @@ To use and pin a previous version of the theme, replace the `0.5.0` with the des
|
||||
|
||||
Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
|
||||
|
||||
The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.github.io/just-the-docs/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`.
|
||||
The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.com/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`.
|
||||
|
||||
As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
|
||||
|
||||
@ -179,16 +463,16 @@ We're so excited to release Just the Docs `v0.4.0`. This release has been almost
|
||||
`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes:
|
||||
|
||||
- better support for dark theme: dark highlighting, search input color
|
||||
- [callouts](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/), a new design component to highlight content
|
||||
- [configuring mermaid.js](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
|
||||
- [copy code button](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#copy-button) for code snippets
|
||||
- [external navigation links](https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#external-navigation-links)
|
||||
- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content
|
||||
- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
|
||||
- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets
|
||||
- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links)
|
||||
- major improvements to nav generation efficiency and robustness
|
||||
- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content)
|
||||
- [modularized site components](https://just-the-docs.github.io/just-the-docs/docs/customization/#custom-layouts-and-includes) (advanced feature)
|
||||
- [new custom includes](https://just-the-docs.github.io/just-the-docs/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices
|
||||
- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature)
|
||||
- [new custom includes](https://just-the-docs.com/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices
|
||||
- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more!
|
||||
- more documentation for [custom includes](https://just-the-docs.github.io/just-the-docs/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/)
|
||||
- more documentation for [custom includes](https://just-the-docs.com/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.com/MIGRATION/)
|
||||
|
||||
*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.*
|
||||
|
||||
@ -221,7 +505,7 @@ remote_theme: just-the-docs/just-the-docs@v0.3.3
|
||||
|
||||
### Migration Guide and Strategies
|
||||
|
||||
We've developed a new [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site.
|
||||
We've developed a new [migration guide](https://just-the-docs.com/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site.
|
||||
|
||||
**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes.
|
||||
|
||||
@ -429,7 +713,7 @@ This RC does not introduce any major user-facing features. It adds more customiz
|
||||
|
||||
### Trying out pre-release `v0.4.0.rc5`
|
||||
|
||||
Simlar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
|
||||
Similar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
|
||||
|
||||
To use this RC explicitly as a remote theme:
|
||||
|
||||
@ -530,7 +814,7 @@ Have any questions, thoughts, or concerns? We'd love to hear from you! Please [o
|
||||
|
||||
### Trying out pre-release `v0.4.0.rc4`
|
||||
|
||||
Simlar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
|
||||
Similar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
|
||||
|
||||
To use this RC explicitly as a remote theme:
|
||||
|
||||
@ -651,7 +935,7 @@ As soon as we get stable test results from major downstream users, we'll push ou
|
||||
|
||||
### Trying out pre-release `v0.4.0.rc3`
|
||||
|
||||
Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
|
||||
Similar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
|
||||
|
||||
To use this RC explicitly as a remote theme:
|
||||
|
||||
@ -727,7 +1011,7 @@ The intention of this release candidate is to gather even more feedback on a pot
|
||||
|
||||
### Trying out pre-release `v0.4.0.rc2`
|
||||
|
||||
Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
|
||||
Similar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
|
||||
|
||||
To use this RC explicitly as a remote theme:
|
||||
|
||||
@ -815,7 +1099,7 @@ We want your feedback! Are these changes helpful? Are our docs easy to understan
|
||||
|
||||
### Trying out pre-release `v0.4.0.rc1`
|
||||
|
||||
Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
|
||||
Due to the massive scope of these changes, we're making `v0.4.0.rc1` available as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
|
||||
|
||||
To use this RC explicitly as a remote theme:
|
||||
|
||||
@ -1327,7 +1611,7 @@ fixes #291 #256 #293 #177
|
||||
|
||||
## v0.2.1
|
||||
|
||||
This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
|
||||
This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
|
||||
|
||||
## v0.2.0
|
||||
|
||||
|
||||
4
Gemfile
4
Gemfile
@ -3,4 +3,6 @@ gemspec
|
||||
|
||||
gem "jekyll-github-metadata", ">= 2.15"
|
||||
|
||||
gem "webrick", "~> 1.7"
|
||||
gem "jekyll-include-cache", group: :jekyll_plugins
|
||||
|
||||
gem "html-proofer", "~> 5.0", :group => :development
|
||||
|
||||
150
Gemfile.lock
Normal file
150
Gemfile.lock
Normal file
@ -0,0 +1,150 @@
|
||||
PATH
|
||||
remote: .
|
||||
specs:
|
||||
just-the-docs (0.7.0)
|
||||
jekyll (>= 3.8.5)
|
||||
jekyll-include-cache
|
||||
jekyll-seo-tag (>= 2.0)
|
||||
rake (>= 12.3.1)
|
||||
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
Ascii85 (1.1.0)
|
||||
addressable (2.8.4)
|
||||
public_suffix (>= 2.0.2, < 6.0)
|
||||
afm (0.2.2)
|
||||
async (2.6.3)
|
||||
console (~> 1.10)
|
||||
fiber-annotation
|
||||
io-event (~> 1.1)
|
||||
timers (~> 4.1)
|
||||
colorator (1.1.0)
|
||||
concurrent-ruby (1.2.2)
|
||||
console (1.23.2)
|
||||
fiber-annotation
|
||||
fiber-local
|
||||
em-websocket (0.5.3)
|
||||
eventmachine (>= 0.12.9)
|
||||
http_parser.rb (~> 0)
|
||||
ethon (0.16.0)
|
||||
ffi (>= 1.15.0)
|
||||
eventmachine (1.2.7)
|
||||
faraday (2.7.10)
|
||||
faraday-net_http (>= 2.0, < 3.1)
|
||||
ruby2_keywords (>= 0.0.4)
|
||||
faraday-net_http (3.0.2)
|
||||
ffi (1.15.5)
|
||||
fiber-annotation (0.2.0)
|
||||
fiber-local (1.0.0)
|
||||
forwardable-extended (2.6.0)
|
||||
google-protobuf (3.23.4-arm64-darwin)
|
||||
google-protobuf (3.23.4-x86_64-linux)
|
||||
hashery (2.1.2)
|
||||
html-proofer (5.0.8)
|
||||
addressable (~> 2.3)
|
||||
async (~> 2.1)
|
||||
nokogiri (~> 1.13)
|
||||
pdf-reader (~> 2.11)
|
||||
rainbow (~> 3.0)
|
||||
typhoeus (~> 1.3)
|
||||
yell (~> 2.0)
|
||||
zeitwerk (~> 2.5)
|
||||
http_parser.rb (0.8.0)
|
||||
i18n (1.14.1)
|
||||
concurrent-ruby (~> 1.0)
|
||||
io-event (1.2.3)
|
||||
jekyll (4.3.2)
|
||||
addressable (~> 2.4)
|
||||
colorator (~> 1.0)
|
||||
em-websocket (~> 0.5)
|
||||
i18n (~> 1.0)
|
||||
jekyll-sass-converter (>= 2.0, < 4.0)
|
||||
jekyll-watch (~> 2.0)
|
||||
kramdown (~> 2.3, >= 2.3.1)
|
||||
kramdown-parser-gfm (~> 1.0)
|
||||
liquid (~> 4.0)
|
||||
mercenary (>= 0.3.6, < 0.5)
|
||||
pathutil (~> 0.9)
|
||||
rouge (>= 3.0, < 5.0)
|
||||
safe_yaml (~> 1.0)
|
||||
terminal-table (>= 1.8, < 4.0)
|
||||
webrick (~> 1.7)
|
||||
jekyll-github-metadata (2.16.0)
|
||||
jekyll (>= 3.4, < 5.0)
|
||||
octokit (>= 4, < 7, != 4.4.0)
|
||||
jekyll-include-cache (0.2.1)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-sass-converter (3.0.0)
|
||||
sass-embedded (~> 1.54)
|
||||
jekyll-seo-tag (2.8.0)
|
||||
jekyll (>= 3.8, < 5.0)
|
||||
jekyll-watch (2.2.1)
|
||||
listen (~> 3.0)
|
||||
kramdown (2.4.0)
|
||||
rexml
|
||||
kramdown-parser-gfm (1.1.0)
|
||||
kramdown (~> 2.0)
|
||||
liquid (4.0.4)
|
||||
listen (3.8.0)
|
||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
rb-inotify (~> 0.9, >= 0.9.10)
|
||||
mercenary (0.4.0)
|
||||
nokogiri (1.15.4-arm64-darwin)
|
||||
racc (~> 1.4)
|
||||
nokogiri (1.15.4-x86_64-linux)
|
||||
racc (~> 1.4)
|
||||
octokit (6.1.1)
|
||||
faraday (>= 1, < 3)
|
||||
sawyer (~> 0.9)
|
||||
pathutil (0.16.2)
|
||||
forwardable-extended (~> 2.6)
|
||||
pdf-reader (2.11.0)
|
||||
Ascii85 (~> 1.0)
|
||||
afm (~> 0.2.1)
|
||||
hashery (~> 2.0)
|
||||
ruby-rc4
|
||||
ttfunk
|
||||
public_suffix (5.0.3)
|
||||
racc (1.7.1)
|
||||
rainbow (3.1.1)
|
||||
rake (13.0.6)
|
||||
rb-fsevent (0.11.2)
|
||||
rb-inotify (0.10.1)
|
||||
ffi (~> 1.0)
|
||||
rexml (3.2.6)
|
||||
rouge (4.1.2)
|
||||
ruby-rc4 (0.1.5)
|
||||
ruby2_keywords (0.0.5)
|
||||
safe_yaml (1.0.5)
|
||||
sass-embedded (1.64.1-arm64-darwin)
|
||||
google-protobuf (~> 3.23)
|
||||
sass-embedded (1.64.1-x86_64-linux-gnu)
|
||||
google-protobuf (~> 3.23)
|
||||
sawyer (0.9.2)
|
||||
addressable (>= 2.3.5)
|
||||
faraday (>= 0.17.3, < 3)
|
||||
terminal-table (3.0.2)
|
||||
unicode-display_width (>= 1.1.1, < 3)
|
||||
timers (4.3.5)
|
||||
ttfunk (1.7.0)
|
||||
typhoeus (1.4.0)
|
||||
ethon (>= 0.9.0)
|
||||
unicode-display_width (2.4.2)
|
||||
webrick (1.8.1)
|
||||
yell (2.2.2)
|
||||
zeitwerk (2.6.11)
|
||||
|
||||
PLATFORMS
|
||||
arm64-darwin
|
||||
x86_64-linux
|
||||
|
||||
DEPENDENCIES
|
||||
bundler (>= 2.3.5)
|
||||
html-proofer (~> 5.0)
|
||||
jekyll-github-metadata (>= 2.15)
|
||||
jekyll-include-cache
|
||||
just-the-docs!
|
||||
|
||||
BUNDLED WITH
|
||||
2.4.13
|
||||
106
MIGRATION.md
106
MIGRATION.md
@ -43,11 +43,111 @@ This document contains instructions on how to migrate and upgrade Just the Docs
|
||||
|
||||
[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
|
||||
|
||||
## v0.6.x - v0.7.0
|
||||
|
||||
### POTENTIALLY-BREAKING CHANGES in v0.7.0
|
||||
|
||||
There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
|
||||
|
||||
1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html`
|
||||
- **explicit migration only necessary if users have overridden `_includes/nav.html`**
|
||||
2. the addition of `<script>` tags with `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet`
|
||||
- **explicit migration only necessary if users have existing elements with those IDs**
|
||||
|
||||
#### Moved Include
|
||||
|
||||
Version `v0.7.0` has moved (and changed the contents of) `_includes/nav.html`; it is now in `_includes/components/nav.html`. This means that user overrides for the component will *no longer be loaded*, reverting to the Just the Docs default.
|
||||
|
||||
Users who have overridden this `_includes` should:
|
||||
|
||||
1. copy in the new upstream `_includes/components/nav.html` into their site
|
||||
2. port over any changes from their custom `_includes/nav.html`
|
||||
|
||||
No other changes are necessary.
|
||||
|
||||
#### New Script IDs
|
||||
|
||||
Version `v0.7.0` adds the `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet` to some existing script tags. This will cause errors for users that have their own custom components with those IDs.
|
||||
|
||||
Users who have elements with those `id`s should rename their elements to avoid a collision.
|
||||
|
||||
## v0.5.x - v0.6.0
|
||||
|
||||
### POTENTIALLY-BREAKING CHANGES in v0.6.0
|
||||
|
||||
There are some *very minor* potentially-breaking changes for users in version `v0.6.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
|
||||
|
||||
1. the addition of new `_includes/favicon.html`, `_includes/head_nav.html`, and `_includes/css/activation.scss.liquid`
|
||||
- **explicit migration only necessary if users have defined a custom file with the same name**
|
||||
2. removing `id="main-content-wrap` from wrapper `div` elements in default layouts
|
||||
- **explicit migration only necessary if users have written code that depends on `#main-content-wrap`**
|
||||
3. loading the new `$color-scheme` variable (from the light scheme by default)
|
||||
- **explicit migration only necessary if users have overridden the base light theme**
|
||||
4. caching the favicon for the entire site
|
||||
- **explicit migration only necessary if users have different favicons for different pages**
|
||||
|
||||
#### New Includes
|
||||
|
||||
Version `v0.6.0` introduces three new `_includes` files:
|
||||
|
||||
- `_includes/favicon.html`, which now contains logic previously in `_includes/head.html`: loading `favicon.ico` if no favicon is specified
|
||||
- `_includes/head_nav.html`, which generates CSS used for the new efficient navigation implementation
|
||||
- `_includes/css/activation.scss.liquid`, which is used by `head_nav` for navigation implementation
|
||||
|
||||
If users have existing `_includes` files with this name, they should be renamed (and imported with their new name) prior to upgrading to `0.6.0`. No other change is necessary.
|
||||
|
||||
#### Removed `#main-content-wrap`
|
||||
|
||||
In `_layouts/default.html` and `_layouts/minimal.html`, the `id="main-content-wrap"` has been removed from the wrapper div (in part due to a bug with multiple `id`s on one element). Internally, our theme *does not use* these `id`s; for most users, this does not require any action.
|
||||
|
||||
However, code that relies on this `id` must be changed. Each of the related elements still has the unique class `.main-content-wrap`, and can be selected with this class. For example, in CSS:
|
||||
|
||||
```css
|
||||
/* OLD */
|
||||
#main-content-wrap { /* ... */ }
|
||||
|
||||
/* NEW */
|
||||
.main-content-wrap { /* ... */ }
|
||||
```
|
||||
|
||||
Or in JS:
|
||||
|
||||
```js
|
||||
// OLD
|
||||
document.getElementById("main-content-wrap");
|
||||
|
||||
// NEW
|
||||
document.getElementsByClassName("main-content-wrap")[0];
|
||||
```
|
||||
|
||||
#### New `$color-scheme` variable
|
||||
|
||||
The theme now properly sets the `color-scheme` property. To do so, the new `$color-scheme` SCSS variable has been created. The variable has been added to the default `light` scheme, which is *always* loaded by Just the Docs.
|
||||
|
||||
Migration is only needed if:
|
||||
|
||||
- the packaged `light` scheme has been *overridden* (this is *not* the same as using a custom scheme)
|
||||
- or, the scheme logic to always load `light` has been changed
|
||||
|
||||
(neither of these behaviours are recommended by Just the Docs)
|
||||
|
||||
In either of these cases, users should add a `$color-scheme` SCSS variable to their active scheme with the appropriate value (see: [MDN docs on `color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)).
|
||||
|
||||
```scss
|
||||
$color-scheme: light !default;
|
||||
```
|
||||
|
||||
#### Cached favicon
|
||||
|
||||
Version `v0.6.0` adds a new `_include` that caches the favicon for the entire site. This significantly improves page build times for large sites.
|
||||
|
||||
However, some users may load different favicons for each page (and/or dynamically change the first favicon load). In this case, they should override the logic in `_includes/favicon.html` by **replacing** it with an empty file (this is *different* from deleting it). No further migration is necessary.
|
||||
|
||||
## v0.4.x - v0.5.0
|
||||
|
||||
### POTENTIALLY-BREAKING CHANGES in v0.5.0
|
||||
|
||||
There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context:
|
||||
There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concerning `setup.scss`. To provide context:
|
||||
|
||||
1. `setup.scss` was introduced in `v0.4.0`
|
||||
2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code
|
||||
@ -71,7 +171,7 @@ For those users, we suggest moving those variables and functions to each relevan
|
||||
The theme repo is now at <https://github.com/just-the-docs/just-the-docs>.
|
||||
The name of its default branch is now `main`.
|
||||
|
||||
The theme docs website is now published at <https://just-the-docs.github.io/just-the-docs>.
|
||||
The theme docs website is now published at <https://just-the-docs.github.io/just-the-docs>. We've also retroactively published the theme docs website for version `v0.3.3` at <https://v0-3-3-docs.just-the-docs.com/>.
|
||||
|
||||
GitHub provides access to previous versions of the theme repo.
|
||||
You can browse [previous versions of the theme docs website] on the [Internet Archive].
|
||||
@ -84,7 +184,7 @@ formatted for browsing on GitHub.
|
||||
It also explains how to install the theme as a Ruby Gem, without creating a new site.
|
||||
|
||||
[README]: https://github.com/just-the-docs/just-the-docs/blob/main/README.md
|
||||
[home page]: https://just-the-docs.github.io/just-the-docs
|
||||
[home page]: https://just-the-docs.com
|
||||
|
||||
#### Deploy previews
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
<p align="center">
|
||||
<h1 align="center">Just the Docs</h1>
|
||||
<p align="center">A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
|
||||
<p align="center"><strong><a href="https://just-the-docs.github.io/just-the-docs/">See it in action!</a></strong></p>
|
||||
<p align="center"><strong><a href="https://just-the-docs.com/">See it in action!</a></strong></p>
|
||||
<br><br><br>
|
||||
</p>
|
||||
|
||||
@ -102,7 +102,7 @@ The theme is available as open source under the terms of the [MIT License](http:
|
||||
|
||||
[Jekyll]: https://jekyllrb.com
|
||||
[Just the Docs Template]: https://just-the-docs.github.io/just-the-docs-template/
|
||||
[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
|
||||
[Just the Docs]: https://just-the-docs.com
|
||||
[Just the Docs repo]: https://github.com/just-the-docs/just-the-docs
|
||||
[GitHub Pages]: https://pages.github.com/
|
||||
[Template README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md
|
||||
|
||||
@ -15,8 +15,8 @@
|
||||
# in the templates via {{ site.myvariable }}.
|
||||
title: Just the Docs
|
||||
description: A Jekyll theme for documentation
|
||||
baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
|
||||
url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
baseurl: "" # the subpath of your site, e.g. /blog
|
||||
url: "https://just-the-docs.com" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
repository: just-the-docs/just-the-docs # for github-metadata
|
||||
|
||||
permalink: pretty
|
||||
@ -102,7 +102,7 @@ heading_anchors: true
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/just-the-docs/just-the-docs"
|
||||
- "https://github.com/just-the-docs/just-the-docs"
|
||||
|
||||
# Makes Aux links open in a new tab. Default is false
|
||||
aux_links_new_tab: false
|
||||
@ -168,6 +168,7 @@ callouts:
|
||||
plugins:
|
||||
- jekyll-seo-tag
|
||||
- jekyll-github-metadata
|
||||
- jekyll-include-cache
|
||||
|
||||
kramdown:
|
||||
syntax_highlighter_opts:
|
||||
|
||||
@ -1,15 +1,51 @@
|
||||
{% unless page.url == "/" %}
|
||||
{% if page.parent %}
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.grand_parent %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
|
||||
{% else %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
|
||||
{% endif %}
|
||||
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
|
||||
</ol>
|
||||
</nav>
|
||||
{% endif %}
|
||||
{% endunless %}
|
||||
{%- comment -%}
|
||||
Include as: {%- include components/breadcrumbs.html -%}
|
||||
Depends on: page, site.
|
||||
Results in: HTML for the breadcrumbs component.
|
||||
Overwrites:
|
||||
node, pages_list, parent_page, grandparent_page.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- if page.url != "/" and page.parent -%}
|
||||
|
||||
{%- assign pages_list = site[page.collection] | default: site.html_pages -%}
|
||||
|
||||
{%- assign parent_page = nil -%}
|
||||
{%- assign grandparent_page = nil -%}
|
||||
|
||||
{%- for node in pages_list -%}
|
||||
|
||||
{%- if node.has_children and page.grand_parent -%}
|
||||
|
||||
{%- if node.title == page.parent and node.parent == page.grand_parent -%}
|
||||
{%- assign parent_page = node -%}
|
||||
{%- endif -%}
|
||||
{%- if node.title == page.grand_parent -%}
|
||||
{%- assign grandparent_page = node -%}
|
||||
{%- endif -%}
|
||||
{%- if parent_page and grandparent_page -%}
|
||||
{%- break -%}
|
||||
{%- endif -%}
|
||||
|
||||
{%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
|
||||
|
||||
{%- assign parent_page = node -%}
|
||||
{%- break -%}
|
||||
|
||||
{%- endif -%}
|
||||
|
||||
{%- endfor -%}
|
||||
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.parent -%}
|
||||
{%- if page.grand_parent %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a></li>
|
||||
{%- endif %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a></li>
|
||||
{% endif -%}
|
||||
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
|
||||
</ol>
|
||||
</nav>
|
||||
|
||||
{%- endif -%}
|
||||
|
||||
@ -1,9 +1,33 @@
|
||||
{%- comment -%}
|
||||
Include as: {%- include components/children_nav.html -%}
|
||||
Depends on: page, site.
|
||||
Results in: HTML for the children-navigation component.
|
||||
Includes:
|
||||
sorted_pages.html
|
||||
toc_heading_custom.html
|
||||
Overwrites:
|
||||
child_pages.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- if page.has_children == true and page.has_toc != false -%}
|
||||
{%- assign child_pages = site[page.collection]
|
||||
| default: site.html_pages
|
||||
| where: "parent", page.title
|
||||
| where: "grand_parent", page.parent -%}
|
||||
|
||||
{%- include sorted_pages.html pages = child_pages -%}
|
||||
|
||||
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
|
||||
{%- assign sorted_pages = sorted_pages | reverse -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
|
||||
<hr>
|
||||
{% include toc_heading_custom.html %}
|
||||
<ul>
|
||||
{% for child in include.toc_list %}
|
||||
<li>
|
||||
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
{% for child in sorted_pages %}
|
||||
<li>
|
||||
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
75
_includes/components/nav.html
Normal file
75
_includes/components/nav.html
Normal file
@ -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" -%}
|
||||
|
||||
<ul class="nav-list">
|
||||
{%- for node in first_level_pages -%}
|
||||
<li class="nav-list-item">
|
||||
{%- if node.has_children -%}
|
||||
<button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
|
||||
<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
|
||||
</button>
|
||||
{%- endif -%}
|
||||
<a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = second_level_pages
|
||||
| where: "parent", node.title -%}
|
||||
{%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
|
||||
{%- assign children_list = children_list | reverse -%}
|
||||
{%- endif -%}
|
||||
<ul class="nav-list">
|
||||
{%- for child in children_list -%}
|
||||
<li class="nav-list-item">
|
||||
{%- if child.has_children -%}
|
||||
<button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="false">
|
||||
<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
|
||||
</button>
|
||||
{%- endif -%}
|
||||
<a href="{{ child.url | relative_url }}" class="nav-list-link">{{ child.title }}</a>
|
||||
{%- if child.has_children -%}
|
||||
{%- assign grand_children_list = third_level_pages
|
||||
| where: "parent", child.title
|
||||
| where: "grand_parent", node.title -%}
|
||||
{%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
|
||||
{%- assign grand_children_list = grand_children_list | reverse -%}
|
||||
{%- endif -%}
|
||||
<ul class="nav-list">
|
||||
{%- for grand_child in grand_children_list -%}
|
||||
<li class="nav-list-item">
|
||||
<a href="{{ grand_child.url | relative_url }}" class="nav-list-link">{{ grand_child.title }}</a>
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
@ -1,7 +1,7 @@
|
||||
{% if site.search.button %}
|
||||
<a href="#" id="search-button" class="search-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
|
||||
</a>
|
||||
<button id="search-button" class="search-button btn-reset" aria-label="Focus on search">
|
||||
<svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-search"></use></svg>
|
||||
</button>
|
||||
{% endif %}
|
||||
|
||||
<div class="search-overlay"></div>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
|
||||
|
||||
<div class="search">
|
||||
<div class="search" role="search">
|
||||
<div class="search-input-wrap">
|
||||
<input type="text" id="search-input" class="search-input" tabindex="0" placeholder="{{ search_placeholder | strip_html | strip }}" aria-label="{{ search_placeholder | strip_html| strip }}" autocomplete="off">
|
||||
<label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
|
||||
|
||||
@ -1,60 +1,23 @@
|
||||
{%- 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 -%}
|
||||
|
||||
<div class="side-bar">
|
||||
<div class="site-header">
|
||||
<div class="site-header" role="banner">
|
||||
<a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
|
||||
<a href="#" id="menu-button" class="site-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
|
||||
</a>
|
||||
<button id="menu-button" class="site-button btn-reset" aria-label="Toggle menu" aria-pressed="false">
|
||||
<svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
|
||||
</button>
|
||||
</div>
|
||||
<nav aria-label="Main" id="site-nav" class="site-nav">
|
||||
{% assign pages_top_size = site.html_pages
|
||||
| where_exp:"item", "item.title != nil"
|
||||
| where_exp:"item", "item.parent == nil"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include nav.html pages=site.html_pages key=nil %}
|
||||
{% endif %}
|
||||
{%- if site.nav_external_links -%}
|
||||
<ul class="nav-list">
|
||||
{%- for node in site.nav_external_links -%}
|
||||
<li class="nav-list-item external">
|
||||
<a href="{{ node.url | absolute_url }}" class="nav-list-link external">
|
||||
{{ node.title }}
|
||||
{% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
|
||||
</a>
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 or pages_top_size > 0 %}
|
||||
{% if collection_value.nav_fold == true %}
|
||||
<ul class="nav-list nav-category-list">
|
||||
<li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
|
||||
{%- if collection.size > 0 -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
</li>
|
||||
</ul>
|
||||
{% else %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% else %}
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
|
||||
{% include_cached components/site_nav.html %}
|
||||
|
||||
{% capture nav_footer_custom %}
|
||||
{%- include nav_footer_custom.html -%}
|
||||
|
||||
67
_includes/components/site_nav.html
Normal file
67
_includes/components/site_nav.html
Normal file
@ -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 -%}
|
||||
|
||||
<nav aria-label="Main" id="site-nav" class="site-nav">
|
||||
{% assign pages_top_size = site.html_pages
|
||||
| where_exp:"item", "item.title != nil"
|
||||
| where_exp:"item", "item.parent == nil"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include components/nav.html pages=site.html_pages %}
|
||||
{% endif %}
|
||||
{%- if site.nav_external_links -%}
|
||||
<ul class="nav-list">
|
||||
{%- for node in site.nav_external_links -%}
|
||||
<li class="nav-list-item external">
|
||||
<a href="{{ node.url | absolute_url }}" class="nav-list-link external"
|
||||
{% if node.opens_in_new_tab or node.opens_in_new_tab == nil and site.nav_external_links_new_tab %}
|
||||
target="_blank" rel="noopener noreferrer"
|
||||
{% endif %}
|
||||
>
|
||||
{{ node.title }}
|
||||
{% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
|
||||
</a>
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 or pages_top_size > 0 %}
|
||||
{% if collection_value.nav_fold == true %}
|
||||
<ul class="nav-list nav-category-list">
|
||||
<li class="nav-list-item">
|
||||
{%- if collection.size > 0 -%}
|
||||
<button class="nav-list-expander btn-reset" aria-label="Toggle collection {{ collection_value.name }}" aria-pressed="false">
|
||||
<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
|
||||
</button>
|
||||
{%- endif -%}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include components/nav.html pages=collection %}
|
||||
</li>
|
||||
</ul>
|
||||
{% else %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include components/nav.html pages=collection %}
|
||||
{% endif %}
|
||||
{% else %}
|
||||
{% include components/nav.html pages=collection %}
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
281
_includes/css/activation.scss.liquid
Normal file
281
_includes/css/activation.scss.liquid
Normal file
@ -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 -%}
|
||||
23
_includes/favicon.html
Normal file
23
_includes/favicon.html
Normal file
@ -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 %}
|
||||
<link rel="icon" href="{{ site.favicon_ico | default: '/favicon.ico' | relative_url }}" type="image/x-icon">
|
||||
{% endif %}
|
||||
@ -1,9 +1,27 @@
|
||||
{%- 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 -%}
|
||||
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
|
||||
|
||||
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
|
||||
|
||||
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-head-nav.css' | relative_url }}" id="jtd-head-nav-stylesheet">
|
||||
|
||||
<style id="jtd-nav-activation">
|
||||
{% include css/activation.scss.liquid %}
|
||||
</style>
|
||||
|
||||
{% if site.ga_tracking != nil %}
|
||||
{% assign ga_tracking_ids = site.ga_tracking | split: "," %}
|
||||
<script async src="https://www.googletagmanager.com/gtag/js?id={{ ga_tracking_ids.first }}"></script>
|
||||
@ -26,14 +44,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
|
||||
{% for file in site.static_files %}
|
||||
{% if file.path == site.favicon_ico or file.path == '/favicon.ico' %}
|
||||
{% assign favicon = true %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% if favicon %}
|
||||
<link rel="icon" href="{{ site.favicon_ico | default: '/favicon.ico' | relative_url }}" type="image/x-icon">
|
||||
{% endif %}
|
||||
{% include_cached favicon.html %}
|
||||
|
||||
{% seo %}
|
||||
|
||||
|
||||
@ -1,251 +0,0 @@
|
||||
{%- comment -%}
|
||||
The `nav_order` values of pages affect the order in which they are shown in
|
||||
the navigation panel and in the automatically generated tables of contents.
|
||||
Sibling pages with the same `nav_order` value may be shown in any order.
|
||||
Sibling pages with no `nav_order` value are shown after all pages that have
|
||||
explicit `nav_order` values, ordered by their `title` values.
|
||||
|
||||
The `nav_order` and `title` values can be numbers or strings. To avoid build
|
||||
failures, we sort numbers and strings separately. We sort numbers by their
|
||||
values, and strings lexicographically. The case-sensitivity of string sorting
|
||||
is determined by the configuration setting of `nav_sort`. Pages with no `title`
|
||||
value are excluded from the navigation.
|
||||
|
||||
Note: Numbers used as `title` or `nav_order` values should not be in quotes,
|
||||
unless you intend them to be lexicographically ordered. Numbers are written
|
||||
without spaces or thousands-separators. Negative numbers are preceded by `-`.
|
||||
Floats are written with the integral and fractional parts separated by `.`.
|
||||
(Bounds on the magnitude and precision are presumably the same as in Liquid.)
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- assign title_pages = include.pages
|
||||
| where_exp: "item", "item.title != nil" -%}
|
||||
|
||||
{%- comment -%}
|
||||
A page with `nav_exclude: true` does not appear in the main navigation.
|
||||
If it has a `parent`, it may appear in the parent's table of contents.
|
||||
If it specifies `has_children: true`, it should appear in the breadcrumbs
|
||||
of the child pages, but its order in relation to other pages is irrelevant.
|
||||
Pages that never appear can be removed from the pages that need to be sorted.
|
||||
This optimisation can be significant on a site with many pages.
|
||||
|
||||
In Jekyll 4, the pages to be sorted can be filtered by:
|
||||
|
||||
{%- assign title_pages = title_pages
|
||||
| where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
|
||||
|
||||
That filter is not allowed in Jekyll 3. The following iterative code gives the
|
||||
same effect, but it is activated only when it will filter more than 50% of the
|
||||
pages.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- unless title_pages == empty -%}
|
||||
{%- assign unsorted_pages = title_pages
|
||||
| where_exp: "item", "item.parent == nil"
|
||||
| where_exp: "item", "item.nav_exclude == true" -%}
|
||||
{%- assign title_pages_size = title_pages.size -%}
|
||||
{%- assign unsorted_pages_percent = unsorted_pages.size
|
||||
| times: 100 | divided_by: title_pages_size -%}
|
||||
{%- if unsorted_pages_percent > 50 -%}
|
||||
{%- assign sorted_pages = "" | split: "" -%}
|
||||
{%- for item in title_pages -%}
|
||||
{%- if item.nav_exclude != true or item.parent -%}
|
||||
{%- assign sorted_pages = sorted_pages | push: item -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- assign title_pages = sorted_pages -%}
|
||||
{%- endif -%}
|
||||
{%- endunless -%}
|
||||
|
||||
{%- assign nav_order_pages = title_pages
|
||||
| where_exp: "item", "item.nav_order != nil" -%}
|
||||
{%- assign title_order_pages = title_pages
|
||||
| where_exp: "item", "item.nav_order == nil" -%}
|
||||
|
||||
{%- comment -%}
|
||||
Divide the arrays of `nav_order_pages` and `title_order_pages` according to
|
||||
the type of value.
|
||||
|
||||
The first character of the result of `jsonify` is `"` only for strings.
|
||||
Grouping by a single character also ensures the number of groups is small.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- assign nav_number_pages = "" | split: "" -%}
|
||||
{%- assign nav_string_pages = "" | split: "" -%}
|
||||
{%- assign nav_order_groups = nav_order_pages
|
||||
| group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
|
||||
{%- for group in nav_order_groups -%}
|
||||
{%- if group.name == '"' -%}
|
||||
{%- assign nav_string_pages = group.items -%}
|
||||
{%- else -%}
|
||||
{%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{%- unless nav_number_pages == empty -%}
|
||||
{%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
|
||||
{%- endunless -%}
|
||||
|
||||
{%- unless nav_string_pages == empty -%}
|
||||
{%- if site.nav_sort == 'case_insensitive' -%}
|
||||
{%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
|
||||
{%- else -%}
|
||||
{%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
|
||||
{%- endif -%}
|
||||
{%- endunless -%}
|
||||
|
||||
{%- assign title_number_pages = "" | split: "" -%}
|
||||
{%- assign title_string_pages = "" | split: "" -%}
|
||||
{%- assign title_order_groups = title_order_pages
|
||||
| group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
|
||||
{%- for group in title_order_groups -%}
|
||||
{%- if group.name == '"' -%}
|
||||
{%- assign title_string_pages = group.items -%}
|
||||
{%- else -%}
|
||||
{%- assign title_number_pages = title_number_pages | concat: group.items -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{%- unless title_number_pages == empty -%}
|
||||
{%- assign title_number_pages = title_number_pages | sort: "title" -%}
|
||||
{%- endunless -%}
|
||||
|
||||
{%- unless title_string_pages == empty -%}
|
||||
{%- if site.nav_sort == 'case_insensitive' -%}
|
||||
{%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
|
||||
{%- else -%}
|
||||
{%- assign title_string_pages = title_string_pages | sort: "title" -%}
|
||||
{%- endif -%}
|
||||
{%- endunless -%}
|
||||
|
||||
{%- assign pages_list = nav_number_pages | concat: nav_string_pages
|
||||
| concat: title_number_pages | concat: title_string_pages -%}
|
||||
|
||||
{%- assign first_level_pages = pages_list
|
||||
| where_exp: "item", "item.parent == nil" -%}
|
||||
{%- assign second_level_pages = pages_list
|
||||
| where_exp: "item", "item.parent != nil"
|
||||
| where_exp: "item", "item.grand_parent == nil" -%}
|
||||
{%- assign third_level_pages = pages_list
|
||||
| where_exp: "item", "item.grand_parent != nil" -%}
|
||||
|
||||
{%- comment -%}
|
||||
The order of sibling pages in `pages_list` determines the order of display of
|
||||
links to them in lists of navigation links and in auto-generated TOCs.
|
||||
|
||||
Note that Liquid evaluates conditions from right to left (and it does not allow
|
||||
the use of parentheses). Some conditions are not so easy to express clearly...
|
||||
|
||||
For example, consider the following condition:
|
||||
|
||||
C: page.collection = = include.key and
|
||||
page.url = = node.url or
|
||||
page.grand_parent = = node.title or
|
||||
page.parent = = node.title and
|
||||
page.grand_parent = = nil
|
||||
|
||||
Here, `node` is a first-level page. The last part of the condition
|
||||
-- namely: `page.parent = = node.title and page.grand_parent = = nil` --
|
||||
is evaluated first; it holds if and only if `page` is a child of `node`.
|
||||
|
||||
The condition `page.grand_parent = = node.title or ...` holds when
|
||||
`page` is a grandchild of node, OR `...` holds.
|
||||
|
||||
The condition `page.url = = node.url or ...` holds when
|
||||
`page` is `node`, OR `...` holds.
|
||||
|
||||
The condition C: `page.collection = = include.key and ...` holds when we are
|
||||
generating the nav links for a collection that includes `page`, AND `...` holds.
|
||||
{%- endcomment -%}
|
||||
|
||||
<ul class="nav-list">
|
||||
{%- for node in first_level_pages -%}
|
||||
{%- unless node.nav_exclude -%}
|
||||
<li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %} active{% endif %}">
|
||||
{%- if node.has_children -%}
|
||||
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
|
||||
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
|
||||
</a>
|
||||
{%- endif -%}
|
||||
<a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = second_level_pages
|
||||
| where: "parent", node.title -%}
|
||||
{%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
|
||||
{%- assign children_list = children_list | reverse -%}
|
||||
{%- endif -%}
|
||||
<ul class="nav-list">
|
||||
{%- for child in children_list -%}
|
||||
{%- unless child.nav_exclude -%}
|
||||
<li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
|
||||
{%- if child.has_children -%}
|
||||
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ child.title }} category">
|
||||
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
|
||||
</a>
|
||||
{%- endif -%}
|
||||
<a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
|
||||
{%- if child.has_children -%}
|
||||
{%- assign grand_children_list = third_level_pages
|
||||
| where: "parent", child.title
|
||||
| where: "grand_parent", node.title -%}
|
||||
{%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
|
||||
{%- assign grand_children_list = grand_children_list | reverse -%}
|
||||
{%- endif -%}
|
||||
<ul class="nav-list">
|
||||
{%- for grand_child in grand_children_list -%}
|
||||
{%- unless grand_child.nav_exclude -%}
|
||||
<li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
|
||||
<a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
|
||||
{%- comment -%}
|
||||
`page.collection` is the name of the Jekyll collection that contains the page,
|
||||
if any, and otherwise nil. Similarly for `include.key`.
|
||||
|
||||
If the current page is in the collection (if any) whose navigation is currently
|
||||
being generated, the following code sets `first_level_url` to the URL used in
|
||||
the page's top-level breadcrumb (if any), and `second_level_url` to that used
|
||||
in the page's second-level breadcrumb (if any).
|
||||
|
||||
For pages with children, the code also sets `toc_list` to the list of child pages,
|
||||
reversing the order if needed.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- if page.collection == include.key -%}
|
||||
{%- for node in first_level_pages -%}
|
||||
{%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%}
|
||||
{%- assign first_level_url = node.url | relative_url -%}
|
||||
{%- endif -%}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = second_level_pages | where: "parent", node.title -%}
|
||||
{%- for child in children_list -%}
|
||||
{%- if child.has_children -%}
|
||||
{%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
|
||||
{%- assign second_level_url = child.url | relative_url -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- if page.has_children == true and page.has_toc != false -%}
|
||||
{%- assign toc_list = pages_list
|
||||
| where: "parent", page.title
|
||||
| where_exp: "item", "item.grand_parent == page.parent" -%}
|
||||
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
|
||||
{%- assign toc_list = toc_list | reverse -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
109
_includes/sorted_pages.html
Normal file
109
_includes/sorted_pages.html
Normal file
@ -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 -%}
|
||||
@ -1,5 +1,5 @@
|
||||
{% if site.logo %}
|
||||
<div class="site-logo"></div>
|
||||
<div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
|
||||
{% else %}
|
||||
{{ site.title }}
|
||||
{% endif %}
|
||||
|
||||
@ -12,21 +12,21 @@ layout: table_wrappers
|
||||
{% include components/sidebar.html %}
|
||||
<div class="main" id="top">
|
||||
{% include components/header.html %}
|
||||
<div id="main-content-wrap" class="main-content-wrap">
|
||||
<div class="main-content-wrap">
|
||||
{% include components/breadcrumbs.html %}
|
||||
<div id="main-content" class="main-content" role="main">
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
|
||||
{% else %}
|
||||
{{ content }}
|
||||
{% endif %}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
{% include components/children_nav.html toc_list=toc_list %}
|
||||
{% endif %}
|
||||
<div id="main-content" class="main-content">
|
||||
<main>
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" 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 %}
|
||||
</main>
|
||||
{% include components/footer.html %}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
{% if site.search_enabled != false %}
|
||||
|
||||
@ -9,33 +9,7 @@ layout: table_wrappers
|
||||
<body>
|
||||
<a class="skip-to-main" href="#main-content">Skip to main content</a>
|
||||
{% include icons/icons.html %}
|
||||
{% comment %}
|
||||
This is a bandaid fix to properly render breadcrumbs; as of now, there is some variable leakage between the sidebar component (which computes parents, grandparents) and the breadcrumbs component. We plan to remove this in a future release to deduplicate code.
|
||||
|
||||
For more context, see https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057014053
|
||||
{% endcomment %}
|
||||
{% capture nav %}
|
||||
{% assign pages_top_size = site.html_pages
|
||||
| where_exp:"item", "item.title != nil"
|
||||
| where_exp:"item", "item.parent == nil"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include nav.html pages=site.html_pages key=nil %}
|
||||
{% endif %}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
{% endcapture %}
|
||||
<div id="main-content-wrap" class="main-content-wrap" id="top">
|
||||
<div class="main-content-wrap" id="top">
|
||||
{% include components/breadcrumbs.html %}
|
||||
<div id="main-content" class="main-content" role="main">
|
||||
{% if site.heading_anchors != false %}
|
||||
@ -45,7 +19,7 @@ layout: table_wrappers
|
||||
{% endif %}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
{% include components/children_nav.html toc_list=toc_list %}
|
||||
{% include components/children_nav.html %}
|
||||
{% endif %}
|
||||
|
||||
{% include components/footer.html %}
|
||||
|
||||
@ -1,6 +1,10 @@
|
||||
// Base element style overrides
|
||||
// stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
|
||||
|
||||
:root {
|
||||
color-scheme: $color-scheme;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
@ -104,6 +108,6 @@ blockquote {
|
||||
// resets user-agent stylesheets for blockquotes
|
||||
margin-block-start: 0;
|
||||
margin-inline-start: 0;
|
||||
padding-left: 15px;
|
||||
padding-left: 1rem;
|
||||
border-left: 3px solid $border-color;
|
||||
}
|
||||
|
||||
@ -17,7 +17,9 @@
|
||||
background-color: $base-button-color;
|
||||
border-width: 0;
|
||||
border-radius: $border-radius;
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
appearance: none;
|
||||
|
||||
&:focus {
|
||||
@ -87,7 +89,9 @@
|
||||
&:focus {
|
||||
text-decoration: none;
|
||||
outline: none;
|
||||
box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25);
|
||||
box-shadow:
|
||||
inset 0 0 0 2px $grey-dk-100,
|
||||
0 0 0 3px rgba(blue, 0.25);
|
||||
}
|
||||
|
||||
&:focus:hover,
|
||||
@ -111,3 +115,13 @@
|
||||
.btn-green {
|
||||
@include btn-color($white, $green-100);
|
||||
}
|
||||
|
||||
.btn-reset {
|
||||
background: none;
|
||||
border: none;
|
||||
margin: 0;
|
||||
text-align: inherit;
|
||||
font: inherit;
|
||||
border-radius: 0;
|
||||
appearance: none;
|
||||
}
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
$color-scheme: dark;
|
||||
$body-background-color: $grey-dk-300;
|
||||
$body-heading-color: $grey-lt-000;
|
||||
$body-text-color: $grey-lt-300;
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
$color-scheme: light !default;
|
||||
$body-background-color: $white !default;
|
||||
$body-heading-color: $grey-dk-300 !default;
|
||||
$body-text-color: $grey-dk-100 !default;
|
||||
|
||||
@ -1,7 +1,11 @@
|
||||
// Labels (not the form kind)
|
||||
|
||||
.label,
|
||||
.label-blue {
|
||||
// this :not() prevents a style clash with Mermaid.js's
|
||||
// diagram labels, which also use .label
|
||||
// for more, see https://github.com/just-the-docs/just-the-docs/issues/1272
|
||||
// and the accompanying PR
|
||||
.label:not(g),
|
||||
.label-blue:not(g) {
|
||||
display: inline-block;
|
||||
padding: 0.16em 0.56em;
|
||||
margin-right: $sp-2;
|
||||
@ -15,19 +19,19 @@
|
||||
border-radius: 12px;
|
||||
}
|
||||
|
||||
.label-green {
|
||||
.label-green:not(g) {
|
||||
background-color: $green-200;
|
||||
}
|
||||
|
||||
.label-purple {
|
||||
.label-purple:not(g) {
|
||||
background-color: $purple-100;
|
||||
}
|
||||
|
||||
.label-red {
|
||||
.label-red:not(g) {
|
||||
background-color: $red-200;
|
||||
}
|
||||
|
||||
.label-yellow {
|
||||
.label-yellow:not(g) {
|
||||
color: $grey-dk-200;
|
||||
background-color: $yellow-200;
|
||||
}
|
||||
|
||||
@ -21,7 +21,7 @@
|
||||
}
|
||||
|
||||
.site-title {
|
||||
font-size: $root-font-size !important;
|
||||
font-size: 1rem !important;
|
||||
font-weight: 700 !important;
|
||||
}
|
||||
|
||||
|
||||
@ -23,7 +23,9 @@
|
||||
height: $sp-8;
|
||||
overflow: hidden;
|
||||
border-radius: $border-radius;
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
transition: height linear #{$transition-duration * 0.5};
|
||||
|
||||
@include mq(md) {
|
||||
@ -42,7 +44,7 @@
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
|
||||
font-size: 16px;
|
||||
font-size: 1rem;
|
||||
color: $body-text-color;
|
||||
background-color: $search-background-color;
|
||||
border-top: 0;
|
||||
@ -53,7 +55,7 @@
|
||||
|
||||
@include mq(md) {
|
||||
padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5};
|
||||
font-size: 14px;
|
||||
font-size: 0.875rem;
|
||||
background-color: $body-background-color;
|
||||
transition: padding-left linear #{$transition-duration * 0.5};
|
||||
}
|
||||
@ -96,7 +98,9 @@
|
||||
background-color: $search-background-color;
|
||||
border-bottom-right-radius: $border-radius;
|
||||
border-bottom-left-radius: $border-radius;
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
|
||||
@include mq(md) {
|
||||
top: 100%;
|
||||
@ -230,7 +234,9 @@
|
||||
background-color: $search-background-color;
|
||||
border: 1px solid rgba($link-color, 0.3);
|
||||
border-radius: #{$sp-9 * 0.5};
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
@ -244,7 +250,9 @@
|
||||
height: 0;
|
||||
background-color: rgba(0, 0, 0, 0.3);
|
||||
opacity: 0;
|
||||
transition: opacity ease $transition-duration, width 0s $transition-duration,
|
||||
transition:
|
||||
opacity ease $transition-duration,
|
||||
width 0s $transition-duration,
|
||||
height 0s $transition-duration;
|
||||
}
|
||||
|
||||
@ -264,7 +272,9 @@
|
||||
|
||||
@include mq(md) {
|
||||
width: $search-results-width;
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
}
|
||||
|
||||
@ -290,7 +300,10 @@
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
opacity: 1;
|
||||
transition: opacity ease $transition-duration, width 0s, height 0s;
|
||||
transition:
|
||||
opacity ease $transition-duration,
|
||||
width 0s,
|
||||
height 0s;
|
||||
}
|
||||
|
||||
@include mq(md) {
|
||||
|
||||
@ -1,9 +0,0 @@
|
||||
@function rem($size, $unit: "") {
|
||||
$rem-size: $size / $root-font-size;
|
||||
|
||||
@if $unit == false {
|
||||
@return #{$rem-size};
|
||||
} @else {
|
||||
@return #{$rem-size}rem;
|
||||
}
|
||||
}
|
||||
@ -1,9 +1,10 @@
|
||||
// Typography
|
||||
|
||||
// prettier-ignore
|
||||
$body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
|
||||
roboto, "Helvetica Neue", arial, sans-serif !default;
|
||||
roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default;
|
||||
$mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
|
||||
$root-font-size: 16px !default; // Base font-size for rems
|
||||
$root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems
|
||||
$body-line-height: 1.4 !default;
|
||||
$content-line-height: 1.6 !default;
|
||||
$body-heading-line-height: 1.25 !default;
|
||||
@ -11,18 +12,18 @@ $body-heading-line-height: 1.25 !default;
|
||||
// Font size
|
||||
// `-sm` suffix is the size at the small (and above) media query
|
||||
|
||||
$font-size-1: 9px !default;
|
||||
$font-size-1-sm: 10px !default;
|
||||
$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small
|
||||
$font-size-3: 12px !default; // h5
|
||||
$font-size-4: 14px !default;
|
||||
$font-size-5: 16px !default; // h3
|
||||
$font-size-6: 18px !default; // h2
|
||||
$font-size-7: 24px !default;
|
||||
$font-size-8: 32px !default; // h1
|
||||
$font-size-9: 36px !default;
|
||||
$font-size-10: 42px !default;
|
||||
$font-size-10-sm: 48px !default;
|
||||
$font-size-1: 0.5625rem !default;
|
||||
$font-size-1-sm: 0.625rem !default;
|
||||
$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small
|
||||
$font-size-3: 0.75rem !default; // h5
|
||||
$font-size-4: 0.875rem !default;
|
||||
$font-size-5: 1rem !default; // h3
|
||||
$font-size-6: 1.125rem !default; // h2
|
||||
$font-size-7: 1.5rem !default;
|
||||
$font-size-8: 2rem !default; // h1
|
||||
$font-size-9: 2.25rem !default;
|
||||
$font-size-10: 2.625rem !default;
|
||||
$font-size-10-sm: 3rem !default;
|
||||
|
||||
// Colors
|
||||
|
||||
@ -95,22 +96,22 @@ $border-color: $grey-lt-100 !default;
|
||||
|
||||
$gutter-spacing: $sp-6 !default;
|
||||
$gutter-spacing-sm: $sp-4 !default;
|
||||
$nav-width: 264px !default;
|
||||
$nav-width-md: 248px !default;
|
||||
$nav-width: 16.5rem !default;
|
||||
$nav-width-md: 15.5rem !default;
|
||||
$nav-list-item-height: $sp-6 !default;
|
||||
$nav-list-item-height-sm: $sp-8 !default;
|
||||
$nav-list-expander-right: true;
|
||||
$content-width: 800px !default;
|
||||
$header-height: 60px !default;
|
||||
$content-width: 50rem !default;
|
||||
$header-height: 3.75rem !default;
|
||||
$search-results-width: $content-width - $nav-width !default;
|
||||
$transition-duration: 400ms;
|
||||
|
||||
// Media queries in pixels
|
||||
|
||||
$media-queries: (
|
||||
xs: 320px,
|
||||
sm: 500px,
|
||||
xs: 20rem,
|
||||
sm: 31.25rem,
|
||||
md: $content-width,
|
||||
lg: $content-width + $nav-width,
|
||||
xl: 1400px,
|
||||
xl: 87.5rem,
|
||||
) !default;
|
||||
|
||||
@ -4,7 +4,9 @@
|
||||
color: $fg;
|
||||
background-color: darken($bg, 2%);
|
||||
background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%));
|
||||
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12);
|
||||
box-shadow:
|
||||
0 1px 3px rgba(0, 0, 0, 0.25),
|
||||
0 4px 10px rgba(0, 0, 0, 0.12);
|
||||
|
||||
&:hover,
|
||||
&.zeroclipboard-is-hover {
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
// If the key exists in the map
|
||||
@if $value {
|
||||
// Prints a media query based on the value
|
||||
@media (width >= rem($value)) {
|
||||
@media (min-width: $value) {
|
||||
@content;
|
||||
}
|
||||
} @else {
|
||||
|
||||
@ -1,3 +1,2 @@
|
||||
@import "./variables";
|
||||
@import "./functions";
|
||||
@import "./mixins/mixins";
|
||||
|
||||
@ -8,7 +8,9 @@
|
||||
margin-bottom: $sp-5;
|
||||
overflow-x: auto;
|
||||
border-radius: $border-radius;
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.12),
|
||||
0 3px 10px rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
|
||||
table {
|
||||
@ -21,7 +23,7 @@ th,
|
||||
td {
|
||||
@include fs-3;
|
||||
|
||||
min-width: 120px;
|
||||
min-width: 7.5rem;
|
||||
padding: $sp-2 $sp-3;
|
||||
background-color: $table-background-color;
|
||||
border-bottom: $border rgba($border-color, 0.5);
|
||||
|
||||
24
assets/css/just-the-docs-head-nav.css
Normal file
24
assets/css/just-the-docs-head-nav.css
Normal file
@ -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 }}
|
||||
@ -31,7 +31,7 @@ function initNav() {
|
||||
}
|
||||
if (target) {
|
||||
e.preventDefault();
|
||||
target.parentNode.classList.toggle('active');
|
||||
target.ariaPressed = target.parentNode.classList.toggle('active');
|
||||
}
|
||||
});
|
||||
|
||||
@ -39,15 +39,19 @@ function initNav() {
|
||||
const mainHeader = document.getElementById('main-header');
|
||||
const menuButton = document.getElementById('menu-button');
|
||||
|
||||
disableHeadStyleSheets();
|
||||
|
||||
jtd.addEvent(menuButton, 'click', function(e){
|
||||
e.preventDefault();
|
||||
|
||||
if (menuButton.classList.toggle('nav-open')) {
|
||||
siteNav.classList.add('nav-open');
|
||||
mainHeader.classList.add('nav-open');
|
||||
menuButton.ariaPressed = true;
|
||||
} else {
|
||||
siteNav.classList.remove('nav-open');
|
||||
mainHeader.classList.remove('nav-open');
|
||||
menuButton.ariaPressed = false;
|
||||
}
|
||||
});
|
||||
|
||||
@ -64,6 +68,26 @@ function initNav() {
|
||||
{%- endif %}
|
||||
}
|
||||
|
||||
// The <head> element is assumed to include the following stylesheets:
|
||||
// - a <link> to /assets/css/just-the-docs-head-nav.css,
|
||||
// with id 'jtd-head-nav-stylesheet'
|
||||
// - a <style> containing the result of _includes/css/activation.scss.liquid.
|
||||
// To avoid relying on the order of stylesheets (which can change with HTML
|
||||
// compression, user-added JavaScript, and other side effects), stylesheets
|
||||
// are only interacted with via ID
|
||||
|
||||
function disableHeadStyleSheets() {
|
||||
const headNav = document.getElementById('jtd-head-nav-stylesheet');
|
||||
if (headNav) {
|
||||
headNav.disabled = true;
|
||||
}
|
||||
|
||||
const activation = document.getElementById('jtd-nav-activation');
|
||||
if (activation) {
|
||||
activation.disabled = true;
|
||||
}
|
||||
}
|
||||
|
||||
{%- if site.search_enabled != false %}
|
||||
// Site search
|
||||
|
||||
@ -459,15 +483,44 @@ jtd.setTheme = function(theme) {
|
||||
cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
|
||||
}
|
||||
|
||||
// Note: pathname can have a trailing slash on a local jekyll server
|
||||
// and not have the slash on GitHub Pages
|
||||
|
||||
function navLink() {
|
||||
var href = document.location.pathname;
|
||||
if (href.endsWith('/') && href != '/') {
|
||||
href = href.slice(0, -1);
|
||||
}
|
||||
return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
|
||||
}
|
||||
|
||||
// Scroll site-nav to ensure the link to the current page is visible
|
||||
|
||||
function scrollNav() {
|
||||
const href = document.location.pathname;
|
||||
const siteNav = document.getElementById('site-nav');
|
||||
const targetLink = siteNav.querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
|
||||
if(targetLink){
|
||||
const targetLink = navLink();
|
||||
if (targetLink) {
|
||||
const rect = targetLink.getBoundingClientRect();
|
||||
siteNav.scrollBy(0, rect.top - 3*rect.height);
|
||||
document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
|
||||
targetLink.removeAttribute('href');
|
||||
}
|
||||
}
|
||||
|
||||
// Find the nav-list-link that refers to the current page
|
||||
// then make it and all enclosing nav-list-item elements active.
|
||||
|
||||
function activateNav() {
|
||||
var target = navLink();
|
||||
if (target) {
|
||||
target.classList.toggle('active', true);
|
||||
}
|
||||
while (target) {
|
||||
while (target && !(target.classList && target.classList.contains('nav-list-item'))) {
|
||||
target = target.parentNode;
|
||||
}
|
||||
if (target) {
|
||||
target.classList.toggle('active', true);
|
||||
target = target.parentNode;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -478,6 +531,7 @@ jtd.onReady(function(){
|
||||
{%- if site.search_enabled != false %}
|
||||
initSearch();
|
||||
{%- endif %}
|
||||
activateNav();
|
||||
scrollNav();
|
||||
});
|
||||
|
||||
@ -488,6 +542,11 @@ jtd.onReady(function(){
|
||||
|
||||
jtd.onReady(function(){
|
||||
|
||||
if (!window.isSecureContext) {
|
||||
console.log('Window does not have a secure context, therefore code clipboard copy functionality will not be available. For more details see https://web.dev/async-clipboard/#security-and-permissions');
|
||||
return;
|
||||
}
|
||||
|
||||
var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock > div.content, figure.highlight');
|
||||
|
||||
// note: the SVG svg-copied and svg-copy is only loaded as a Jekyll include if site.enable_copy_code_button is true; see _includes/icons/icons.html
|
||||
|
||||
@ -295,6 +295,16 @@ just_the_docs:
|
||||
|
||||
The navigation for all your normal pages (if any) is displayed before those in collections.
|
||||
|
||||
<span>New (v0.4.0)</span>{: .label .label-green }
|
||||
Including `nav_fold: true` in a collection configuration *folds* that collection:
|
||||
an expander symbol appears next to the collection name,
|
||||
and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled]
|
||||
|
||||
[^js-disabled]: <span>New (v0.6.0)</span>{: .label .label-green }
|
||||
When JavaScript is disabled in the browser, all folded collections are automatically expanded,
|
||||
since clicking expander symbols has no effect.
|
||||
(In previous releases, navigation into folded collections required JavaScript to be enabled.)
|
||||
|
||||
You can reference multiple collections.
|
||||
This creates categories in the navigation with the configured names.
|
||||
|
||||
|
||||
@ -52,7 +52,7 @@ New (v0.4.2)
|
||||
{: .label .label-green }
|
||||
|
||||
|
||||
In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who are want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
|
||||
In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
|
||||
|
||||
## Custom schemes
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page](another-page).
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
|
||||
There should be whitespace between paragraphs.
|
||||
|
||||
@ -55,7 +55,7 @@ GitHubPages::Dependencies.gems.each do |gem, version|
|
||||
end
|
||||
```
|
||||
|
||||
#### [](#header-4)Header 4 `with code not transformed`
|
||||
#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed`
|
||||
|
||||
* This is an unordered list following a header.
|
||||
* This is an unordered list following a header.
|
||||
@ -310,7 +310,17 @@ graph TD;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
### Collapsed Section
|
||||
|
||||
```
|
||||
The final element.
|
||||
```
|
||||
The following uses the [`<details>`](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) tag to create a collapsed section.
|
||||
|
||||
<details markdown="block">
|
||||
<summary>Shopping list (click me!)</summary>
|
||||
|
||||
This is content inside a `<details>` dropdown.
|
||||
|
||||
- [ ] Apples
|
||||
- [ ] Oranges
|
||||
- [ ] Milk
|
||||
|
||||
</details>
|
||||
|
||||
40
docs/layout/layout.md
Normal file
40
docs/layout/layout.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Layout
|
||||
layout: default
|
||||
nav_order: 4.5
|
||||
has_children: true
|
||||
---
|
||||
|
||||
# Layout
|
||||
|
||||
You specify the layout for a page in its [front matter]. Just the Docs has a `default` layout with a sidebar, used for almost all pages in the theme docs, and a `minimal` layout that omits the sidebar.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
## The layout concept
|
||||
|
||||
See the [Jekyll docs page about layouts] for an explanation of the general idea of layouts and how to specify them.
|
||||
|
||||
You can use [Jekyll's front matter defaults] to specify the same layout for many pages.
|
||||
|
||||
## The `default` layout
|
||||
|
||||
This page uses the default layout.
|
||||
|
||||
It is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
|
||||
|
||||
Each child (and grandchild) page of a top-level page has so-called *breadcrumbs*: links to its parent (and grandparent) pages. It shows the breadcrumbs above the main content of the page.
|
||||
|
||||
Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content.
|
||||
|
||||
## The `minimal` layout
|
||||
|
||||
A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar -- and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
|
||||
|
||||
## Other layouts
|
||||
|
||||
Just the Docs has further layouts: `about`, `home`, `page`, and `post`. Currently, they are all based on the `default` layout. See the [Jekyll docs about inheritance] for how to customize them.
|
||||
|
||||
[front matter]: https://jekyllrb.com/docs/front-matter/ "Jekyll docs about front matter"
|
||||
[Jekyll docs page about layouts]: https://jekyllrb.com/docs/layouts/ "Jekyll docs about layouts"
|
||||
[Jekyll's front matter defaults]: https://jekyllrb.com/docs/configuration/front-matter-defaults/ "Jekyll docs about front matter defaults"
|
||||
[Jekyll docs about inheritance]: https://jekyllrb.com/docs/layouts/#inheritance "Jekyll docs about inheritance"
|
||||
8
docs/layout/minimal/default-child.md
Normal file
8
docs/layout/minimal/default-child.md
Normal file
@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Default layout child page
|
||||
layout: default
|
||||
parent: A minimal layout page
|
||||
grand_parent: Layout
|
||||
---
|
||||
|
||||
This is a child page that uses the same minimal layout as its parent page.
|
||||
8
docs/layout/minimal/minimal-child.md
Normal file
8
docs/layout/minimal/minimal-child.md
Normal file
@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Minimal layout child page
|
||||
layout: minimal
|
||||
parent: A minimal layout page
|
||||
grand_parent: Layout
|
||||
---
|
||||
|
||||
This is a child page that uses the same minimal layout as its parent page.
|
||||
12
docs/layout/minimal/minimal.md
Normal file
12
docs/layout/minimal/minimal.md
Normal file
@ -0,0 +1,12 @@
|
||||
---
|
||||
title: A minimal layout page
|
||||
layout: minimal
|
||||
parent: Layout
|
||||
has_children: true
|
||||
---
|
||||
|
||||
# A minimal layout page
|
||||
|
||||
This page illustrates the built-in layout `minimal`.
|
||||
|
||||
One of its child pages also uses the minimal layout; the other child pages uses the default layout.
|
||||
@ -20,7 +20,7 @@ nav_order: 5
|
||||
|
||||
## Main navigation
|
||||
|
||||
The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
|
||||
The main navigation for your Just the Docs site is on the left side of the page on large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
|
||||
|
||||
By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
|
||||
|
||||
@ -30,7 +30,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
|
||||
|
||||
To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
|
||||
|
||||
#### Example
|
||||
### Example (ordering pages)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -55,7 +55,7 @@ By default, all Capital letters come before all lowercase letters; you can add `
|
||||
|
||||
For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
|
||||
|
||||
#### Example
|
||||
### Example (excluding pages)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -108,7 +108,7 @@ On the parent pages, add this YAML front matter parameter:
|
||||
|
||||
- `has_children: true` (tells us that this is a parent page)
|
||||
|
||||
#### Example
|
||||
### Example (parent pages)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -129,7 +129,7 @@ Here we're setting up the UI Components landing page that is available at `/docs
|
||||
|
||||
On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
|
||||
|
||||
#### Example
|
||||
#### Example (child pages)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -154,7 +154,7 @@ You can optionally add the following to the YAML front matter to reverse the def
|
||||
|
||||
- `child_nav_order: reversed`
|
||||
|
||||
#### Example
|
||||
#### Example (ordering child pages)
|
||||
{: .no_toc }
|
||||
```yaml
|
||||
---
|
||||
@ -168,7 +168,7 @@ child_nav_order: reversed
|
||||
|
||||
By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
|
||||
|
||||
#### Example
|
||||
#### Example (auto-generating Table of Contents)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -191,7 +191,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
|
||||
1. Add the `has_children` attribute to the child
|
||||
1. Add the `parent` and `grand_parent` attribute to the grandchild
|
||||
|
||||
#### Example
|
||||
##### Example (children within children)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -241,7 +241,7 @@ Currently, the navigation structure is limited to 3 levels: grandchild pages can
|
||||
|
||||
To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
|
||||
|
||||
#### Example
|
||||
### Example (auxiliary links)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -262,7 +262,7 @@ New (v0.4.0)
|
||||
To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
|
||||
External links will appear in the navigation after the links to ordinary pages, but before any collections.
|
||||
|
||||
#### Example
|
||||
### Example (external navigation links)
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -271,18 +271,32 @@ nav_external_links:
|
||||
- title: Just the Docs on GitHub
|
||||
url: https://github.com/just-the-docs/just-the-docs
|
||||
hide_icon: false # set to true to hide the external link icon - defaults to false
|
||||
opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
|
||||
```
|
||||
|
||||
### Opening external links in a new tab
|
||||
{: .d-inline-block }
|
||||
|
||||
New (unreleased)
|
||||
{: .label .label-green }
|
||||
|
||||
The external links are decorated by an icon, which distinguishes them from internal links.
|
||||
You can suppress the icon by setting `hide_icon: true`.
|
||||
|
||||
By default, external links are not opened in a new tab. However, this can be enabled by:
|
||||
|
||||
1. setting `opens_in_new_tab: true` in the link's configuration object
|
||||
2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
|
||||
|
||||
When they conflict, `opens_in_new_tab` takes precedence.
|
||||
|
||||
---
|
||||
|
||||
## In-page navigation with Table of Contents
|
||||
|
||||
To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
|
||||
|
||||
#### Example
|
||||
### Example (in-page navigation with Table of Contents)
|
||||
{: .no_toc }
|
||||
|
||||
```markdown
|
||||
@ -300,7 +314,7 @@ This example skips the page name heading (`#`) from the TOC, as well as the head
|
||||
|
||||
### Collapsible Table of Contents
|
||||
|
||||
The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements , as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
|
||||
The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements, as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
|
||||
|
||||
```markdown
|
||||
<details open markdown="block">
|
||||
|
||||
@ -15,7 +15,7 @@ nav_order: 7
|
||||
|
||||
---
|
||||
|
||||
Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
|
||||
Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
|
||||
All search results are shown in an auto-complete style interface (there is no search results page).
|
||||
By default, all generated HTML pages are indexed using the following data points:
|
||||
|
||||
|
||||
@ -21,22 +21,22 @@ nav_order: 2
|
||||
### Links that look like buttons
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
[Link button](http://example.com/){: .btn .btn-purple }
|
||||
[Link button](http://example.com/){: .btn .btn-blue }
|
||||
[Link button](http://example.com/){: .btn .btn-green }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-purple }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-green }
|
||||
|
||||
[Link button](http://example.com/){: .btn .btn-outline }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-outline }
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
[Link button](http://example.com/){: .btn .btn-purple }
|
||||
[Link button](http://example.com/){: .btn .btn-blue }
|
||||
[Link button](http://example.com/){: .btn .btn-green }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-purple }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-green }
|
||||
|
||||
[Link button](http://example.com/){: .btn .btn-outline }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-outline }
|
||||
```
|
||||
|
||||
### Button element
|
||||
@ -60,20 +60,20 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
<span class="fs-6">
|
||||
[Big ass button](http://example.com/){: .btn }
|
||||
[Big ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
|
||||
<span class="fs-3">
|
||||
[Tiny ass button](http://example.com/){: .btn }
|
||||
[Tiny ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
</div>
|
||||
```markdown
|
||||
<span class="fs-8">
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
|
||||
<span class="fs-3">
|
||||
[Tiny ass button](http://example.com/){: .btn }
|
||||
[Tiny ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
```
|
||||
|
||||
@ -82,16 +82,16 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
|
||||
Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
|
||||
[Button](http://example.com/){: .btn .btn-blue }
|
||||
[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
|
||||
[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
|
||||
[Button](http://example.com/){: .btn .btn-blue }
|
||||
[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
</div>
|
||||
```markdown
|
||||
[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
|
||||
[Button](http://example.com/){: .btn .btn-blue }
|
||||
[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
|
||||
[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
|
||||
[Button](http://example.com/){: .btn .btn-blue }
|
||||
[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
```
|
||||
|
||||
@ -68,22 +68,22 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
```
|
||||
|
||||
</div>
|
||||
{% highlight markdown %}
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](http://example.com/){: .btn }
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
```
|
||||
{% endhighlight %}
|
||||
|
||||
@ -115,7 +115,7 @@ Additional configuration options are loaded through `_includes/mermaid_config.js
|
||||
|
||||
This loads the default settings.
|
||||
|
||||
The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
|
||||
The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to:
|
||||
|
||||
```js
|
||||
// _includes/mermaid_config.js
|
||||
@ -185,7 +185,7 @@ graph TD;
|
||||
++++
|
||||
{% endhighlight %}
|
||||
|
||||
Alternatively, community member [@flyx](https://.github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://.github.com/flyx)!
|
||||
Alternatively, community member [@flyx](https://github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://github.com/flyx)!
|
||||
|
||||
The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
|
||||
|
||||
|
||||
@ -115,6 +115,9 @@ end
|
||||
{% include fix_linenos.html code=code %}
|
||||
{% assign code = nil %}
|
||||
|
||||
{: .warning }
|
||||
The following generates **incorrect** and **invalid** HTML. It should not be used as a positive example; the improper layout (with the broken HTML tags) is intentional.
|
||||
|
||||
❌ With the compression options used for the theme docs, the following example illustrates
|
||||
the **incorrect** formatting arising from the incompatibility of HTML compression
|
||||
and the non-conforming HTML produced by Jekyll for line numbers:
|
||||
|
||||
@ -21,7 +21,7 @@ nav_order: 1
|
||||
By default, Just the Docs uses a native system font stack for sans-serif fonts:
|
||||
|
||||
```scss
|
||||
system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
|
||||
system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Segoe UI Emoji"
|
||||
```
|
||||
|
||||
ABCDEFGHIJKLMNOPQRSTUVWXYZ
|
||||
@ -97,12 +97,12 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
|
||||
<div class="code-example" markdown="1">
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page](another-page).
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
</div>
|
||||
```markdown
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page](another-page).
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -61,7 +61,7 @@ Use `mx-auto` to horizontally center elements.
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
```markdown
|
||||
This paragraph will have a margin bottom of 1rem/16px at large screens.
|
||||
This paragraph will have a margin bottom of 1rem/16px on large screens.
|
||||
{: .mb-lg-4 }
|
||||
|
||||
This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.
|
||||
|
||||
@ -9,5 +9,5 @@ permalink: docs/utilities
|
||||
# Utilities
|
||||
{: .no_toc }
|
||||
|
||||
CSS utility classes come in handy when you to want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
|
||||
CSS utility classes come in handy when you want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
15
fixtures/Gemfile-jekyll-3.9
Normal file
15
fixtures/Gemfile-jekyll-3.9
Normal file
@ -0,0 +1,15 @@
|
||||
source "https://rubygems.org"
|
||||
|
||||
gem "jekyll", "~> 3.9"
|
||||
|
||||
gem "jekyll-seo-tag", ">= 2.0"
|
||||
gem "rake", ">= 12.3.1"
|
||||
|
||||
gem "jekyll-include-cache", group: :jekyll_plugins
|
||||
|
||||
# required for Jekyll 3
|
||||
gem "webrick", "~> 1.7"
|
||||
gem "kramdown-parser-gfm", '~> 1.1'
|
||||
|
||||
# docs-only
|
||||
gem "jekyll-github-metadata", ">= 2.15"
|
||||
11
fixtures/Gemfile-jekyll-4.3
Normal file
11
fixtures/Gemfile-jekyll-4.3
Normal file
@ -0,0 +1,11 @@
|
||||
source "https://rubygems.org"
|
||||
|
||||
gem "jekyll", "~> 4.3"
|
||||
|
||||
gem "jekyll-seo-tag", ">= 2.0"
|
||||
gem "rake", ">= 12.3.1"
|
||||
|
||||
gem "jekyll-include-cache", group: :jekyll_plugins
|
||||
|
||||
# docs-only
|
||||
gem "jekyll-github-metadata", ">= 2.15"
|
||||
3
fixtures/html5validator-config.yml
Normal file
3
fixtures/html5validator-config.yml
Normal file
@ -0,0 +1,3 @@
|
||||
root: _site
|
||||
blacklist:
|
||||
- "line-numbers"
|
||||
4
index.md
4
index.md
@ -49,7 +49,7 @@ See the theme [README][Just the Docs README] for how to use the theme as a gem w
|
||||
|
||||
## About the project
|
||||
|
||||
Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](http://patrickmarsceill.com).
|
||||
Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](https://patrickmarsceill.com).
|
||||
|
||||
### License
|
||||
|
||||
@ -89,7 +89,7 @@ Just the Docs is committed to fostering a welcoming community.
|
||||
[Jekyll configuration]: https://jekyllrb.com/docs/configuration/
|
||||
[source file for this page]: https://github.com/just-the-docs/just-the-docs/blob/main/index.md
|
||||
[Just the Docs Template]: https://just-the-docs.github.io/just-the-docs-template/
|
||||
[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
|
||||
[Just the Docs]: https://just-the-docs.com
|
||||
[Just the Docs repo]: https://github.com/just-the-docs/just-the-docs
|
||||
[Just the Docs README]: https://github.com/just-the-docs/just-the-docs/blob/main/README.md
|
||||
[GitHub Pages]: https://pages.github.com/
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Gem::Specification.new do |spec|
|
||||
spec.name = "just-the-docs"
|
||||
spec.version = "0.5.0"
|
||||
spec.version = "0.7.0"
|
||||
spec.authors = ["Patrick Marsceill", "Matthew Wang"]
|
||||
spec.email = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
|
||||
|
||||
@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
|
||||
spec.metadata = {
|
||||
"bug_tracker_uri" => "https://github.com/just-the-docs/just-the-docs/issues",
|
||||
"changelog_uri" => "https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md",
|
||||
"documentation_uri" => "https://just-the-docs.github.io/just-the-docs/",
|
||||
"documentation_uri" => "https://just-the-docs.com/",
|
||||
"source_code_uri" => "https://github.com/just-the-docs/just-the-docs",
|
||||
}
|
||||
|
||||
@ -22,5 +22,6 @@ Gem::Specification.new do |spec|
|
||||
spec.add_development_dependency "bundler", ">= 2.3.5"
|
||||
spec.add_runtime_dependency "jekyll", ">= 3.8.5"
|
||||
spec.add_runtime_dependency "jekyll-seo-tag", ">= 2.0"
|
||||
spec.add_runtime_dependency "jekyll-include-cache"
|
||||
spec.add_runtime_dependency "rake", ">= 12.3.1"
|
||||
end
|
||||
|
||||
1153
package-lock.json
generated
1153
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -7,9 +7,9 @@
|
||||
"bugs": "https://github.com/just-the-docs/just-the-docs/issues",
|
||||
"devDependencies": {
|
||||
"npm-run-all": "^4.1.5",
|
||||
"prettier": "^2.8.7",
|
||||
"stylelint": "^15.5.0",
|
||||
"stylelint-config-standard-scss": "^8.0.0"
|
||||
"prettier": "^3.0.3",
|
||||
"stylelint": "^15.11.0",
|
||||
"stylelint-config-standard-scss": "^11.0.0"
|
||||
},
|
||||
"scripts": {
|
||||
"lint": "npm-run-all --parallel --continue-on-error lint:*",
|
||||
@ -32,6 +32,7 @@
|
||||
"alpha-value-notation": null,
|
||||
"at-rule-empty-line-before": null,
|
||||
"color-function-notation": null,
|
||||
"media-feature-range-notation": "prefix",
|
||||
"no-descending-specificity": null,
|
||||
"scss/no-global-function-names": null
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user