diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 055d7e0..5e56136 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,37 +1,35 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: // https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll { - "name": "Just the docs", - "build": { - "dockerfile": "Dockerfile", - "args": { - // Update 'VARIANT' to pick a Debian OS version: bullseye, buster - // Use bullseye when on local arm64/Apple Silicon. - "VARIANT": "bullseye", - // Enable Node.js: pick the latest LTS version - "NODE_VERSION": "lts/*" - } - }, + "name": "Just the docs", + "build": { + "dockerfile": "Dockerfile", + "args": { + // Update 'VARIANT' to pick a Debian OS version: bullseye, buster + // Use bullseye when on local arm64/Apple Silicon. + "VARIANT": "bullseye", + // Enable Node.js: pick the latest LTS version + "NODE_VERSION": "lts/*" + } + }, - // Set *default* container specific settings.json values on container create. - "settings": {}, + // Set *default* container specific settings.json values on container create. + "settings": {}, - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "GitHub.vscode-pull-request-github" - ], + // Add the IDs of extensions you want installed when the container is created. + "extensions": ["GitHub.vscode-pull-request-github"], - // Use 'forwardPorts' to make a list of ports inside the container available locally. - "forwardPorts": [ - // Jekyll server - 4000, - // Live reload server - 35729 - ], + // Use 'forwardPorts' to make a list of ports inside the container available locally. + "forwardPorts": [ + // Jekyll server + 4000, + // Live reload server + 35729 + ], - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "sh .devcontainer/post-create.sh", + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "sh .devcontainer/post-create.sh", - // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. - "remoteUser": "vscode" + // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode" } diff --git a/.stylelintrc.json b/.stylelintrc.json index 329ca34..dfe788c 100644 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -5,9 +5,17 @@ "assets/css/just-the-docs-dark.scss", "_sass/vendor/**/*.scss" ], - "extends": ["stylelint-config-primer", "stylelint-config-prettier"], + "extends": [ + "stylelint-config-standard-scss", + "stylelint-config-prettier-scss" + ], "plugins": ["stylelint-prettier"], "rules": { - "prettier/prettier": true + "prettier/prettier": true, + "alpha-value-notation": null, + "color-function-notation": null, + "declaration-block-no-redundant-longhand-properties": null, + "no-descending-specificity": null, + "scss/no-global-function-names": null } } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index e8b6253..6d5d5f3 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -1,26 +1,26 @@ { - // See https://go.microsoft.com/fwlink/?LinkId=733558 - // for the documentation about the tasks.json format - "version": "2.0.0", - "tasks": [ - { - "label": "Serve", - "type": "shell", - "command": "bundle exec jekyll serve --livereload", - "group": { - "kind": "test", - "isDefault": true - }, - "isBackground": true, - }, - { - "label": "Build", - "type": "shell", - "command": "bundle exec jekyll build", - "group": { - "kind": "build", - "isDefault": true - }, - } - ] -} \ No newline at end of file + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Serve", + "type": "shell", + "command": "bundle exec jekyll serve --livereload", + "group": { + "kind": "test", + "isDefault": true + }, + "isBackground": true + }, + { + "label": "Build", + "type": "shell", + "command": "bundle exec jekyll build", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} diff --git a/404.html b/404.html index 5fde966..a2d250a 100644 --- a/404.html +++ b/404.html @@ -8,4 +8,4 @@ search_exclude: true

Page not found

-

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

+

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

diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bb1260..75e9c9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,107 @@ All notable changes to this project are documented in this file. ## Head -Major work in progress. Please see [PR #892](https://github.com/just-the-docs/just-the-docs/pull/892) for a v0.4.0 release candidate. +Major work in progress. Please see [PR #892](https://github.com/just-the-docs/just-the-docs/pull/892) for a v0.4.0 release candidate. The following changelog notes are a draft (and not final). + +### Features + +* Added: Combination by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/578 + - Added: dark highlighting in https://github.com/just-the-docs/just-the-docs/pull/463 + - Added: pages and collections in https://github.com/just-the-docs/just-the-docs/pull/448 + - Added: callouts in https://github.com/just-the-docs/just-the-docs/pull/466 + - Fixed: breadcrumb behaviour … by @AdityaTiwari2102 in https://github.com/just-the-docs/just-the-docs/pull/477 + - Fixed: prevent rake command corrupting search data in https://github.com/just-the-docs/just-the-docs/pull/495 (also listed below) + - Fixed: nested lists in https://github.com/just-the-docs/just-the-docs/pull/496 + - Fixed: set color for search input in https://github.com/just-the-docs/just-the-docs/pull/498 (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in https://github.com/just-the-docs/just-the-docs/pull/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 https://github.com/just-the-docs/just-the-docs/pull/639 + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by @svrooij in https://github.com/just-the-docs/just-the-docs/pull/544 +* Added: custom favicon `_includes` by @burner1024 in https://github.com/just-the-docs/just-the-docs/pull/364 +* Added: set color for search input by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/498 +* Added: search placeholder configuration by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/613 +* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by @jmertic in https://github.com/just-the-docs/just-the-docs/pull/726 +* Added: `nav_footer_custom` include by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/474 +* Added: style fixes for jekyll-asciidoc by @alyssais in https://github.com/just-the-docs/just-the-docs/pull/829 +* Added: mermaid.js support by @nascosto in https://github.com/just-the-docs/just-the-docs/pull/857 +* Added: support for external navigation links by @SPGoding in https://github.com/just-the-docs/just-the-docs/pull/876 +* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/909 +* Fixed: prepend `site.collections_dir` if exists by @alexsegura in https://github.com/just-the-docs/just-the-docs/pull/519 +* Fixed: nested task lists (#517) by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/855 +* Fixed: suppress Liquid processing in CSS comments by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/686 +* Fixed: prevent rake command from corrupting search data by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/495 +* Fixed: anchor heading links should be visible on focus by @jacobhq in https://github.com/just-the-docs/just-the-docs/pull/846 +* Fixed: add `overflow-x: auto` to `figure.highlight` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/727 +* Fixed: add `overflow-wrap: word-break` to `body` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/889 +* Fixed: vertical alignment for consecutive labels by @Eisverygoodletter in https://github.com/just-the-docs/just-the-docs/pull/893 +* Fixed: allow links to wrap by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/905 +* Fixed: nav scroll feature and absolute/relative URLs by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/898 + +### Documentation + +* Added: docs on how to break an `ol` by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/856 +* Added: docs for custom includes by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/806 +* Added: document caveat about variable dependencies by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/555 +* Added: docs on how to use `custom_head` to add a custom favicon by @UnclassedPenguin in https://github.com/just-the-docs/just-the-docs/pull/814 +* Fixed: `ol` on `index.md` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/778 +* Fixed: image link in Markdown kitchen sink by @JeffGuKang in https://github.com/just-the-docs/just-the-docs/pull/221 +* Fixed: images in Markdown kitchen sink by @dougaitken in https://github.com/just-the-docs/just-the-docs/pull/782 +* Fixed: clearer label of link to Jekyll quickstart by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/549 +* Fixed: remove extra spaces in component docs by @MichelleBlanchette in https://github.com/just-the-docs/just-the-docs/pull/554 +* Fixed: double "your" typo in `index.md` by @sehilyi in https://github.com/just-the-docs/just-the-docs/pull/499 +* Fixed: "you" -> "your" typo in `index.md` by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/473 +* Fixed: spacing in toc example by @henryiii in https://github.com/just-the-docs/just-the-docs/pull/835 +* Fixed: typo in `README` on `_config.yml` by @ivanskodje in https://github.com/just-the-docs/just-the-docs/pull/891 +* Fixed: missing code fence in navigation structure docs by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/906 + +### Maintenance + +* Added: VScode devcontainer by @max06 in https://github.com/just-the-docs/just-the-docs/pull/783 +* Added: `webrick` to `Gemfile` by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/799 +* Added: 'This site is powered by Netlify.' to the footer by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/797 +* Updated: new repo path by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/775 +* Updated: rename `master` -> `main` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/776 +* Updated: README by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/777 +* Updated: Code of Conduct to Contributor Covenant v2.1 by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/790 +* Updated: CI files, Ruby & Node Versions by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/820 +* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/821 + +### Dependencies +* Upgrade to GitHub-native Dependabot by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/627 +* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/606 +* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/641 +* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/640 +* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/511 +* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/699 +* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/766 +* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/787 +* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/809 +* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/864 + +### New Contributors +* @alexsegura made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/519 +* @burner1024 made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/364 +* @JeffGuKang made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/221 +* @dougaitken made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/782 +* @max06 made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/783 +* @sehilyi made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/499 +* @nathanjessen made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/473 +* @waldyrious made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/549 +* @MichelleBlanchette made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/554 +* @henryiii made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/835 +* @jmertic made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/726 +* @jacobhq made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/846 +* @UnclassedPenguin made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/814 +* @alyssais made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/829 +* @nascosto made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/857 +* @SPGoding made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/876 +* @iridazzle made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/727 +* @ivanskodje made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/891 +* @Eisverygoodletter made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/893 + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0 ## v0.3.3 diff --git a/_config.yml b/_config.yml index a8a3b6d..348c984 100644 --- a/_config.yml +++ b/_config.yml @@ -19,15 +19,7 @@ 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 permalink: pretty -exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile" -, "docs/tests/" -] - -# Regression tests -# By default, the pages in /docs/tests are excluded when the ste is built. -# To include them, comment-out the relevant line above. -# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791 -# include: ["docs/tests/"] +exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"] # Set a path/url to a logo that will be displayed instead of the title #logo: "/assets/images/just-the-docs.png" @@ -59,6 +51,15 @@ search: # Supports true or false (default) button: false +# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/), +# uncomment the `mermaid` and `version` keys below +# mermaid: +# # Version of mermaid library +# # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ +# version: "9.1.3" +# # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js +# # See also docs/ui-components/code + # Enable or disable heading anchors heading_anchors: true @@ -74,6 +75,11 @@ aux_links_new_tab: false # nav_sort: case_insensitive # default, equivalent to nil nav_sort: case_sensitive # Capital letters sorted before lowercase +# External navigation links +nav_external_links: + - title: Just the Docs on GitHub + url: https://github.com/just-the-docs/just-the-docs + # Footer content # appears at the bottom of every page's main content diff --git a/_includes/css/callouts.scss.liquid b/_includes/css/callouts.scss.liquid new file mode 100644 index 0000000..e99600e --- /dev/null +++ b/_includes/css/callouts.scss.liquid @@ -0,0 +1,93 @@ +{%- comment -%} + {% include css/callouts.scss.liquid color_scheme = string %} + produces SCSS for all the callouts in site.callouts. For the "dark" + color scheme, the levels of the text and background colors are reversed. +{%- endcomment -%} + +{%- assign callout_background_hue = "000" -%} +{%- assign callout_color_hue = "300" -%} +{%- if site.callouts_level == "loud" or include.color_scheme == "dark" and site.callouts_level != "quiet" -%} + {%- assign callout_background_hue = "300" -%} + {%- assign callout_color_hue = "000" -%} +{%- endif -%} + +div.opaque { + background-color: $body-background-color; +} + +{%- for callout in site.callouts %} + +{%- assign callout_opacity = callout[1].opacity | default: site.callouts_opacity | default: 0.2 -%} + +p.{{ callout[0] }}, blockquote.{{ callout[0] }} { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + {% if callout[1].title %} + &::before { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + content: "{{ callout[1].title }}"; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } + {% endif %} + > .{{ callout[0] }}-title { + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +p.{{ callout[0] }}-title, blockquote.{{ callout[0] }}-title { + background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }}); + border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }}; + border-radius: $border-radius; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + padding: .8rem; + > p:first-child { + margin-top: 0; + margin-bottom: 0; + color: ${{ callout[1].color }}-{{ callout_color_hue }}; + display: block; + font-weight: bold; + text-transform: uppercase; + font-size: .75em; + padding-bottom: .125rem; + } +} + +blockquote.{{ callout[0] }} { + margin-left: 0; + margin-right: 0; + + > p:first-child { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +blockquote.{{ callout[0] }}-title { + margin-left: 0; + margin-right: 0; + + > p:nth-child(2) { + margin-top: 0; + } + + > p:last-child { + margin-bottom: 0; + } +} + +{% endfor -%} diff --git a/_includes/css/just-the-docs.scss.liquid b/_includes/css/just-the-docs.scss.liquid index 495cd6d..29d5690 100644 --- a/_includes/css/just-the-docs.scss.liquid +++ b/_includes/css/just-the-docs.scss.liquid @@ -1,7 +1,8 @@ {% if site.logo %} -$logo: "{{ site.logo | absolute_url }}"; +$logo: "{{ site.logo | relative_url }}"; {% endif %} @import "./support/support"; @import "./color_schemes/{{ include.color_scheme }}"; @import "./modules"; {% include css/custom.scss.liquid %} +{% include css/callouts.scss.liquid color_scheme = include.color_scheme %} diff --git a/_includes/favicon.html b/_includes/favicon.html new file mode 100644 index 0000000..c485d4c --- /dev/null +++ b/_includes/favicon.html @@ -0,0 +1 @@ + diff --git a/_includes/head.html b/_includes/head.html index c0f73d7..ef48ba9 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -10,7 +10,7 @@ {% endif %} {% endunless %} - + {% include favicon.html %} @@ -29,6 +29,11 @@ {% if site.search_enabled != false %} {% endif %} + + {% if site.mermaid %} + + {% endif %} + diff --git a/_includes/icons/external_link.html b/_includes/icons/external_link.html new file mode 100644 index 0000000..1592be6 --- /dev/null +++ b/_includes/icons/external_link.html @@ -0,0 +1,5 @@ + + + (external link) + + diff --git a/_includes/mermaid_config.js b/_includes/mermaid_config.js new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/_includes/mermaid_config.js @@ -0,0 +1 @@ +{} diff --git a/_includes/nav.html b/_includes/nav.html index 325a68c..0d2e6ef 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -60,13 +60,17 @@ {%- for node in pages_list -%} {%- if node.parent == nil -%} {%- unless node.nav_exclude -%} -