Prep v0.5.0

This PR does two things:

1. fixes using mermaid version `>= 10` from the CDN, by importing the ESM module instead
2. moves script loading code from `head.html` to the mermaid include

I've also added some light documentation to clarify how using mermaid with local paths should work (users should specify a version, and they should only use fully-minified bundles with no local references).

The nice thing about this approach is that it's a breaking change for nobody, and only adds functionality (v10 support). Eventually, we should remove support for mermaid <10, which should make this much easier!

Closes #1206.

## Context

In v10, Mermaid has implemented a few (admittedly, very frustrating to deal with) breaking changes:

1. they've removed CJS support, which is fine, *but*
2. that means that the `dist` they publish to JSDelivr now has a **different URL**: for versions `10.0.0` - `10.0.2`, **they do not have a minified bundle -- you have to load the ESM version with relative imports**
3. and, separately the `init` function has been deprecated

2 is really the issue, and so I've had to go into the code to now load mermaid by ESM by default when the user is on mermaid > v10.

I've tested this with:

- CDN version < 10 (v9)
- CDN version 10
- local path with version < 10 (v9)
- local path with version 10 (new: also loaded as an ESM module)

Separately, I chose to put all the mermaid stuff in one include because:

- I think @pdmosses requested something like this - it's a bit confusing that some mermaid code is *not* in the include, and this makes modular components ... more modular
- from a developer perspective, it's more clear what's happening with mermaid
- mermaid is not render-blocking, so it shouldn't be in the `head` anyways

---------

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>

.github/workflows/ci.yml

@@ -5,23 +5,25 @@ on:
   pull_request:
     branches:
       - main
-      - 'v**'
 
 name: CI
 
 jobs:
   jekyll-build:
-    name: Build Jekyll site
+    name: Build (jekyll gem)
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         jekyll-version: [3.9, 4.3]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        ruby-version: [2.7, 3.1]
+    runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3
-    - name: Setup Ruby
+    - name: Setup Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1' # Not needed with a .ruby-version file
+        ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
     - name: Bundle Install
       run: bundle install
@@ -32,6 +34,21 @@ jobs:
     - name: Build Site
       run: bundle exec jekyll build
 
+  github-pages-build:
+    name: Build (github-pages gem)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.1'
+        bundler-cache: false
+    - name: Bundle Install
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle install
+    - name: Build Site
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle exec jekyll build
+
   assets:
     name: Test CSS and JS
     runs-on: ubuntu-latest

.github/workflows/publish-gem.yml

@@ -27,13 +27,14 @@ jobs:
         GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
         OWNER: ${{ github.repository_owner }}
 
-    - name: Publish to RubyGems
+    # Disabled as this does not handle 2FA
-      run: |
+    # - name: Publish to RubyGems
-        mkdir -p $HOME/.gem
+    #   run: |
-        touch $HOME/.gem/credentials
+    #     mkdir -p $HOME/.gem
-        chmod 0600 $HOME/.gem/credentials
+    #     touch $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+    #     chmod 0600 $HOME/.gem/credentials
-        gem build *.gemspec
+    #     printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem push *.gem
+    #     gem build *.gemspec
-      env:
+    #     gem push *.gem
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+    #   env:
+    #     GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

.prettierignore

@@ -1,4 +1,3 @@
-package.json
 package-lock.json
 _site
 assets/css/just-the-docs-default.scss
@@ -6,5 +5,7 @@ assets/css/just-the-docs-light.scss
 assets/css/just-the-docs-dark.scss
 assets/js/vendor/lunr.min.js
 assets/js/search-data.json
+assets/js/zzzz-search-data.json
 assets/js/just-the-docs.js
 *.md
+_includes/mermaid_config.js

.prettierrc

@@ -1,7 +0,0 @@
-{
-  "endOfLine": "lf",
-  "semi": false,
-  "singleQuote": false,
-  "tabWidth": 2,
-  "trailingComma": "es5"
-}

.stylelintrc.json

@@ -1,20 +0,0 @@
-{
-  "ignoreFiles": [
-    "assets/css/just-the-docs-default.scss",
-    "assets/css/just-the-docs-light.scss",
-    "assets/css/just-the-docs-dark.scss",
-    "_sass/vendor/**/*.scss"
-  ],
-  "extends": [
-    "stylelint-config-standard-scss",
-    "stylelint-config-prettier-scss"
-  ],
-  "plugins": ["stylelint-prettier"],
-  "rules": {
-    "prettier/prettier": true,
-    "alpha-value-notation": null,
-    "color-function-notation": null,
-    "no-descending-specificity": null,
-    "scss/no-global-function-names": null
-  }
-}

CHANGELOG.md

@@ -16,12 +16,411 @@ The project underwent a major maintenance shift in March 2022.
 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.4.0.rc5` and `v0.3.3`!
+This website includes docs for some new features that are not available in `v0.5.0`!
 
-Changes to `main` that are *not* in the latest pre-release:
+Code changes to `main` that are *not* in the latest release:
 
 - n/a
 
+Docs changes in `main` that are *not* in the latest release:
+
+- n/a
+
+## Release v0.5.0
+
+Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`.
+
+We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes.
+
+As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Migrating to `v0.5.0`
+
+**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves.
+
+For more, refer to the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/).
+
+### Using Release `v0.5.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.5.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.5.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag.
+
+### Bugfixes
+
+- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209]
+- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208]
+- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190]
+- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107]
+- Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187]
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0)
+
+[#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107
+[#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187
+[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190
+[#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208
+[#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209
+
+## Release v0.4.2
+
+Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
+
+The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.github.io/just-the-docs/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`.
+
+As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Using Release `v0.4.2`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.2
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.4.2"
+```
+
+To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166]
+- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173]
+- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184]
+- Removed: unused dark syntax themes by [@mattxwang] in [#1192]
+
+### Documentation
+
+- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182]
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2)
+
+[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166
+[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173
+[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182
+[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184
+[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192
+
+## Release v0.4.1
+
+Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
+
+As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Using Release `v0.4.1`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.1
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.4.1"
+```
+
+To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165]
+- Fixed: AsciiDoc code block styling by [@flyx] in [#1168]
+- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177]
+- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167]
+
+### Documentation
+
+- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108]
+
+### New Contributors
+
+- [@flyx] made their first contribution in [#1168]
+- [@Dima-369] made their first contribution in [#1177]
+
+[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108
+[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165
+[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167
+[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168
+[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177
+
+[@flyx]: https://github.com/flyx
+[@Dima-369]: https://github.com/Dima-369
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1)
+
+## Release v0.4.0
+
+We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme.
+
+### Brief Overview - Highlighted Changes
+
+`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes:
+
+- better support for dark theme: dark highlighting, search input color
+- [callouts](https://just-the-docs.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)
+- 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
+- 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/)
+
+*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.*
+
+### Using Release `v0.4.0`
+
+Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.4.0"
+```
+
+If you would prefer to not upgrade, you can enforce that explicitly:
+
+1. pin your gem version in your `Gemfile`, like so
+```ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### Migration Guide and Strategies
+
+We've developed a new [migration guide](https://just-the-docs.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.
+
+**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes.
+
+Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release.
+
+For support with migrating to `v0.4.0`, [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
+
+### Roadmap (What's Next?)
+
+Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future!
+
+Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release.
+
+For version `v0.5`, our roadmap includes:
+
+- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences
+- better GDPR compliance for analytics
+- multi-level/recursive navigation (unlimited hierarchy of child pages)
+
+In future versions, we also plan on:
+
+- adding better dark theme defaults
+- adding better internationalization support
+- exploring offline PDF generation
+- improving accessibility within the theme
+- improving search functionality
+- refactoring and improving the robustness of our codebase
+
+Have ideas for what's next, or want to get involved? [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! We're looking for more contributors and maintainers to help us develop the theme.
+
+### New Features
+
+- Added: Combination by [@pdmosses] in [#578]
+  - Added: dark highlighting in [#463]
+  - Added: pages and collections in [#448]
+  - Added: callouts in [#466]
+  - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477]
+  - Fixed: prevent rake command corrupting search data in [#495] (also listed below)
+  - Fixed: nested lists in [#496]
+  - Fixed: set color for search input in [#498] (also listed below)
+  - Fixed: sites with no child pages (no PR)
+  - Fixed: TOC/breadcrumbs for multiple collections in [#494]
+  - Added: collection configuration option `nav_fold` (no PR)
+  - Fixed: indentation and color for folded collection navigation (no PR)
+  - Fixed: scroll navigation to show the link to the current page in [#639]
+  - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544]
+- Added: custom favicon `_includes` by [@burner1024] in [#364]
+- Added: set color for search input by [@pdmosses] in [#498]
+- Added: search placeholder configuration by [@mattxwang] in [#613]
+- Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726]
+- Added: `nav_footer_custom` include by [@nathanjessen] in [#474]
+- Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829]
+- Added: mermaid.js support by [@nascosto] in [#857]
+- Added: support for external navigation links by [@SPGoding] in [#876]
+- Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909]
+- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950]
+- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944]
+- Added: docs for custom search placeholder by [@mattxwang] in [#939]
+- Added: provide ability to skip to main content by [@JPrevost] in [#949]
+- Added: styling for `<blockquote>` by [@mattxwang] in [#965]
+- Added: custom include for TOC heading by [@pdmosses] in [#980]
+- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992]
+- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029]
+- Added: copy code button to code snippets by [@simonebortolin] in [#945]
+- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095]
+- Added: modularize site components by [@mattxwang] in [#1058]
+- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068]
+- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135]
+- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153]
+
+### Bugfixes
+
+- Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519]
+- Fixed: nested task lists (#517) by [@pdmosses] in [#855]
+- Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686]
+- Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495]
+- Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846]
+- Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727]
+- Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889]
+- Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893]
+- Fixed: allow links to wrap by [@pdmosses] in [#905]
+- Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898]
+- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941]
+- Fixed: improve build time of navigation panel by [@pdmosses] in [#956]
+- Fixed: spacing issue when search is disabled by [@henryiii] in [#960]
+- Fixed: active grandchild link class by [@pdmosses] in [#962]
+- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964]
+- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967]
+- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985]
+- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974]
+- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986]
+- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999]
+- Fixed: duplicated external links in collections by [@pdmosses] in [#1001]
+- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010]
+- Fixed: top-level active link styling by [@pdmosses] in [#1015]
+- Fixed: external links for sites with no pages by [@pdmosses] in [#1021]
+- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040]
+- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027]
+- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061]
+- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065]
+- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074]
+    - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077]
+- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092]
+- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102]
+- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104]
+- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096]
+- Fixed: replace inline styling for `<svg>` icons by [@captn3m0] in [#1110]
+- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123]
+- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128]
+- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142]
+- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124]
+- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143]
+
+### Maintenance
+
+- Added: VScode devcontainer by [@max06] in [#783]
+- Added: `webrick` to `Gemfile` by [@mattxwang] in [#799]
+- Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797]
+- Updated: new repo path by [@pmarsceill] in [#775]
+- Updated: rename `master` -> `main` by [@pmarsceill] in [#776]
+- Updated: README by [@pmarsceill] in [#777]
+- Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790]
+- Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820]
+- Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821]
+- Deleted: unused script directory by [@mattxwang] in [#937]
+- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071]
+
+### Documentation
+
+- Added: docs on how to break an `ol` by [@pdmosses] in [#856]
+- Added: docs for custom includes by [@nathanjessen] in [#806]
+- Added: document caveat about variable dependencies by [@waldyrious] in [#555]
+- Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814]
+- Added: docs load mermaid.js by default by [@mattxwang] in [#935]
+- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091]
+- Added:  migration guide by [@pdmosses] in [#1059]
+- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138]
+- Fixed: `ol` on `index.md` by [@pmarsceill] in [#778]
+- Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221]
+- Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782]
+- Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549]
+- Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554]
+- Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499]
+- Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473]
+- Fixed: spacing in toc example by [@henryiii] in [#835]
+- Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891]
+- Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906]
+- Fixed: table of contents on search docs by [@robinpokorny] in [#940]
+- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951]
+- Fixed: clarify version docs by [@pdmosses] in [#955]
+- Fixed: typo in changelog links [@koppor] in [#1000]
+- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090]
+- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130]
+- Fixed: broken relative page links by [@mattxwang] in [#1106]
+- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139]
+- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018]
+- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019]
+- Updated: `README` demo video by [@codewithfan] in [#1097]
+
+### New Contributors
+
+- [@AdityaTiwari2102] made their first contribution in [#477]
+- [@svrooij] made their first contribution in [#544]
+- [@alexsegura] made their first contribution in [#519]
+- [@burner1024] made their first contribution in [#364]
+- [@JeffGuKang] made their first contribution in [#221]
+- [@dougaitken] made their first contribution in [#782]
+- [@max06] made their first contribution in [#783]
+- [@sehilyi] made their first contribution in [#499]
+- [@nathanjessen] made their first contribution in [#473]
+- [@waldyrious] made their first contribution in [#549]
+- [@MichelleBlanchette] made their first contribution in [#554]
+- [@henryiii] made their first contribution in [#835]
+- [@jmertic] made their first contribution in [#726]
+- [@jacobhq] made their first contribution in [#846]
+- [@UnclassedPenguin] made their first contribution in [#814]
+- [@alyssais] made their first contribution in [#829]
+- [@nascosto] made their first contribution in [#857]
+- [@SPGoding] made their first contribution in [#876]
+- [@iridazzle] made their first contribution in [#727]
+- [@ivanskodje] made their first contribution in [#891]
+- [@Eisverygoodletter] made their first contribution in [#893]
+- [@robinpokorny] made their first contribution in [#940]
+- [@olgarithms] made their first contribution in [#951]
+- [@manuelhenke] made their first contribution in [#941]
+- [@JPrevost] made their first contribution in [#950]
+- [@koppor] made their first contribution in [#1000]
+- [@deseo] made their first contribution in [#1010]
+- [@Tom-Brouwer] made their first contribution in [#1040]
+- [@simonebortolin] made their first contribution in [#945]
+- [@SConaway] made their first contribution in [#1104]
+- [@captn3m0] made their first contribution in [#1110]
+- [@kevinlin1] made their first contribution in [#1123]
+- [@codewithfan] made their first contribution in [#1097]
+- [@agabrys] made their first contribution in [#1130]
+- [@diablodale] made their first contribution in [#1068]
+- [@m-r-mccormick] made their first contribution in [#1142]
+- [@fabrik42] made their first contribution in [#1153]
+
 ## Pre-release v0.4.0.rc5
 
 Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release.
@@ -40,14 +439,14 @@ remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5
 
 To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
-```Ruby
+```ruby
 gem "just-the-docs", "0.4.0.rc5"
 ```
 
 By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -141,14 +540,14 @@ remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4
 
 To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
-```Ruby
+```ruby
 gem "just-the-docs", "0.4.0.rc4"
 ```
 
 By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -262,14 +661,14 @@ remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3
 
 To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
-```Ruby
+```ruby
 gem "just-the-docs", "0.4.0.rc3"
 ```
 
 By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -338,14 +737,14 @@ remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2
 
 To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
-```Ruby
+```ruby
 gem "just-the-docs", "0.4.0.rc2"
 ```
 
 By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -426,7 +825,7 @@ remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
 
 To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
-```Ruby
+```ruby
 gem "just-the-docs", "0.4.0.rc1"
 ```
 
@@ -437,7 +836,7 @@ If you're not ready to make the switch, that's alright! If your version of just-
 If you have not pinned your theme version, you should either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so

Gemfile

@@ -1,4 +1,6 @@
 source "https://rubygems.org"
 gemspec
 
+gem "jekyll-github-metadata", ">= 2.15"
+
 gem "webrick", "~> 1.7"

MIGRATION.md

@@ -43,6 +43,25 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.4.x - v0.5.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.5.0
+
+There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context:
+
+1. `setup.scss` was introduced in `v0.4.0`
+2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code
+3. in `v0.4.2`, we adjusted the order to import `setup.scss` *after* color scheme SCSS code
+4. in `v0.5.0`, we have reverted the previous change: `setup.scss` is now again imported *before* color scheme SCSS code
+
+This does not affect most users. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes.
+
+Explicit migration steps are only needed if:
+
+1. a custom `setup.scss` has been defined,
+2. **and** the `setup.scss` depends on variables or functions defined in color scheme SCSS code; this change was only possible on `v0.4.2`
+
+For those users, we suggest moving those variables and functions to each relevant color scheme.
 ## v0.3.3 … v0.4.x
 
 ### REPOSITORY CHANGES
@@ -246,8 +265,6 @@ For changes since v0.3.3, the log usually references the merged PR that made the
 
 ### NON-BREAKING CHANGES (OUTLINE ONLY)
 
-Brief descriptions of the following changes are to be added below.
-
 #### Accessibility
 
 - Skip to main content: the first keyboard-navigatable item is now a link to skip over the sidebar and header to the main content of the page. PR: [#949].

_config.yml

@@ -17,6 +17,7 @@ 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
+repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
 
@@ -42,6 +43,11 @@ exclude:
    - package-lock.json
    - Rakefile
    - README.md
+   - CODE_OF_CONDUCT.md
+   - docker-compose.yml
+   - Dockerfile
+ # theme test code
+   - fixtures/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -76,8 +82,6 @@ search:
 # For copy button on code
 enable_copy_code_button: true
 
-# To disable support for mermaid diagrams (https://mermaid.js.org),
-# comment out the `mermaid` and `version` keys below
 # By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
 mermaid:
   # Version of mermaid library
@@ -85,8 +89,12 @@ mermaid:
   version: "9.1.6"
   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
   # See also docs/ui-components/code
-  # To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
+  # To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
+  # for (v10+):
+  # path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
   # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
 
 # Enable or disable heading anchors
 heading_anchors: true
@@ -159,6 +167,7 @@ callouts:
 
 plugins:
   - jekyll-seo-tag
+  - jekyll-github-metadata
 
 kramdown:
   syntax_highlighter_opts:

_includes/components/mermaid.html

@@ -1,5 +1,45 @@
+{% comment %}
+The complexity of this file comes from a breaking change in Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work earlier?).
+
+So, we check whether the user's Mermaid version is >= 10; if not, we fall back to the previous init syntax.
+
+If a user is using a custom mermaid file and doesn't specify a version, we default to the < v10 behaviour. Users who use version v10 or above should specify this in the version key.
+{% endcomment %}
+
+{% if site.mermaid.version %}
+  {% assign mermaid_major_version = site.mermaid.version | split: "." | first | plus: 0 %}
+{% else %}
+  {% assign mermaid_major_version = 9 %}
+{% endif %}
+
+{% if mermaid_major_version > 9 %}
+
+<script type="module">
+  {% if site.mermaid.path %}
+  import mermaid from '{{ site.mermaid.path | relative_url }}';
+  {% else %}
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.esm.min.mjs';
+  {% endif %}
+
+  var config = {% include mermaid_config.js %};
+  mermaid.initialize(config);
+  mermaid.run({
+    querySelector: '.language-mermaid',
+  });
+</script>
+
+{% else %}
+
+{% if site.mermaid.path %}
+  <script src="{{ site.mermaid.path | relative_url }}"></script>
+{% else %}
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
+{% endif %}
+
 <script>
   var config = {% include mermaid_config.js %};
   mermaid.initialize(config);
   window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
 </script>
+
+{% endif %}

_includes/css/just-the-docs.scss.liquid

@@ -4,7 +4,9 @@ $logo: "{{ site.logo | relative_url }}";
 @import "./support/support";
 @import "./custom/setup";
 @import "./color_schemes/light";
+{% unless include.color_scheme == "light" %}
 @import "./color_schemes/{{ include.color_scheme }}";
+{% endunless %}
 @import "./modules";
 {% include css/callouts.scss.liquid color_scheme = include.color_scheme %}
 {% include css/custom.scss.liquid %}

_includes/head.html

@@ -22,14 +22,6 @@
     <script src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
 
-  {% if site.mermaid %}
-    {% if site.mermaid.path %}
-      <script src="{{ site.mermaid.path | relative_url }}"></script>
-    {% else %}
-      <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
-    {% endif %}
-  {% endif %}
-
   <script src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">

_sass/base.scss

@@ -5,11 +5,6 @@
   box-sizing: border-box;
 }
 
-::selection {
-  color: $white;
-  background: $link-color;
-}
-
 html {
   @include fs-4;
 

_sass/code.scss

@@ -50,6 +50,11 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
+// or in AsciiDoc:
+//
+//     ----
+//     ...
+//     ----
 
 // the code may appear with 3 different types:
 // container \ case:  default case,          code with line number,   code with html rendering
@@ -59,6 +64,7 @@ a:visited code {
 // last level:        code,                  pre,                     code (optionality)
 // highlighter level: span,                  span,                    span
 // the spacing are only in the second level for case 1, 3 and in the third level for case 2
+// in AsciiDoc, there is a parent container that contains optionally a title and the content.
 
 // select top level container
 div.highlighter-rouge,
@@ -111,17 +117,17 @@ figure.highlight {
 }
 
 // setting the spacing and scrollbar on the second level for the first case
-// remove all space on the second and thirt level
+// remove all space on the second and third level
-div.highlighter-rouge,
+// this is a mixin to accommodate for the slightly different structures generated via Markdown vs AsciiDoc
-div.listingblock {
+@mixin scroll-and-spacing($code-div, $pre-select) {
-  div.highlight {
+  #{$code-div} {
     overflow-x: auto;
     padding: $sp-3;
     margin: 0;
     border: 0;
   }
 
-  pre.highlight,
+  #{$pre-select},
   code {
     padding: 0;
     margin: 0;
@@ -129,6 +135,19 @@ div.listingblock {
   }
 }
 
+// for Markdown
+div.highlighter-rouge {
+  @include scroll-and-spacing("div.highlight", "pre.highlight");
+}
+
+// for AsciiDoc. we also need to fix the margins for its parent container.
+div.listingblock {
+  @include scroll-and-spacing("div.content", "div.content > pre");
+
+  margin-top: 0;
+  margin-bottom: $sp-3;
+}
+
 // {% highlight LANG %}...{% endhighlight %},
 // {% highlight LANG linenos %}...{% endhighlight %}:
 

_sass/color_schemes/dark.scss

@@ -1,32 +1,17 @@
 $body-background-color: $grey-dk-300;
-$sidebar-color: $grey-dk-300;
-$border-color: $grey-dk-200;
-$body-text-color: $grey-lt-300;
 $body-heading-color: $grey-lt-000;
-$nav-child-link-color: $grey-dk-000;
+$body-text-color: $grey-lt-300;
-$search-result-preview-color: $grey-dk-000;
 $link-color: $blue-000;
-$btn-primary-color: $blue-200;
+$nav-child-link-color: $grey-dk-000;
+$sidebar-color: $grey-dk-300;
 $base-button-color: $grey-dk-250;
-$search-background-color: $grey-dk-250;
+$btn-primary-color: $blue-200;
-$table-background-color: $grey-dk-250;
-$feedback-color: darken($sidebar-color, 3%);
-
-// The following highlight theme is more legible than that used for the light color scheme
-
-// @import "./vendor/OneDarkJekyll/syntax-one-dark";
-// $code-background-color: #282c34; // OneDarkJekyll default for syntax-one-dark
-// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-one-dark
-
-@import "./vendor/OneDarkJekyll/syntax-one-dark-vivid";
-
 $code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid
 $code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid
+$feedback-color: darken($sidebar-color, 3%);
+$table-background-color: $grey-dk-250;
+$search-background-color: $grey-dk-250;
+$search-result-preview-color: $grey-dk-000;
+$border-color: $grey-dk-200;
 
-// @import "./vendor/OneDarkJekyll/syntax-firewatch";
+@import "./vendor/OneDarkJekyll/syntax"; // this is the one-dark-vivid atom syntax theme
-// $code-background-color: #282c34; // OneDarkJekyll default for syntax-firewatch
-// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-firewatch
-
-// @import "./vendor/OneDarkJekyll/syntax-firewatch-green";
-// $code-background-color: #282c34; // OneDarkJekyll default for syntax-firewatch-green
-// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-firewatch-green

_sass/color_schemes/legacy_light.scss

@@ -0,0 +1,208 @@
+// Moved from _sass/code.scss
+
+.highlight .c {
+  color: #586e75;
+} // comment //
+.highlight .err {
+  color: #93a1a1;
+} // error //
+.highlight .g {
+  color: #93a1a1;
+} // generic //
+.highlight .k {
+  color: #859900;
+} // keyword //
+.highlight .l {
+  color: #93a1a1;
+} // literal //
+.highlight .n {
+  color: #93a1a1;
+} // name //
+.highlight .o {
+  color: #859900;
+} // operator //
+.highlight .x {
+  color: #cb4b16;
+} // other //
+.highlight .p {
+  color: #93a1a1;
+} // punctuation //
+.highlight .cm {
+  color: #586e75;
+} // comment.multiline //
+.highlight .cp {
+  color: #859900;
+} // comment.preproc //
+.highlight .c1 {
+  color: #586e75;
+} // comment.single //
+.highlight .cs {
+  color: #859900;
+} // comment.special //
+.highlight .gd {
+  color: #2aa198;
+} // generic.deleted //
+.highlight .ge {
+  font-style: italic;
+  color: #93a1a1;
+} // generic.emph //
+.highlight .gr {
+  color: #dc322f;
+} // generic.error //
+.highlight .gh {
+  color: #cb4b16;
+} // generic.heading //
+.highlight .gi {
+  color: #859900;
+} // generic.inserted //
+.highlight .go {
+  color: #93a1a1;
+} // generic.output //
+.highlight .gp {
+  color: #93a1a1;
+} // generic.prompt //
+.highlight .gs {
+  font-weight: bold;
+  color: #93a1a1;
+} // generic.strong //
+.highlight .gu {
+  color: #cb4b16;
+} // generic.subheading //
+.highlight .gt {
+  color: #93a1a1;
+} // generic.traceback //
+.highlight .kc {
+  color: #cb4b16;
+} // keyword.constant //
+.highlight .kd {
+  color: #268bd2;
+} // keyword.declaration //
+.highlight .kn {
+  color: #859900;
+} // keyword.namespace //
+.highlight .kp {
+  color: #859900;
+} // keyword.pseudo //
+.highlight .kr {
+  color: #268bd2;
+} // keyword.reserved //
+.highlight .kt {
+  color: #dc322f;
+} // keyword.type //
+.highlight .ld {
+  color: #93a1a1;
+} // literal.date //
+.highlight .m {
+  color: #2aa198;
+} // literal.number //
+.highlight .s {
+  color: #2aa198;
+} // literal.string //
+.highlight .na {
+  color: #555;
+} // name.attribute //
+.highlight .nb {
+  color: #b58900;
+} // name.builtin //
+.highlight .nc {
+  color: #268bd2;
+} // name.class //
+.highlight .no {
+  color: #cb4b16;
+} // name.constant //
+.highlight .nd {
+  color: #268bd2;
+} // name.decorator //
+.highlight .ni {
+  color: #cb4b16;
+} // name.entity //
+.highlight .ne {
+  color: #cb4b16;
+} // name.exception //
+.highlight .nf {
+  color: #268bd2;
+} // name.function //
+.highlight .nl {
+  color: #555;
+} // name.label //
+.highlight .nn {
+  color: #93a1a1;
+} // name.namespace //
+.highlight .nx {
+  color: #555;
+} // name.other //
+.highlight .py {
+  color: #93a1a1;
+} // name.property //
+.highlight .nt {
+  color: #268bd2;
+} // name.tag //
+.highlight .nv {
+  color: #268bd2;
+} // name.variable //
+.highlight .ow {
+  color: #859900;
+} // operator.word //
+.highlight .w {
+  color: #93a1a1;
+} // text.whitespace //
+.highlight .mf {
+  color: #2aa198;
+} // literal.number.float //
+.highlight .mh {
+  color: #2aa198;
+} // literal.number.hex //
+.highlight .mi {
+  color: #2aa198;
+} // literal.number.integer //
+.highlight .mo {
+  color: #2aa198;
+} // literal.number.oct //
+.highlight .sb {
+  color: #586e75;
+} // literal.string.backtick //
+.highlight .sc {
+  color: #2aa198;
+} // literal.string.char //
+.highlight .sd {
+  color: #93a1a1;
+} // literal.string.doc //
+.highlight .s2 {
+  color: #2aa198;
+} // literal.string.double //
+.highlight .se {
+  color: #cb4b16;
+} // literal.string.escape //
+.highlight .sh {
+  color: #93a1a1;
+} // literal.string.heredoc //
+.highlight .si {
+  color: #2aa198;
+} // literal.string.interpol //
+.highlight .sx {
+  color: #2aa198;
+} // literal.string.other //
+.highlight .sr {
+  color: #dc322f;
+} // literal.string.regex //
+.highlight .s1 {
+  color: #2aa198;
+} // literal.string.single //
+.highlight .ss {
+  color: #2aa198;
+} // literal.string.symbol //
+.highlight .bp {
+  color: #268bd2;
+} // name.builtin.pseudo //
+.highlight .vc {
+  color: #268bd2;
+} // name.variable.class //
+.highlight .vg {
+  color: #268bd2;
+} // name.variable.global //
+.highlight .vi {
+  color: #268bd2;
+} // name.variable.instance //
+.highlight .il {
+  color: #2aa198;
+} // literal.number.integer.long //

_sass/color_schemes/light.scss

@@ -1,208 +1,15 @@
-// Moved from _sass/code.scss
+$body-background-color: $white !default;
+$body-heading-color: $grey-dk-300 !default;
+$body-text-color: $grey-dk-100 !default;
+$link-color: $purple-000 !default;
+$nav-child-link-color: $grey-dk-100 !default;
+$sidebar-color: $grey-lt-000 !default;
+$base-button-color: #f7f7f7 !default;
+$btn-primary-color: $purple-100 !default;
+$code-background-color: $grey-lt-000 !default;
+$feedback-color: darken($sidebar-color, 3%) !default;
+$table-background-color: $white !default;
+$search-background-color: $white !default;
+$search-result-preview-color: $grey-dk-000 !default;
 
-.highlight .c {
+@import "./vendor/OneLightJekyll/syntax";
-  color: #586e75;
-} // comment //
-.highlight .err {
-  color: #93a1a1;
-} // error //
-.highlight .g {
-  color: #93a1a1;
-} // generic //
-.highlight .k {
-  color: #859900;
-} // keyword //
-.highlight .l {
-  color: #93a1a1;
-} // literal //
-.highlight .n {
-  color: #93a1a1;
-} // name //
-.highlight .o {
-  color: #859900;
-} // operator //
-.highlight .x {
-  color: #cb4b16;
-} // other //
-.highlight .p {
-  color: #93a1a1;
-} // punctuation //
-.highlight .cm {
-  color: #586e75;
-} // comment.multiline //
-.highlight .cp {
-  color: #859900;
-} // comment.preproc //
-.highlight .c1 {
-  color: #586e75;
-} // comment.single //
-.highlight .cs {
-  color: #859900;
-} // comment.special //
-.highlight .gd {
-  color: #2aa198;
-} // generic.deleted //
-.highlight .ge {
-  font-style: italic;
-  color: #93a1a1;
-} // generic.emph //
-.highlight .gr {
-  color: #dc322f;
-} // generic.error //
-.highlight .gh {
-  color: #cb4b16;
-} // generic.heading //
-.highlight .gi {
-  color: #859900;
-} // generic.inserted //
-.highlight .go {
-  color: #93a1a1;
-} // generic.output //
-.highlight .gp {
-  color: #93a1a1;
-} // generic.prompt //
-.highlight .gs {
-  font-weight: bold;
-  color: #93a1a1;
-} // generic.strong //
-.highlight .gu {
-  color: #cb4b16;
-} // generic.subheading //
-.highlight .gt {
-  color: #93a1a1;
-} // generic.traceback //
-.highlight .kc {
-  color: #cb4b16;
-} // keyword.constant //
-.highlight .kd {
-  color: #268bd2;
-} // keyword.declaration //
-.highlight .kn {
-  color: #859900;
-} // keyword.namespace //
-.highlight .kp {
-  color: #859900;
-} // keyword.pseudo //
-.highlight .kr {
-  color: #268bd2;
-} // keyword.reserved //
-.highlight .kt {
-  color: #dc322f;
-} // keyword.type //
-.highlight .ld {
-  color: #93a1a1;
-} // literal.date //
-.highlight .m {
-  color: #2aa198;
-} // literal.number //
-.highlight .s {
-  color: #2aa198;
-} // literal.string //
-.highlight .na {
-  color: #555;
-} // name.attribute //
-.highlight .nb {
-  color: #b58900;
-} // name.builtin //
-.highlight .nc {
-  color: #268bd2;
-} // name.class //
-.highlight .no {
-  color: #cb4b16;
-} // name.constant //
-.highlight .nd {
-  color: #268bd2;
-} // name.decorator //
-.highlight .ni {
-  color: #cb4b16;
-} // name.entity //
-.highlight .ne {
-  color: #cb4b16;
-} // name.exception //
-.highlight .nf {
-  color: #268bd2;
-} // name.function //
-.highlight .nl {
-  color: #555;
-} // name.label //
-.highlight .nn {
-  color: #93a1a1;
-} // name.namespace //
-.highlight .nx {
-  color: #555;
-} // name.other //
-.highlight .py {
-  color: #93a1a1;
-} // name.property //
-.highlight .nt {
-  color: #268bd2;
-} // name.tag //
-.highlight .nv {
-  color: #268bd2;
-} // name.variable //
-.highlight .ow {
-  color: #859900;
-} // operator.word //
-.highlight .w {
-  color: #93a1a1;
-} // text.whitespace //
-.highlight .mf {
-  color: #2aa198;
-} // literal.number.float //
-.highlight .mh {
-  color: #2aa198;
-} // literal.number.hex //
-.highlight .mi {
-  color: #2aa198;
-} // literal.number.integer //
-.highlight .mo {
-  color: #2aa198;
-} // literal.number.oct //
-.highlight .sb {
-  color: #586e75;
-} // literal.string.backtick //
-.highlight .sc {
-  color: #2aa198;
-} // literal.string.char //
-.highlight .sd {
-  color: #93a1a1;
-} // literal.string.doc //
-.highlight .s2 {
-  color: #2aa198;
-} // literal.string.double //
-.highlight .se {
-  color: #cb4b16;
-} // literal.string.escape //
-.highlight .sh {
-  color: #93a1a1;
-} // literal.string.heredoc //
-.highlight .si {
-  color: #2aa198;
-} // literal.string.interpol //
-.highlight .sx {
-  color: #2aa198;
-} // literal.string.other //
-.highlight .sr {
-  color: #dc322f;
-} // literal.string.regex //
-.highlight .s1 {
-  color: #2aa198;
-} // literal.string.single //
-.highlight .ss {
-  color: #2aa198;
-} // literal.string.symbol //
-.highlight .bp {
-  color: #268bd2;
-} // name.builtin.pseudo //
-.highlight .vc {
-  color: #268bd2;
-} // name.variable.class //
-.highlight .vg {
-  color: #268bd2;
-} // name.variable.global //
-.highlight .vi {
-  color: #268bd2;
-} // name.variable.instance //
-.highlight .il {
-  color: #2aa198;
-} // literal.number.integer.long //

_sass/layout.scss

@@ -29,9 +29,13 @@
   }
 
   @include mq(lg) {
-    margin-left: calc(
+    // stylelint-disable function-name-case
-      (100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}
+    // disable for Max(), we want to use the CSS max() function
+    margin-left: Max(
+      #{$nav-width},
+      calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
     );
+    // stylelint-enable function-name-case
   }
 }
 

_sass/support/_variables.scss

@@ -56,19 +56,6 @@ $red-000: #f77e7e !default;
 $red-100: #f96e65 !default;
 $red-200: #e94c4c !default;
 $red-300: #dd2e2e !default;
-$body-background-color: $white !default;
-$sidebar-color: $grey-lt-000 !default;
-$search-background-color: $white !default;
-$table-background-color: $white !default;
-$code-background-color: $grey-lt-000 !default;
-$feedback-color: darken($sidebar-color, 3%) !default;
-$body-text-color: $grey-dk-100 !default;
-$body-heading-color: $grey-dk-300 !default;
-$search-result-preview-color: $grey-dk-000 !default;
-$nav-child-link-color: $grey-dk-100 !default;
-$link-color: $purple-000 !default;
-$btn-primary-color: $purple-100 !default;
-$base-button-color: #f7f7f7 !default;
 
 // Spacing
 

_sass/support/mixins/_layout.scss

@@ -16,8 +16,7 @@
       @content;
     }
   } @else {
-    @warn "No value could be retrieved from `#{$media-query}`. "
+    @warn "No value could be retrieved from `#{$media-query}`. Please make sure it is defined in `$media-queries` map.";
-      + "Please make sure it is defined in `$media-queries` map.";
   }
 }
 

_sass/vendor/OneDarkJekyll/README.md

@@ -1,25 +0,0 @@
-# OneDarkJekyll
-
-*Use Atom's One Dark syntax colors in your Jekyll powered blog!*
-
-It's LESS file which can be compiled to a - Pygments, Rouge compatible - stylesheet from Atom editor's One Dark syntax theme (and any theme based on it, for example One Dark Vivid, Firewatch, etc.).
-
-Download the stylesheet files or compile a new one from any Atom syntax theme which based on One Dark (the variable names in `colors.less` must match with One Dark's)
-
-## Create a new syntax stylesheet
-
-1. `npm install -g less less-plugin-clean-css`
-2. Clone this repository
-3. Download the `colors.css` file from the syntax theme's repository (for example https://github.com/atom/one-dark-syntax/blob/master/styles/colors.less in case of One-Dark)
-4. Put the previously downloaded file next to `syntax.less`
-5. Run `lessc syntax.less syntax.css --clean-css`
-6. Use the `syntax.css`
-
-It's not final and in case you find any error/improvement feel free to create a PR. :)
-
-----
-
-# UPDATES FOR USE IN JUST-THE-DOCS:
-
-1. Layout added in `*.css`
-2. Renamed `*.css` to `*.scss`

_sass/vendor/OneDarkJekyll/colors.less

@@ -1,30 +0,0 @@
-// Config -----------------------------------
-@syntax-hue:          220;
-@syntax-saturation:   13%;
-@syntax-brightness:   18%;
-
-
-// Monochrome -----------------------------------
-@mono-1: hsl(@syntax-hue, 14%, 71%); // default text
-@mono-2: hsl(@syntax-hue,  9%, 55%);
-@mono-3: hsl(@syntax-hue, 10%, 40%);
-
-// Colors -----------------------------------
-@hue-1:   hsl(187, 47%, 55%); // <-cyan
-@hue-2:   hsl(207, 82%, 66%); // <-blue
-@hue-3:   hsl(286, 60%, 67%); // <-purple
-@hue-4:   hsl( 95, 38%, 62%); // <-green
-
-@hue-5:   hsl(355, 65%, 65%); // <-red 1
-@hue-5-2: hsl(  5, 48%, 51%); // <-red 2
-
-@hue-6:   hsl( 29, 54%, 61%); // <-orange 1
-@hue-6-2: hsl( 39, 67%, 69%); // <-orange 2
-
-
-// Base colors -----------------------------------
-@syntax-fg:     @mono-1;
-@syntax-bg:     hsl(@syntax-hue, @syntax-saturation, @syntax-brightness);
-@syntax-gutter: darken(@syntax-fg, 26%);
-@syntax-guide:  fade(@syntax-fg, 15%);
-@syntax-accent: hsl(@syntax-hue, 100%, 66% );

_sass/vendor/OneDarkJekyll/syntax-firewatch.scss

@@ -1,200 +0,0 @@
-.highlight,
-pre.highlight {
-  background: #282c34;
-  color: #abb2bf;
-}
-.highlight pre {
-  background: #282c34;
-}
-.highlight .hll {
-  background: #282c34;
-}
-.highlight .c {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .err {
-  color: #960050;
-  background-color: #1e0010;
-}
-.highlight .k {
-  color: #dd672c;
-}
-.highlight .l {
-  color: #c8ae9d;
-}
-.highlight .n {
-  color: #abb2bf;
-}
-.highlight .o {
-  color: #abb2bf;
-}
-.highlight .p {
-  color: #abb2bf;
-}
-.highlight .cm {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cp {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .c1 {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cs {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .ge {
-  font-style: italic;
-}
-.highlight .gs {
-  font-weight: 700;
-}
-.highlight .kc {
-  color: #dd672c;
-}
-.highlight .kd {
-  color: #dd672c;
-}
-.highlight .kn {
-  color: #dd672c;
-}
-.highlight .kp {
-  color: #dd672c;
-}
-.highlight .kr {
-  color: #dd672c;
-}
-.highlight .kt {
-  color: #dd672c;
-}
-.highlight .ld {
-  color: #c8ae9d;
-}
-.highlight .m {
-  color: #d19a66;
-}
-.highlight .s {
-  color: #c8ae9d;
-}
-.highlight .na {
-  color: #d19a66;
-}
-.highlight .nb {
-  color: #e5c07b;
-}
-.highlight .nc {
-  color: #e5c07b;
-}
-.highlight .no {
-  color: #e5c07b;
-}
-.highlight .nd {
-  color: #e5c07b;
-}
-.highlight .ni {
-  color: #e5c07b;
-}
-.highlight .ne {
-  color: #e5c07b;
-}
-.highlight .nf {
-  color: #abb2bf;
-}
-.highlight .nl {
-  color: #e5c07b;
-}
-.highlight .nn {
-  color: #abb2bf;
-}
-.highlight .nx {
-  color: #abb2bf;
-}
-.highlight .py {
-  color: #e5c07b;
-}
-.highlight .nt {
-  color: #e06c75;
-}
-.highlight .nv {
-  color: #e5c07b;
-}
-.highlight .ow {
-  font-weight: 700;
-}
-.highlight .w {
-  color: #f8f8f2;
-}
-.highlight .mf {
-  color: #d19a66;
-}
-.highlight .mh {
-  color: #d19a66;
-}
-.highlight .mi {
-  color: #d19a66;
-}
-.highlight .mo {
-  color: #d19a66;
-}
-.highlight .sb {
-  color: #c8ae9d;
-}
-.highlight .sc {
-  color: #c8ae9d;
-}
-.highlight .sd {
-  color: #c8ae9d;
-}
-.highlight .s2 {
-  color: #c8ae9d;
-}
-.highlight .se {
-  color: #c8ae9d;
-}
-.highlight .sh {
-  color: #c8ae9d;
-}
-.highlight .si {
-  color: #c8ae9d;
-}
-.highlight .sx {
-  color: #c8ae9d;
-}
-.highlight .sr {
-  color: #56b6c2;
-}
-.highlight .s1 {
-  color: #c8ae9d;
-}
-.highlight .ss {
-  color: #56b6c2;
-}
-.highlight .bp {
-  color: #e5c07b;
-}
-.highlight .vc {
-  color: #e5c07b;
-}
-.highlight .vg {
-  color: #e5c07b;
-}
-.highlight .vi {
-  color: #e06c75;
-}
-.highlight .il {
-  color: #d19a66;
-}
-.highlight .gu {
-  color: #75715e;
-}
-.highlight .gd {
-  color: #f92672;
-}
-.highlight .gi {
-  color: #a6e22e;
-}

_sass/vendor/OneDarkJekyll/syntax-one-dark.scss

@@ -1,200 +0,0 @@
-.highlight,
-pre.highlight {
-  background: #282c34;
-  color: #abb2bf;
-}
-.highlight pre {
-  background: #282c34;
-}
-.highlight .hll {
-  background: #282c34;
-}
-.highlight .c {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .err {
-  color: #960050;
-  background-color: #1e0010;
-}
-.highlight .k {
-  color: #c678dd;
-}
-.highlight .l {
-  color: #98c379;
-}
-.highlight .n {
-  color: #abb2bf;
-}
-.highlight .o {
-  color: #abb2bf;
-}
-.highlight .p {
-  color: #abb2bf;
-}
-.highlight .cm {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cp {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .c1 {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cs {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .ge {
-  font-style: italic;
-}
-.highlight .gs {
-  font-weight: 700;
-}
-.highlight .kc {
-  color: #c678dd;
-}
-.highlight .kd {
-  color: #c678dd;
-}
-.highlight .kn {
-  color: #c678dd;
-}
-.highlight .kp {
-  color: #c678dd;
-}
-.highlight .kr {
-  color: #c678dd;
-}
-.highlight .kt {
-  color: #c678dd;
-}
-.highlight .ld {
-  color: #98c379;
-}
-.highlight .m {
-  color: #d19a66;
-}
-.highlight .s {
-  color: #98c379;
-}
-.highlight .na {
-  color: #d19a66;
-}
-.highlight .nb {
-  color: #e5c07b;
-}
-.highlight .nc {
-  color: #e5c07b;
-}
-.highlight .no {
-  color: #e5c07b;
-}
-.highlight .nd {
-  color: #e5c07b;
-}
-.highlight .ni {
-  color: #e5c07b;
-}
-.highlight .ne {
-  color: #e5c07b;
-}
-.highlight .nf {
-  color: #abb2bf;
-}
-.highlight .nl {
-  color: #e5c07b;
-}
-.highlight .nn {
-  color: #abb2bf;
-}
-.highlight .nx {
-  color: #abb2bf;
-}
-.highlight .py {
-  color: #e5c07b;
-}
-.highlight .nt {
-  color: #e06c75;
-}
-.highlight .nv {
-  color: #e5c07b;
-}
-.highlight .ow {
-  font-weight: 700;
-}
-.highlight .w {
-  color: #f8f8f2;
-}
-.highlight .mf {
-  color: #d19a66;
-}
-.highlight .mh {
-  color: #d19a66;
-}
-.highlight .mi {
-  color: #d19a66;
-}
-.highlight .mo {
-  color: #d19a66;
-}
-.highlight .sb {
-  color: #98c379;
-}
-.highlight .sc {
-  color: #98c379;
-}
-.highlight .sd {
-  color: #98c379;
-}
-.highlight .s2 {
-  color: #98c379;
-}
-.highlight .se {
-  color: #98c379;
-}
-.highlight .sh {
-  color: #98c379;
-}
-.highlight .si {
-  color: #98c379;
-}
-.highlight .sx {
-  color: #98c379;
-}
-.highlight .sr {
-  color: #56b6c2;
-}
-.highlight .s1 {
-  color: #98c379;
-}
-.highlight .ss {
-  color: #56b6c2;
-}
-.highlight .bp {
-  color: #e5c07b;
-}
-.highlight .vc {
-  color: #e5c07b;
-}
-.highlight .vg {
-  color: #e5c07b;
-}
-.highlight .vi {
-  color: #e06c75;
-}
-.highlight .il {
-  color: #d19a66;
-}
-.highlight .gu {
-  color: #75715e;
-}
-.highlight .gd {
-  color: #f92672;
-}
-.highlight .gi {
-  color: #a6e22e;
-}

_sass/vendor/OneDarkJekyll/syntax-variables.less

@@ -1,56 +0,0 @@
-@import "colors.less";
-
-// Official Syntax Variables -----------------------------------
-
-// General colors
-@syntax-text-color:            @syntax-fg;
-@syntax-cursor-color:          @syntax-accent;
-@syntax-selection-color:       lighten(@syntax-background-color, 10%);
-@syntax-selection-flash-color: @syntax-accent;
-@syntax-background-color:      @syntax-bg;
-
-// Guide colors
-@syntax-wrap-guide-color:          @syntax-guide;
-@syntax-indent-guide-color:        @syntax-guide;
-@syntax-invisible-character-color: @syntax-guide;
-
-// For find and replace markers
-@syntax-result-marker-color:          fade(@syntax-accent, 24%);
-@syntax-result-marker-color-selected: @syntax-accent;
-
-// Gutter colors
-@syntax-gutter-text-color:                @syntax-gutter;
-@syntax-gutter-text-color-selected:       @syntax-fg;
-@syntax-gutter-background-color:          @syntax-bg; // unused
-@syntax-gutter-background-color-selected: lighten(@syntax-bg, 2%);
-
-// Git colors - For git diff info. i.e. in the gutter
-@syntax-color-renamed:  hsl(208, 100%, 60%);
-@syntax-color-added:    hsl(150,  60%, 54%);
-@syntax-color-modified: hsl(40,   60%, 70%);
-@syntax-color-removed:  hsl(0,    70%, 60%);
-
-// For language entity colors
-@syntax-color-variable:   @hue-5;
-@syntax-color-constant:   @hue-6;
-@syntax-color-property:   @syntax-fg;
-@syntax-color-value:      @syntax-fg;
-@syntax-color-function:   @hue-2;
-@syntax-color-method:     @hue-2;
-@syntax-color-class:      @hue-6-2;
-@syntax-color-keyword:    @hue-3;
-@syntax-color-tag:        @hue-5;
-@syntax-color-attribute:  @hue-6;
-@syntax-color-import:     @hue-3;
-@syntax-color-snippet:    @hue-4;
-
-
-// Custom Syntax Variables -----------------------------------
-// Don't use in packages
-
-@syntax-cursor-line: hsla(@syntax-hue, 100%,  80%, .04); // needs to be semi-transparent to show search results
-
-@syntax-deprecated-fg: darken(@syntax-color-modified, 50%);
-@syntax-deprecated-bg: @syntax-color-modified;
-@syntax-illegal-fg:    white;
-@syntax-illegal-bg:    @syntax-color-removed;

_sass/vendor/OneDarkJekyll/syntax.less

@@ -1,93 +0,0 @@
-/*
-  LESS for Pygments
-*/
-
-@import "syntax-variables.less";
-
-pre.highlight,
-.highlight {
-  background: @syntax-bg;
-	color: @mono-1;
-}
-.highlight {
- pre { background: @syntax-bg; }
- .hll { background: @syntax-bg; }
- .c {  color: @mono-3; font-style: italic;  } /* Comment */
- .err { color: @syntax-illegal-fg; background-color: @syntax-illegal-bg; } /* Error */
- .k { color: @hue-3;  } /* Keyword */
- .l { color: @hue-4; } /* Literal */
- .n { color: @mono-1; } /* Name */
- .o { color: @mono-1; } /* Operator */
- .p { color: @mono-1; } /* Punctuation */
- .cm { color: @mono-3; font-style: italic; } /* Comment.Multiline */
- .cp { color: @mono-3; font-style: italic; } /* Comment.Preproc */
- .c1 { color: @mono-3; font-style: italic; } /* Comment.Single */
- .cs { color: @mono-3; font-style: italic; } /* Comment.Special */
- .ge { font-style: italic } /* Generic.Emph */
- .gs { font-weight: bold } /* Generic.Strong */
- .kc { color: @hue-3;  } /* Keyword.Constant */
- .kd { color: @hue-3;  } /* Keyword.Declaration */
- .kn { color: @hue-3;  } /* Keyword.Namespace */
- .kp { color: @hue-3;  } /* Keyword.Pseudo */
- .kr { color: @hue-3;  } /* Keyword.Reserved */
- .kt { color: @hue-3;  } /* Keyword.Type */
- .ld { color: @hue-4; } /* Literal.Date */
- .m { color: @hue-6; } /* Literal.Number */
- .s { color: @hue-4; } /* Literal.String */
- .na { color: @hue-6; } /* Name.Attribute */
- .nb { color: @hue-6-2; } /* Name.Builtin */
- .nc { color: @hue-6-2; } /* Name.Class */
- .no { color: @hue-6-2; } /* Name.Constant */
- .nd { color: @hue-6-2; } /* Name.Decorator */
- .ni { color: @hue-6-2; } /* Name.Entity */
- .ne { color: @hue-6-2; } /* Name.Exception */
- .nf { color: @mono-1; } /* Name.Function */
- .nl { color: @hue-6-2; } /* Name.Label */
- .nn { color: @mono-1; } /* Name.Namespace */
- .nx { color: @mono-1; } /* Name.Other */
- .py { color: @hue-6-2; } /* Name.Property */
- .nt { color: @hue-5; } /* Name.Tag */
- .nv { color: @hue-6-2; } /* Name.Variable */
- .ow { font-weight: bold; } /* Operator.Word */
- .w { color: #f8f8f2 } /* Text.Whitespace */
- .mf { color: @hue-6; } /* Literal.Number.Float */
- .mh { color: @hue-6; } /* Literal.Number.Hex */
- .mi { color: @hue-6; } /* Literal.Number.Integer */
- .mo { color: @hue-6; } /* Literal.Number.Oct */
- .sb { color: @hue-4; } /* Literal.String.Backtick */
- .sc { color: @hue-4; } /* Literal.String.Char */
- .sd { color: @hue-4; } /* Literal.String.Doc */
- .s2 { color: @hue-4; } /* Literal.String.Double */
- .se { color: @hue-4; } /* Literal.String.Escape */
- .sh { color: @hue-4; } /* Literal.String.Heredoc */
- .si { color: @hue-4; } /* Literal.String.Interpol */
- .sx { color: @hue-4; } /* Literal.String.Other */
- .sr { color: @hue-1; } /* Literal.String.Regex */
- .s1 { color: @hue-4; } /* Literal.String.Single */
- .ss { color: @hue-1; } /* Literal.String.Symbol */
- .bp { color: @hue-6-2; } /* Name.Builtin.Pseudo */
- .vc { color: @hue-6-2; } /* Name.Variable.Class */
- .vg { color: @hue-6-2; } /* Name.Variable.Global */
- .vi { color: @hue-5; } /* Name.Variable.Instance */
- .il { color: @hue-6; } /* Literal.Number.Integer.Long */
-
- .gh { } /* Generic Heading & Diff Header */
- .gu { color: #75715e; } /* Generic.Subheading & Diff Unified/Comment? */
- .gd { color: @syntax-color-removed; } /* Generic.Deleted & Diff Deleted */
- .gi { color: @syntax-color-added; } /* Generic.Inserted & Diff Inserted */
-	
- ::selection { background-color: @syntax-selection-color; }
-
- .language-json {
-   .w + .s2 { color: @hue-5; }
-   .kc { color: @hue-1; }
- }
-
- .language-python {
-   // python related modifications
- }
-
- .language-csharp {
-   // csharp related modifications
- }
-}

_sass/vendor/OneDarkJekyll/syntax.scss

@@ -1,3 +1,5 @@
+// Generated with OneDarkJekyll applied to Atom's One Dark Vivid theme
+
 .highlight,
 pre.highlight {
   background: #31343f;

_sass/vendor/OneLightJekyll/LICENSE

@@ -0,0 +1,65 @@
+OneLightJekyll relies on two works: OneDarkJekyll, and Atom's One Light theme. This file contains the licensing for all the related software.
+
+---
+
+OneLightJekyll (https://github.com/just-the-docs/OneLightJekyll/blob/main/LICENSE)
+
+MIT License
+
+Copyright (c) 2023 Matthew Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+OneDarkJekyll (https://github.com/mgyongyosi/OneDarkJekyll/blob/master/LICENSE)
+
+MIT License
+
+Copyright (c) 2016 Mihály Gyöngyösi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Atom One Light (https://github.com/atom/atom/blob/master/LICENSE.md)
+
+Copyright (c) 2011-2022 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

_sass/vendor/OneLightJekyll/syntax.scss

@@ -1,51 +1,53 @@
+// Generated with OneLightJekyll applied to Atom's One Light theme
+
 .highlight,
 pre.highlight {
-  background: #282c34;
+  background: #f9f9f9;
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight pre {
-  background: #282c34;
+  background: #f9f9f9;
 }
 .highlight .hll {
-  background: #282c34;
+  background: #f9f9f9;
 }
 .highlight .c {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .err {
-  color: #960050;
+  color: #fff;
-  background-color: #1e0010;
+  background-color: #e05151;
 }
 .highlight .k {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .l {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .n {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .o {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .p {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .cm {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .cp {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .c1 {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .cs {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .ge {
@@ -55,73 +57,73 @@ pre.highlight {
   font-weight: 700;
 }
 .highlight .kc {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kd {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kn {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kp {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kr {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kt {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .ld {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .m {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .s {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .na {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .nb {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nc {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .no {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nd {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ni {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ne {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nf {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .nl {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nn {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .nx {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .py {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nt {
-  color: #77b181;
+  color: #e35549;
 }
 .highlight .nv {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ow {
   font-weight: 700;
@@ -130,71 +132,77 @@ pre.highlight {
   color: #f8f8f2;
 }
 .highlight .mf {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mh {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mi {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mo {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .sb {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sc {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sd {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .s2 {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .se {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sh {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .si {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sx {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sr {
-  color: #56b6c2;
+  color: #0083bb;
 }
 .highlight .s1 {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .ss {
-  color: #56b6c2;
+  color: #0083bb;
 }
 .highlight .bp {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vc {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vg {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vi {
-  color: #77b181;
+  color: #e35549;
 }
 .highlight .il {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .gu {
   color: #75715e;
 }
 .highlight .gd {
-  color: #f92672;
+  color: #e05151;
 }
 .highlight .gi {
-  color: #a6e22e;
+  color: #43d089;
+}
+.highlight .language-json .w + .s2 {
+  color: #e35549;
+}
+.highlight .language-json .kc {
+  color: #0083bb;
 }

assets/images/search.svg

@@ -1 +0,0 @@
-<svg width="28" height="28" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg"><title>Search</title><g fill-rule="nonzero" fill="#959396"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>

assets/js/just-the-docs.js

@@ -488,7 +488,7 @@ jtd.onReady(function(){
 
 jtd.onReady(function(){
 
-  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock, figure.highlight');
+  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
   var svgCopied =  '<svg viewBox="0 0 24 24" class="copy-icon"><use xlink:href="#svg-copied"></use></svg>';

docs/customization.md

@@ -45,6 +45,15 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 });
 </script>
 
+### deprecated: `legacy_light`
+{: .d-inline-block .no_toc }
+
+New (v0.4.2)
+{: .label .label-green }
+
+
+In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who 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.
+
 ## Custom schemes
 
 ### Define a custom scheme
@@ -113,7 +122,7 @@ jtd.setTheme("foo")
 New (v0.4.0)
 {: .label .label-green }
 
-To define new SCSS variables, functions, or override existing theme variables, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section).
+To define new SCSS variables or functions, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section) or overriding color scheme variables (in this case, you should create a new color scheme).
 
 This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example,
 

docs/navigation-structure.md

@@ -254,6 +254,10 @@ aux_links:
 ---
 
 ## External Navigation Links
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
 External links will appear in the navigation after the links to ordinary pages, but before any collections.

docs/ui-components/code.md

@@ -150,14 +150,45 @@ graph TD;
 
 ### Using a local mermaid library
 
-In order to use a local version of the mermaid library instead of one provided by jsDelivr, you can specify a `path` key in the mermaid configuration instead of a `version` key.
+To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g.
 
 ```yaml
 mermaid:
-  # To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
+  version: "10.1.0"
-  path: "/assets/js/mermaid.min.js"
+  # for (v10+)
+  path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
+  # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated
+  # `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
 ```
 
+For mermaid versions `>=10`, this file is imported directly as an ESM module (rather than as a plain `<script>` tag); users should use the `mermaid.esm.min.mjs` file. In contrast, for mermaid versions `<10`, this file is loaded as a script tag; it should be a standalone CJS file (i.e. `mermaid.min.js`).
+
+{: .warning }
+Mermaid versions `10.0` - `10.1` (and possibly, future releases) still encode relative imports in `mermaid.esm.min.mjs`. Local users must copy *all* of the contents of the `dist` folder to the specified path (preserving the relative location of the files). Just the Docs is actively monitoring mermaid releases; an upstream fix is planned.
+
+### Using mermaid with AsciiDoc
+
+Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.
+
+By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. The simplest way to resolve this is to use a [passthrough block](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/):
+{% highlight asciidoc %}
+++++
+<pre class="language-mermaid">
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+</pre>
+++++
+{% 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)!
+
+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.
+
 ## Copy button
 {: .d-inline-block }
 

fixtures/Gemfile-github-pages

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem 'github-pages', group: :jekyll_plugins

fixtures/README.md

@@ -0,0 +1,3 @@
+# Test Fixtures
+
+These files are used by Just the Docs maintainers to test *the theme itself*. **If you are using Just the Docs as a theme, you should not copy these files over.**

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.4.0.rc5"
+  spec.version       = "0.5.0"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 
@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z ':!:*.jpg' ':!:*.png'`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README|CHANGELOG|favicon)}i) }
   spec.executables   << 'just-the-docs'
 
-  spec.add_development_dependency "bundler", "~> 2.3.5"
+  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 "rake", ">= 12.3.1"

package.json

@@ -6,15 +6,41 @@
   "license": "MIT",
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
-    "prettier": "^2.8.3",
+    "npm-run-all": "^4.1.5",
-    "stylelint": "^14.16.1",
+    "prettier": "^2.8.7",
-    "stylelint-config-prettier-scss": "0.0.1",
+    "stylelint": "^15.4.0",
-    "stylelint-config-standard-scss": "^6.1.0",
+    "stylelint-config-standard-scss": "^8.0.0"
-    "stylelint-prettier": "^2.0.0"
   },
   "scripts": {
-    "test": "stylelint '**/*.scss'",
+    "lint": "npm-run-all --parallel --continue-on-error lint:*",
+    "lint:css": "stylelint '**/*.scss'",
+    "lint:formatting": "prettier --check '**/*.{scss,js,json}'",
     "format": "prettier --write '**/*.{scss,js,json}'",
-    "stylelint-check": "stylelint-config-prettier-check"
+    "test": "npm run lint"
+  },
+  "stylelint": {
+    "ignoreFiles": [
+      "assets/css/just-the-docs-default.scss",
+      "assets/css/just-the-docs-light.scss",
+      "assets/css/just-the-docs-dark.scss",
+      "_sass/vendor/**/*.scss"
+    ],
+    "extends": [
+      "stylelint-config-standard-scss"
+    ],
+    "rules": {
+      "alpha-value-notation": null,
+      "at-rule-empty-line-before": null,
+      "color-function-notation": null,
+      "no-descending-specificity": null,
+      "scss/no-global-function-names": null
+    }
+  },
+  "prettier": {
+    "endOfLine": "lf",
+    "semi": false,
+    "singleQuote": false,
+    "tabWidth": 2,
+    "trailingComma": "es5"
   }
 }