diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml new file mode 100644 index 0000000..b88834e --- /dev/null +++ b/.github/release-drafter.yml @@ -0,0 +1,34 @@ +references: + - v+ +name-template: 'v$RESOLVED_VERSION 🌈' +tag-template: 'v$RESOLVED_VERSION' +categories: + - title: '🚀 Features' + labels: + - 'feature' + - 'enhancement' + - title: '🐛 Bug Fixes' + labels: + - 'fix' + - 'bugfix' + - 'bug' + - title: '🧰 Maintenance' + label: + - 'chore' + - 'dependencies' +change-template: '- $TITLE @$AUTHOR (#$NUMBER)' +version-resolver: + major: + labels: + - 'next-major-release' + minor: + labels: + - 'next-minor-release' + patch: + labels: + - 'patch' + default: minor +template: | + ## Changes + + $CHANGES diff --git a/.github/workflows/ci-master.yml b/.github/workflows/ci-master.yml new file mode 100644 index 0000000..6d41eb5 --- /dev/null +++ b/.github/workflows/ci-master.yml @@ -0,0 +1,45 @@ +on: + push: + branches: + - master + +name: Master branch CI + +jobs: + + jekyll-latest: + name: Build Jekyll site (latest) + runs-on: ubuntu-latest + steps: + + - uses: actions/checkout@master + + - name: Build the site in the jekyll/builder container + run: | + docker run --rm \ + --volume="${{ github.workspace }}:/srv/jekyll" \ + jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" + jekyll-3-8-5: + name: Build Jekyll site (v3.8.5) + runs-on: ubuntu-latest + steps: + + - uses: actions/checkout@master + + - name: Build the site in the jekyll/builder container + run: | + docker run --rm \ + --volume="${{ github.workspace }}:/srv/jekyll" \ + jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" + assets: + name: Format and test CSS and JS + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Use Node.js 12.x + uses: actions/setup-node@v1 + with: + node-version: '12.x' + - run: npm install + - run: npm test diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 926b7f5..3fb7809 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,64 +9,36 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@master + - uses: actions/checkout@v2 - name: Build the site in the jekyll/builder container run: | docker run --rm \ --volume="${{ github.workspace }}:/srv/jekyll" \ - jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && jekyll build && bundle exec just-the-docs rake search:init" + jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" jekyll-3-8-5: name: Build Jekyll site (v3.8.5) runs-on: ubuntu-latest steps: - - uses: actions/checkout@master + - uses: actions/checkout@v2 - name: Build the site in the jekyll/builder container run: | docker run --rm \ --volume="${{ github.workspace }}:/srv/jekyll" \ - jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && jekyll build && bundle exec just-the-docs rake search:init" + jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" assets: - name: Format and test CSS and JS + name: Test CSS and JS runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - # Using this so the this instead of GITHUB_TOKEN so that this workflow can trigger another - with: - token: ${{ secrets.PAT }} - name: Use Node.js 12.x uses: actions/setup-node@v1 with: node-version: '12.x' - - name: Extract branch name - shell: bash - run: echo "##[set-output name=branch;]$(echo ${GITHUB_HEAD_REF#refs/heads/})" - id: extract_branch - - run: npm install - - run: npm run format - - name: Add changed files - run: | - echo "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git" - git config --global user.email $GITHUB_ACTOR@users.noreply.github.com - git config --global user.name $GITHUB_ACTOR - echo "extracted branch is ${{ steps.extract_branch.outputs.branch }}" - git checkout -b ${{ steps.extract_branch.outputs.branch }} - git status - git add . - - name: Are there any updates? - shell: bash - run: echo "##[set-output name=status]$(git status -s)" - id: is_dirty - - name: Commit files - if: steps.is_dirty.outputs.status - run: | - echo ${{ steps.is_dirty.outputs.status }} - git commit -m "🎨 Prettier" - git push --force --set-upstream "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" ${{ steps.extract_branch.outputs.branch }} - run: npm test diff --git a/.gitignore b/.gitignore index a802a86..a54b922 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ *.gem .bundle +.ruby-version .jekyll-cache .sass-cache _site diff --git a/.prettierignore b/.prettierignore index 41fbef8..5dc073f 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,8 +1,9 @@ package.json package-lock.json _site -assets/css/dark-mode-preview.scss -assets/css/just-the-docs.scss +assets/css/just-the-docs-default.scss +assets/css/just-the-docs-light.scss +assets/css/just-the-docs-dark.scss assets/js/vendor/lunr.min.js assets/js/search-data.json assets/js/just-the-docs.js diff --git a/.stylelintrc.json b/.stylelintrc.json index a14d920..329ca34 100644 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -1,7 +1,8 @@ { "ignoreFiles": [ - "assets/css/just-the-docs.scss", - "assets/css/dark-mode-preview.scss", + "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-primer", "stylelint-config-prettier"], diff --git a/404.html b/404.html index 56efce4..1e7a37e 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 %}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/README.md b/README.md index 1237707..90dfb6f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Gem version Build status + Gem version Build status



diff --git a/_config.yml b/_config.yml index 7e71f3e..bcde0a2 100644 --- a/_config.yml +++ b/_config.yml @@ -25,10 +25,31 @@ exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "pac #logo: "/assets/images/just-the-docs.png" # Enable or disable the site search +# Supports true (default) or false search_enabled: true - -# Set the search token separator for hyphenated-word search: -search_tokenizer_separator: /[\s/]+/ +search: + # Split pages into sections that can be searched individually + # Supports 1 - 6, default: 2 + heading_level: 2 + # Maximum amount of previews per search result + # Default: 3 + previews: 3 + # Maximum amount of words to display before a matched word in the preview + # Default: 5 + preview_words_before: 5 + # Maximum amount of words to display after a matched word in the preview + # Default: 10 + preview_words_after: 10 + # Set the search token separator + # Default: /[\s\-/]+/ + # Example: enable support for hyphenated search words + tokenizer_separator: /[\s/]+/ + # Display the relative url in search results + # Supports true (default) or false + rel_url: true + # Enable or disable the search button that appears in the bottom right corner of every page + # Supports true or false (default) + button: false # Enable or disable heading anchors heading_anchors: true @@ -38,15 +59,42 @@ aux_links: "Just the Docs on GitHub": - "//github.com/pmarsceill/just-the-docs" -# Footer content appears at the bottom of every page's main content -footer_content: "Copyright © 2017-2019 Patrick Marsceill. Distributed by an MIT license." +# Makes Aux links open in a new tab. Default is false +aux_links_new_tab: false -# Color scheme currently only supports "dark" or nil (default) +# Sort order for navigation links +nav_sort: case_insensitive # default, equivalent to nil +# nav_sort: case_sensitive # Capital letters sorted before lowercase + +# Footer content +# appears at the bottom of every page's main content + +# Back to top link +back_to_top: true +back_to_top_text: "Back to top" + +footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license." + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + + + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub" +gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo +gh_edit_branch: "master" # the branch that your docs is served from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately + +# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define color_scheme: nil # Google Analytics Tracking (optional) # e.g, UA-1234567-89 ga_tracking: UA-2709176-10 +ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default) plugins: - jekyll-seo-tag diff --git a/_includes/css/custom.scss.liquid b/_includes/css/custom.scss.liquid new file mode 100644 index 0000000..2ad1576 --- /dev/null +++ b/_includes/css/custom.scss.liquid @@ -0,0 +1 @@ +@import "./custom/custom"; diff --git a/_includes/css/just-the-docs.scss.liquid b/_includes/css/just-the-docs.scss.liquid new file mode 100644 index 0000000..495cd6d --- /dev/null +++ b/_includes/css/just-the-docs.scss.liquid @@ -0,0 +1,7 @@ +{% if site.logo %} +$logo: "{{ site.logo | absolute_url }}"; +{% endif %} +@import "./support/support"; +@import "./color_schemes/{{ include.color_scheme }}"; +@import "./modules"; +{% include css/custom.scss.liquid %} diff --git a/_includes/head.html b/_includes/head.html index eae6a5e..4f22497 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -2,17 +2,17 @@ - {% if site.plugins.jekyll-seo == nil %} + {% unless site.plugins contains "jekyll-seo-tag" %} {{ page.title }} - {{ site.title }} {% if page.description %} {% endif %} - {% endif %} + {% endunless %} - + {% if site.ga_tracking != nil %} @@ -21,7 +21,7 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); - gtag('config', "{{ site.ga_tracking }}"); + gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %}); {% endif %} diff --git a/_includes/nav.html b/_includes/nav.html index eb96e28..f2ec7e5 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -1,44 +1,55 @@ -

+ diff --git a/_includes/vendor/anchor_headings.html b/_includes/vendor/anchor_headings.html index 25397df..985f448 100755 --- a/_includes/vendor/anchor_headings.html +++ b/_includes/vendor/anchor_headings.html @@ -64,7 +64,7 @@ {% capture anchor %}{% endcapture %} {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %} - {% capture anchor %}href="#{{ html_id}}"{% endcapture %} + {% capture anchor %}href="#{{ html_id}}" aria-labelledby="{{ html_id}}"{% endcapture %} {% if include.anchorClass %} {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %} @@ -97,4 +97,4 @@ {% endcapture %} {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %} {% endfor %} -{% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }} \ No newline at end of file +{% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }} diff --git a/_layouts/default.html b/_layouts/default.html index b1d3c72..1d41a71 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -4,99 +4,166 @@ layout: table_wrappers - + {% include head.html %} - + Link - + + + + + + Search + + + + + + Menu + + + + + + Expand + + + + + + Document + + + -
-
-
- {% include title.html %} - -
- -
- {% include nav.html %} -
-
-

This site uses Just the Docs, a documentation theme for Jekyll.

-
-
-
-
-
- {% if site.search_enabled != false %} -
-
- - Search -
-
-
- {% endif %} - {% if site.aux_links != nil %} - - {% endif %} -
-
- {% unless page.url == "/" %} - {% if page.parent %} - - {% endif %} - {% endunless %} -
- {% if site.heading_anchors != false %} - {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" %} - {% else %} - {{ content }} - {% endif %} - - {% if page.has_children == true and page.has_toc != false %} -
-

Table of contents

- {% assign children_list = site.pages | sort:"nav_order" %} -
    - {% for child in children_list %} - {% if child.parent == page.title and child.title != page.title %} -
  • - {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} -
    • - {% endif %} - {% endfor %} -
- {% endif %} - - {% if site.footer_content != nil %} -
-
-

{{ site.footer_content }}

-
- {% endif %} - -
-
+
+
+ {% include title.html %} + + +
+ +
+ This site uses Just the Docs, a documentation theme for Jekyll. +
+
+
+ {% if site.search_enabled != false %} +
+
+ + +
+
+
+ {% endif %} + {% if site.aux_links %} + + {% endif %} +
+
+ {% unless page.url == "/" %} + {% if page.parent %} + + {% endif %} + {% endunless %} +
+ {% if site.heading_anchors != false %} + {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" %} + {% else %} + {{ content }} + {% endif %} + {% if page.has_children == true and page.has_toc != false %} +
+

Table of contents

+
    + {%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%} + {% for child in children_list %} +
  • + {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} +
    • + {% endfor %} +
+ {% endif %} + + {% if site.footer_content != nil or site.last_edit_timestamp or site.gh_edit_link %} +
+
+ {% if site.back_to_top %} +

{{ site.back_to_top_text }}

+ {% endif %} + {% if site.footer_content != nil %} +

{{ site.footer_content }}

+ {% endif %} + + {% if site.last_edit_timestamp or site.gh_edit_link %} +
+ {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %} +

+ Page last modified: {{ page.last_modified_date | date: site.last_edit_time_format }}. +

+ {% endif %} + {% if + site.gh_edit_link and + site.gh_edit_link_text and + site.gh_edit_repository and + site.gh_edit_branch and + site.gh_edit_view_mode + %} +

+ {{ site.gh_edit_link_text }} +

+ {% endif %} +
+ {% endif %} +
+ {% endif %} + +
+
+ + {% if site.search_enabled != false %} + {% if site.search.button %} + + + + {% endif %} + +
+ {% endif %} +
diff --git a/_layouts/table_wrappers.html b/_layouts/table_wrappers.html index cc6187a..3f8f226 100644 --- a/_layouts/table_wrappers.html +++ b/_layouts/table_wrappers.html @@ -4,4 +4,4 @@ layout: vendor/compress {% assign content_ = content | replace: '', '
' %} -{{ content_ }} \ No newline at end of file +{{ content_ }} diff --git a/_sass/base.scss b/_sass/base.scss index 839fa0d..c3b6698 100644 --- a/_sass/base.scss +++ b/_sass/base.scss @@ -14,6 +14,7 @@ html { @include fs-4; + scroll-behavior: smooth; } body { @@ -24,25 +25,18 @@ body { background-color: $body-background-color; } -p, -h1, -h2, -h3, -h4, -h5, -h6, ol, ul, +dl, pre, address, blockquote, -dl, +table, div, -fieldset, -form, hr, -noscript, -table { +form, +fieldset, +noscript .table-wrapper { margin-top: 0; } @@ -52,14 +46,15 @@ h3, h4, h5, h6 { - margin-top: 1.2em; - margin-bottom: 0.8em; + margin-top: 0; + margin-bottom: 1em; font-weight: 500; line-height: $body-heading-line-height; color: $body-heading-color; } p { + margin-top: 1em; margin-bottom: 1em; } @@ -86,7 +81,7 @@ a:not([class]) { code { font-family: $mono-font-family; - font-size: 12px; + font-size: 0.75em; line-height: $body-line-height; } diff --git a/_sass/code.scss b/_sass/code.scss index 97ce8f4..affc8aa 100644 --- a/_sass/code.scss +++ b/_sass/code.scss @@ -14,9 +14,11 @@ code { pre.highlight, figure.highlight { padding: $sp-3; + margin-top: 0; margin-bottom: 0; - -webkit-overflow-scrolling: touch; background-color: $code-background-color; + border-radius: $border-radius; + -webkit-overflow-scrolling: touch; code { padding: 0; @@ -26,8 +28,6 @@ figure.highlight { .highlighter-rouge { margin-bottom: $sp-3; - overflow: hidden; - border-radius: $border-radius; } .highlight .c { diff --git a/_sass/color_schemes/dark.scss b/_sass/color_schemes/dark.scss index 9a0b9ea..a25f449 100644 --- a/_sass/color_schemes/dark.scss +++ b/_sass/color_schemes/dark.scss @@ -14,3 +14,4 @@ $base-button-color: $grey-dk-250; $code-background-color: $grey-dk-250; $search-background-color: $grey-dk-250; $table-background-color: $grey-dk-250; +$feedback-color: darken($sidebar-color, 3%); diff --git a/_sass/color_schemes/light.scss b/_sass/color_schemes/light.scss new file mode 100644 index 0000000..e69de29 diff --git a/_sass/content.scss b/_sass/content.scss index 2940286..113e733 100644 --- a/_sass/content.scss +++ b/_sass/content.scss @@ -5,9 +5,19 @@ // // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type -.page-content { +.main-content { line-height: $content-line-height; + ol, + ul, + dl, + pre, + address, + blockquote, + .table-wrapper { + margin-top: 0.5em; + } + a { overflow: hidden; text-overflow: ellipsis; @@ -19,6 +29,12 @@ padding-left: 1.5em; } + li { + .highlight { + margin-top: $sp-1; + } + } + ol { list-style-type: none; counter-reset: step-counter; @@ -132,7 +148,7 @@ display: inline-block; width: 100%; height: 100%; - fill: $link-color; + color: $link-color; visibility: hidden; } } @@ -149,6 +165,10 @@ } } + summary { + cursor: pointer; + } + h1, h2, h3, @@ -156,5 +176,22 @@ h5, h6 { position: relative; + margin-top: 1.5em; + margin-bottom: 0.25em; + + &:first-child { + margin-top: $sp-2; + } + + + table, + + .table-wrapper, + + .code-example, + + .highlighter-rouge { + margin-top: 1em; + } + + + p { + margin-top: 0; + } } } diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss index 9ac503b..e69de29 100644 --- a/_sass/custom/custom.scss +++ b/_sass/custom/custom.scss @@ -1,129 +0,0 @@ -//// -//// Typography -//// - -//$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif; -//$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace; -//$root-font-size: 16px; // Base font-size for rems -//$body-line-height: 1.4; -//$content-line-height: 1.5; -//$body-heading-line-height: 1.15; - -//// -//// Colors -//// - -//$white: #fff; - -//$grey-dk-000: #959396; -//$grey-dk-100: #5c5962; -//$grey-dk-200: #44434d; -//$grey-dk-250: #302d36; -//$grey-dk-300: #27262b; - -//$grey-lt-000: #f5f6fa; -//$grey-lt-100: #eeebee; -//$grey-lt-200: #ecebed; -//$grey-lt-300: #e6e1e8; - -//$purple-000: #7253ed; -//$purple-100: #5e41d0; -//$purple-200: #4e26af; -//$purple-300: #381885; - -//$blue-000: #2c84fa; -//$blue-100: #2869e6; -//$blue-200: #264caf; -//$blue-300: #183385; - -//$green-000: #41d693; -//$green-100: #11b584; -//$green-200: #009c7b; -//$green-300: #026e57; - -//$yellow-000: #ffeb82; -//$yellow-100: #fadf50; -//$yellow-200: #f7d12e; -//$yellow-300: #e7af06; - -//$red-000: #f77e7e; -//$red-100: #f96e65; -//$red-200: #e94c4c; -//$red-300: #dd2e2e; - -//$body-background-color: $white; -//$sidebar-color: $grey-lt-000; -//$search-background-color: $white; -//$table-background-color: $white; -//$code-background-color: $grey-lt-000; - -//$body-text-color: $grey-dk-100; -//$body-heading-color: $grey-dk-300; -//$search-result-preview-color: $grey-dk-000; -//$nav-child-link-color: $grey-dk-100; -//$link-color: $purple-000; -//$btn-primary-color: $purple-100; -//$base-button-color: #f7f7f7; - -//// -//// Spacing -//// - -//$spacing-unit: 1rem; // 1rem == 16px - -//$spacers: ( -//sp-0: 0, -//sp-1: $spacing-unit * 0.25, -//sp-2: $spacing-unit * 0.5, -//sp-3: $spacing-unit * 0.75, -//sp-4: $spacing-unit, -//sp-5: $spacing-unit * 1.5, -//sp-6: $spacing-unit * 2, -//sp-7: $spacing-unit * 2.5, -//sp-8: $spacing-unit * 3, -//sp-9: $spacing-unit * 3.5, -//sp-10: $spacing-unit * 4 -//); - -//$sp-1: map-get($spacers, sp-1); // 0.25 rem == 4px -//$sp-2: map-get($spacers, sp-2); // 0.5 rem == 8px -//$sp-3: map-get($spacers, sp-3); // 0.75 rem == 12px -//$sp-4: map-get($spacers, sp-4); // 1 rem == 16px -//$sp-5: map-get($spacers, sp-5); // 1.5 rem == 24px -//$sp-6: map-get($spacers, sp-6); // 2 rem == 32px -//$sp-7: map-get($spacers, sp-7); // 2.5 rem == 40px -//$sp-8: map-get($spacers, sp-8); // 3 rem == 48px -//$sp-9: map-get($spacers, sp-9); // 4 rem == 48px -//$sp-10: map-get($spacers, sp-10); // 4.5 rem == 48px - -//// -//// Borders -//// - -//$border: 1px solid; -//$border-radius: 4px; -//$border-color: $grey-lt-100; - -//// -//// Grid system -//// - -//$gutter-spacing: $sp-6; -//$gutter-spacing-sm: $sp-4; -//$nav-width: 264px; -//$nav-width-md: 248px; -//$content-width: 800px; -//$header-height: 60px; -//$search-results-width: 500px; - -//// -//// Media queries in pixels -//// - -//$media-queries: ( -//xs: 320px, -//sm: 500px, -//md: $content-width, -//lg: $content-width + $nav-width, -//xl: 1400px -//); diff --git a/_sass/labels.scss b/_sass/labels.scss index 23cc510..e08ae80 100644 --- a/_sass/labels.scss +++ b/_sass/labels.scss @@ -6,16 +6,17 @@ .label-blue { display: inline-block; padding-top: 0.16em; - padding-right: 0.42em; + padding-right: 0.56em; padding-bottom: 0.16em; - padding-left: 0.42em; - margin-right: $sp-1; - margin-left: $sp-1; + padding-left: 0.56em; + margin-right: $sp-2; + margin-left: $sp-2; color: $white; text-transform: uppercase; vertical-align: middle; background-color: $blue-100; @include fs-2; + border-radius: 12px; } .label-green { diff --git a/_sass/layout.scss b/_sass/layout.scss index 79169e4..004cbe7 100644 --- a/_sass/layout.scss +++ b/_sass/layout.scss @@ -2,28 +2,15 @@ // The basic two column layout // -.page-wrap { - @include mq(md) { - position: absolute; - top: 0; - left: 0; - display: flex; - width: 100%; - height: 100%; - overflow-x: hidden; - overflow-y: hidden; - } -} - .side-bar { - z-index: 100; + z-index: 0; display: flex; flex-wrap: wrap; background-color: $sidebar-color; @include mq(md) { flex-wrap: nowrap; - position: absolute; + position: fixed; width: $nav-width-md; height: 100%; flex-direction: column; @@ -37,20 +24,7 @@ } } -.main-content-wrap { - @include mq(md) { - position: absolute; - top: 0; - left: 0; - width: 100%; - height: 100%; - -webkit-overflow-scrolling: touch; - overflow-x: hidden; - overflow-y: scroll; - } -} - -.main-content { +.main { @include mq(md) { position: relative; max-width: $content-width; @@ -64,11 +38,7 @@ } } -.js-main-content:focus { - outline: none; -} - -.page { +.main-content-wrap { @include container; padding-top: $gutter-spacing-sm; padding-bottom: $gutter-spacing-sm; @@ -79,16 +49,14 @@ } } -.page-header { - @include container; +.main-header { + z-index: 0; display: none; - padding-top: $gutter-spacing-sm; - padding-bottom: $gutter-spacing-sm; background-color: $sidebar-color; @include mq(md) { display: flex; - justify-content: flex-end; + justify-content: space-between; height: $header-height; background-color: $body-background-color; border-bottom: $border $border-color; @@ -103,7 +71,7 @@ } } -.navigation, +.site-nav, .site-header, .site-footer { width: 100%; @@ -113,10 +81,15 @@ } } -.navigation { - @include container; +.site-nav { + display: none; + + &.nav-open { + display: block; + } @include mq(md) { + display: block; padding-top: $sp-8; padding-bottom: $gutter-spacing-sm; overflow-y: auto; @@ -130,7 +103,6 @@ align-items: center; @include mq(md) { - z-index: 101; height: $header-height; max-height: $header-height; border-bottom: $border $border-color; @@ -165,27 +137,42 @@ } } -.menu-button { - appearance: none; +.site-button { display: flex; height: 100%; padding: $gutter-spacing-sm; align-items: center; - color: $link-color; - text-transform: uppercase; - background: transparent; - border: 0; +} - @include mq(md) { +@include mq(md) { + .site-header .site-button { display: none; } } +.site-title:hover { + background-image: linear-gradient( + -90deg, + rgba($feedback-color, 1) 0%, + rgba($feedback-color, 0.8) 80%, + rgba($feedback-color, 0) 100% + ); +} + +.site-button:hover { + background-image: linear-gradient( + -90deg, + rgba($feedback-color, 1) 0%, + rgba($feedback-color, 0.8) 100% + ); +} + // stylelint-disable selector-max-type body { position: relative; padding-bottom: $sp-10; + overflow-y: scroll; @include mq(md) { position: static; @@ -202,9 +189,17 @@ body { left: 0; padding-top: $sp-4; padding-bottom: $sp-4; + color: $grey-dk-000; + @include fs-2; @include mq(md) { position: static; justify-self: end; } } + +.icon { + width: $sp-5; + height: $sp-5; + color: $link-color; +} diff --git a/_sass/modules.scss b/_sass/modules.scss new file mode 100644 index 0000000..d82591b --- /dev/null +++ b/_sass/modules.scss @@ -0,0 +1,20 @@ +// +// Import external dependencies +// +@import "./vendor/normalize.scss/normalize.scss"; + +// +// Modules +// +@import "./base"; +@import "./layout"; +@import "./content"; +@import "./navigation"; +@import "./typography"; +@import "./labels"; +@import "./buttons"; +@import "./search"; +@import "./tables"; +@import "./code"; +@import "./utilities/utilities"; +@import "./print"; diff --git a/_sass/navigation.scss b/_sass/navigation.scss index c774904..0417b4c 100644 --- a/_sass/navigation.scss +++ b/_sass/navigation.scss @@ -1,89 +1,165 @@ // // Main nav, breadcrumb, etc... // -.navigation-list { +// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity + +.nav-list { padding: 0; margin-top: 0; margin-bottom: 0; list-style: none; -} -.navigation-list-child-list { - padding-left: $sp-3; - list-style: none; - - .navigation-list-link { - color: $nav-child-link-color; - } - - .navigation-list-item { + .nav-list-item { + @include fs-4; position: relative; + margin: 0; - &::before { + @include mq(md) { + @include fs-3; + } + + .nav-list-link { + display: block; + min-height: $nav-list-item-height-sm; + padding-top: $sp-1; + padding-bottom: $sp-1; + line-height: #{$nav-list-item-height-sm - 2 * $sp-1}; + @if $nav-list-expander-right { + padding-right: $nav-list-item-height-sm; + padding-left: $gutter-spacing-sm; + } @else { + padding-right: $gutter-spacing-sm; + padding-left: $nav-list-item-height-sm; + } + + @include mq(md) { + min-height: $nav-list-item-height; + line-height: #{$nav-list-item-height - 2 * $sp-1}; + @if $nav-list-expander-right { + padding-right: $nav-list-item-height; + padding-left: $gutter-spacing; + } @else { + padding-right: $gutter-spacing; + padding-left: $nav-list-item-height; + } + } + + &.active { + font-weight: 600; + text-decoration: none; + } + + &:hover, + &.active { + background-image: linear-gradient( + -90deg, + rgba($feedback-color, 1) 0%, + rgba($feedback-color, 0.8) 80%, + rgba($feedback-color, 0) 100% + ); + } + } + + .nav-list-expander { position: absolute; - margin-top: 0.3em; - margin-left: -0.8em; - color: rgba($body-text-color, 0.3); - content: "- "; + @if $nav-list-expander-right { + right: 0; + } + width: $nav-list-item-height-sm; + height: $nav-list-item-height-sm; + padding-top: #{$nav-list-item-height-sm / 4}; + padding-right: #{$nav-list-item-height-sm / 4}; + padding-bottom: #{$nav-list-item-height-sm / 4}; + padding-left: #{$nav-list-item-height-sm / 4}; + color: $link-color; + + @include mq(md) { + width: $nav-list-item-height; + height: $nav-list-item-height; + padding-top: #{$nav-list-item-height / 4}; + padding-right: #{$nav-list-item-height / 4}; + padding-bottom: #{$nav-list-item-height / 4}; + padding-left: #{$nav-list-item-height / 4}; + } + + &:hover { + background-image: linear-gradient( + -90deg, + rgba($feedback-color, 1) 0%, + rgba($feedback-color, 0.8) 100% + ); + } + + @if $nav-list-expander-right { + svg { + transform: rotate(90deg); + } + } + } + + > .nav-list { + display: none; + padding-left: $sp-3; + list-style: none; + + .nav-list-item { + position: relative; + + .nav-list-link { + color: $nav-child-link-color; + } + + .nav-list-expander { + color: $nav-child-link-color; + } + } } &.active { - &::before { - color: $body-text-color; + > .nav-list-expander svg { + @if $nav-list-expander-right { + transform: rotate(-90deg); + } @else { + transform: rotate(90deg); + } + } + + > .nav-list { + display: block; } } } } -.navigation-list-item { - @include fs-4; - margin: 0; - - @include mq(md) { - @include fs-3; - } - - .navigation-list-child-list { - display: none; - } - - &.active { - .navigation-list-child-list { - display: block; - } - } -} - -.navigation-list-link { - display: block; - padding-top: $sp-1; - padding-bottom: $sp-1; - - &.active { - font-weight: 600; - color: $body-heading-color; - text-decoration: none; - } -} - -// Small screen nav - -.main-nav { - display: none; - - &.nav-open { - display: block; - } - @include mq(md) { - display: block; - } -} +// Aux nav .aux-nav { - align-self: center; + height: 100%; + overflow-x: auto; + @include fs-2; + + .aux-nav-list { + display: flex; + height: 100%; + padding: 0; + margin: 0; + list-style: none; + } + + .aux-nav-list-item { + display: inline-block; + height: 100%; + padding: 0; + margin: 0; + } + + @include mq(md) { + padding-right: $gutter-spacing-sm; + } } // Breadcrumb nav + .breadcrumb-nav { @include mq(md) { margin-top: -$sp-4; diff --git a/_sass/overrides.scss b/_sass/overrides.scss deleted file mode 100644 index 21e9527..0000000 --- a/_sass/overrides.scss +++ /dev/null @@ -1,3 +0,0 @@ -// -// Custom overrides from a user. -// diff --git a/_sass/print.scss b/_sass/print.scss new file mode 100644 index 0000000..6e6de37 --- /dev/null +++ b/_sass/print.scss @@ -0,0 +1,40 @@ +// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type, primer/no-override, + +@media print { + .site-footer, + .site-button, + #edit-this-page, + #back-to-top, + .site-nav, + .main-header { + display: none !important; + } + + .side-bar { + width: 100%; + height: auto; + border-right: 0 !important; + } + + .site-header { + border-bottom: 1px solid $border-color; + } + + .site-title { + font-size: $root-font-size !important; + font-weight: 700 !important; + } + + .text-small { + font-size: 8pt !important; + } + + pre.highlight { + border: 1px solid $border-color; + } + + .main { + max-width: none; + margin-left: 0; + } +} diff --git a/_sass/search.scss b/_sass/search.scss index bef2df7..eb94cb7 100644 --- a/_sass/search.scss +++ b/_sass/search.scss @@ -4,91 +4,115 @@ .search { position: relative; - z-index: 99; + z-index: 2; flex-grow: 1; - height: 100%; - margin-bottom: $sp-3; + height: $sp-10; + padding: $sp-2; + transition: padding linear #{$transition-duration / 2}; @include mq(md) { - margin-bottom: 0; + position: relative !important; + width: auto !important; + height: 100% !important; + padding: 0; + transition: none; } } .search-input-wrap { - display: flex; - height: 100%; - padding: $sp-2; - background-color: $search-background-color; + position: relative; + z-index: 1; + height: $sp-8; + overflow: hidden; border-radius: $border-radius; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + transition: height linear #{$transition-duration / 2}; @include mq(md) { - padding-top: 0; - padding-right: 0; - padding-bottom: 0; - padding-left: 0; - background-color: $body-background-color; + position: absolute; + width: 100%; + max-width: $search-results-width; + height: 100% !important; border-radius: 0; box-shadow: none; + transition: width ease $transition-duration; } } .search-input { - align-self: center; + position: absolute; width: 100%; - padding-top: $sp-1; - padding-bottom: $sp-1; + height: 100%; + padding-top: $sp-2; + padding-right: $gutter-spacing-sm; + padding-bottom: $sp-2; + padding-left: #{$gutter-spacing-sm + $sp-5}; + font-size: 16px; background-color: $search-background-color; border-top: 0; border-right: 0; border-bottom: 0; border-left: 0; - order: 2; - @include fs-4; + border-radius: 0; + + @include mq(md) { + padding-top: $gutter-spacing-sm; + padding-bottom: $gutter-spacing-sm; + padding-left: #{$gutter-spacing + $sp-5}; + font-size: 14px; + background-color: $body-background-color; + transition: padding-left linear #{$transition-duration / 2}; + } &:focus { outline: 0; - box-shadow: none; - + .search-icon { - fill: $link-color; + + .search-label .search-icon { + color: $link-color; } } +} + +.search-label { + position: absolute; + display: flex; + height: 100%; + padding-left: $gutter-spacing-sm; @include mq(md) { - background-color: $body-background-color; - @include fs-3; + padding-left: $gutter-spacing; + transition: padding-left linear #{$transition-duration / 2}; + } + + .search-icon { + width: #{$sp-4 * 1.2}; + height: #{$sp-4 * 1.2}; + align-self: center; + color: $grey-dk-000; } } -.search-icon { - align-self: center; - margin-right: $sp-2; - fill: $grey-dk-000; - order: 1; -} - -.search-results-wrap { +.search-results { position: absolute; - z-index: 100; + left: 0; display: none; width: 100%; - background: $search-background-color; - border-radius: $border-radius; + max-height: calc(100% - #{$sp-10}); + overflow-y: auto; + background-color: $search-background-color; + border-bottom-right-radius: $border-radius; + border-bottom-left-radius: $border-radius; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - &.active { - display: block; - } - @include mq(md) { + top: 100%; width: $search-results-width; + max-height: calc(100vh - 200%) !important; } } .search-results-list { padding-left: 0; - margin-top: $sp-1; margin-bottom: $sp-1; list-style: none; @include fs-4; @@ -112,31 +136,58 @@ &:hover, &.active { - background-color: $sidebar-color; - } - - @include mq(md) { - padding-right: $sp-4; - padding-left: $sp-4; + background-color: $feedback-color; } } .search-result-title { display: block; padding-top: $sp-2; - padding-right: $sp-4; padding-bottom: $sp-2; @include mq(sm) { display: inline-block; width: 40%; - word-wrap: break-word; + padding-right: $sp-2; vertical-align: top; } } +.search-result-doc { + display: flex; + align-items: center; + word-wrap: break-word; + + &.search-result-doc-parent { + opacity: 0.5; + @include fs-3; + + @include mq(md) { + @include fs-2; + } + } + + .search-result-icon { + width: $sp-4; + height: $sp-4; + margin-right: $sp-2; + color: $link-color; + flex-shrink: 0; + } + + .search-result-doc-title { + overflow: auto; + } +} + +.search-result-section { + margin-left: #{$sp-4 + $sp-2}; + word-wrap: break-word; +} + .search-result-rel-url { display: block; + margin-left: #{$sp-4 + $sp-2}; overflow: hidden; color: $search-result-preview-color; text-overflow: ellipsis; @@ -144,12 +195,14 @@ @include fs-1; } -.search-result-preview { +.search-result-previews { display: block; padding-top: $sp-2; padding-bottom: $sp-2; padding-left: $sp-4; + margin-left: $sp-2; color: $search-result-preview-color; + word-wrap: break-word; border-left: $border; border-left-color: $border-color; @include fs-2; @@ -157,11 +210,114 @@ @include mq(sm) { display: inline-block; width: 60%; + padding-left: $sp-2; + margin-left: 0; vertical-align: top; } } +.search-result-preview + .search-result-preview { + margin-top: $sp-1; +} + .search-result-highlight { font-weight: bold; - color: $link-color; +} + +.search-no-result { + padding-top: $sp-2; + padding-right: $sp-3; + padding-bottom: $sp-2; + padding-left: $sp-3; + @include fs-3; +} + +.search-button { + position: fixed; + right: $sp-4; + bottom: $sp-4; + display: flex; + width: $sp-9; + height: $sp-9; + background-color: $search-background-color; + border: 1px solid rgba($link-color, 0.3); + border-radius: #{$sp-9 / 2}; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + align-items: center; + justify-content: center; +} + +.search-overlay { + position: fixed; + top: 0; + left: 0; + z-index: 1; + width: 0; + height: 0; + background-color: rgba(0, 0, 0, 0.3); + opacity: 0; + transition: opacity ease $transition-duration, width 0s $transition-duration, + height 0s $transition-duration; +} + +.search-active { + .search { + position: fixed; + top: 0; + left: 0; + width: 100%; + height: 100%; + padding: 0; + } + + .search-input-wrap { + height: $sp-10; + border-radius: 0; + + @include mq(md) { + width: $search-results-width; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); + } + } + + .search-input { + background-color: $search-background-color; + + @include mq(md) { + padding-left: #{$sp-4 * 1.25 + $sp-5}; + } + } + + .search-label { + @include mq(md) { + padding-left: #{$sp-4 * 1.25}; + } + } + + .search-results { + display: block; + } + + .search-overlay { + width: 100%; + height: 100%; + opacity: 1; + transition: opacity ease $transition-duration, width 0s, height 0s; + } + + @include mq(md) { + .main { + position: fixed; + right: 0; + left: 0; + } + } + + .main-header { + padding-top: $sp-10; + + @include mq(md) { + padding-top: 0; + } + } } diff --git a/_sass/support/_variables.scss b/_sass/support/_variables.scss index 76d8b5d..b97b14e 100644 --- a/_sass/support/_variables.scss +++ b/_sass/support/_variables.scss @@ -7,8 +7,8 @@ $body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", $mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default; $root-font-size: 16px !default; // Base font-size for rems $body-line-height: 1.4 !default; -$content-line-height: 1.5 !default; -$body-heading-line-height: 1.15 !default !default; +$content-line-height: 1.6 !default; +$body-heading-line-height: 1.25 !default; // // Colors @@ -57,6 +57,7 @@ $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; @@ -94,8 +95,8 @@ $sp-5: map-get($spacers, sp-5) !default; // 1.5 rem == 24px $sp-6: map-get($spacers, sp-6) !default; // 2 rem == 32px $sp-7: map-get($spacers, sp-7) !default; // 2.5 rem == 40px $sp-8: map-get($spacers, sp-8) !default; // 3 rem == 48px -$sp-9: map-get($spacers, sp-9) !default; // 4 rem == 48px -$sp-10: map-get($spacers, sp-10) !default; // 4.5 rem == 48px +$sp-9: map-get($spacers, sp-9) !default; // 3.5 rem == 56px +$sp-10: map-get($spacers, sp-10) !default; // 4 rem == 64px // // Borders @@ -113,9 +114,13 @@ $gutter-spacing: $sp-6 !default; $gutter-spacing-sm: $sp-4 !default; $nav-width: 264px !default; $nav-width-md: 248px !default; +$nav-list-item-height: $sp-6 !default; +$nav-list-item-height-sm: $sp-8 !default; +$nav-list-expander-right: true; $content-width: 800px !default; $header-height: 60px !default; -$search-results-width: 500px !default; +$search-results-width: $content-width - $nav-width !default; +$transition-duration: 400ms; // // Media queries in pixels diff --git a/_sass/support/mixins/_typography.scss b/_sass/support/mixins/_typography.scss index e6d85be..1718a93 100644 --- a/_sass/support/mixins/_typography.scss +++ b/_sass/support/mixins/_typography.scss @@ -25,7 +25,7 @@ } @mixin fs-4 { - font-size: 14px !important; + font-size: 15px !important; @include mq(sm) { font-size: 16px !important; @@ -45,11 +45,13 @@ @include mq(sm) { font-size: 24px !important; + line-height: $body-heading-line-height; } } @mixin fs-7 { font-size: 24px !important; + line-height: $body-heading-line-height; @include mq(sm) { font-size: 32px !important; @@ -58,6 +60,7 @@ @mixin fs-8 { font-size: 32px !important; + line-height: $body-heading-line-height; @include mq(sm) { font-size: 36px !important; @@ -66,6 +69,7 @@ @mixin fs-9 { font-size: 36px !important; + line-height: $body-heading-line-height; @include mq(sm) { font-size: 42px !important; @@ -74,6 +78,7 @@ @mixin fs-10 { font-size: 42px !important; + line-height: $body-heading-line-height; @include mq(sm) { font-size: 48px !important; diff --git a/_sass/typography.scss b/_sass/typography.scss index ccf1604..3749d43 100644 --- a/_sass/typography.scss +++ b/_sass/typography.scss @@ -22,7 +22,7 @@ h3, h4, .text-delta { @include fs-2; - font-weight: 300; + font-weight: 400; text-transform: uppercase; letter-spacing: 0.1em; } @@ -39,12 +39,6 @@ h6, color: $grey-dk-200; } -li { - .highlight { - margin-top: $sp-2; - } -} - .text-small { @include fs-2; } @@ -53,6 +47,14 @@ li { font-family: $mono-font-family !important; } +.text-left { + text-align: left !important; +} + .text-center { text-align: center !important; } + +.text-right { + text-align: right !important; +} diff --git a/_sass/utilities/_layout.scss b/_sass/utilities/_layout.scss index 3247ea3..37ebe42 100644 --- a/_sass/utilities/_layout.scss +++ b/_sass/utilities/_layout.scss @@ -47,6 +47,32 @@ } } +// Horizontal alignment + +.float-left { + float: left !important; +} + +.float-right { + float: right !important; +} + +.flex-justify-start { + justify-content: flex-start !important; +} + +.flex-justify-end { + justify-content: flex-end !important; +} + +.flex-justify-between { + justify-content: space-between !important; +} + +.flex-justify-around { + justify-content: space-around !important; +} + // Vertical alignment .v-align-baseline { diff --git a/_sass/utilities/_spacing.scss b/_sass/utilities/_spacing.scss index 917dd3c..162f801 100644 --- a/_sass/utilities/_spacing.scss +++ b/_sass/utilities/_spacing.scss @@ -7,6 +7,11 @@ // Margin spacer utilities +.mx-auto { + margin-right: auto !important; + margin-left: auto !important; +} + @for $i from 1 through length($spacers) { $size: #{map-get($spacers, sp-#{$i - 1})}; $scale: #{$i - 1}; @@ -42,11 +47,10 @@ margin-right: -#{$size} !important; margin-left: -#{$size} !important; } -} - -.mx-auto { - margin-right: auto !important; - margin-left: auto !important; + .mx-#{$scale}-auto { + margin-right: auto !important; + margin-left: auto !important; + } } @each $media-query in map-keys($media-queries) { diff --git a/assets/css/dark-mode-preview.scss b/assets/css/dark-mode-preview.scss deleted file mode 100644 index c524e81..0000000 --- a/assets/css/dark-mode-preview.scss +++ /dev/null @@ -1,45 +0,0 @@ ---- -# this ensures Jekyll reads the file to be transformed into CSS later -# only Main files contain this front matter, not partials. ---- - -{% if site.logo %} -$logo: "{{ site.logo | absolute_url }}"; -{% endif %} - -// -// Import external dependencies -// - -@import "./vendor/normalize.scss/normalize.scss"; - -// -// Import Just the Docs scss -// - -// Support -@import "./support/support"; - -// -// Import custom color scheme scss -// - -@import "./color_schemes/dark.scss"; - -// Modules -@import "./base"; -@import "./layout"; -@import "./content"; -@import "./navigation"; -@import "./typography"; -@import "./labels"; -@import "./buttons"; -@import "./search"; -@import "./tables"; -@import "./code"; -@import "./utilities/utilities"; - -// -// Import custom overrides -// -@import "./custom/custom"; diff --git a/assets/css/just-the-docs-dark.scss b/assets/css/just-the-docs-dark.scss new file mode 100644 index 0000000..ac92fb1 --- /dev/null +++ b/assets/css/just-the-docs-dark.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="dark" %} diff --git a/assets/css/just-the-docs-default.scss b/assets/css/just-the-docs-default.scss new file mode 100644 index 0000000..63fde26 --- /dev/null +++ b/assets/css/just-the-docs-default.scss @@ -0,0 +1,8 @@ +--- +--- +{% if site.color_scheme and site.color_scheme != "nil" %} + {% assign color_scheme = site.color_scheme %} +{% else %} + {% assign color_scheme = "light" %} +{% endif %} +{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %} diff --git a/assets/css/just-the-docs-light.scss b/assets/css/just-the-docs-light.scss new file mode 100644 index 0000000..ac69688 --- /dev/null +++ b/assets/css/just-the-docs-light.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="light" %} diff --git a/assets/css/just-the-docs.scss b/assets/css/just-the-docs.scss deleted file mode 100644 index 199ad89..0000000 --- a/assets/css/just-the-docs.scss +++ /dev/null @@ -1,49 +0,0 @@ ---- -# this ensures Jekyll reads the file to be transformed into CSS later -# only Main files contain this front matter, not partials. ---- - -{% if site.logo %} -$logo: "{{ site.logo | absolute_url }}"; -{% endif %} - -// -// Import external dependencies -// - -@import "./vendor/normalize.scss/normalize.scss"; - -// -// Import Just the Docs scss -// - -// Support -@import "./support/support"; - -// -// Import custom overrides -// - -@import "./custom/custom"; - -// -// Import custom color scheme scss -// - -{% if site.color_scheme == "dark" %} -@import "./color_schemes/dark.scss"; -{% endif %} - -// Modules -@import "./base"; -@import "./layout"; -@import "./content"; -@import "./navigation"; -@import "./typography"; -@import "./labels"; -@import "./buttons"; -@import "./search"; -@import "./tables"; -@import "./code"; -@import "./utilities/utilities"; -@import "./overrides"; diff --git a/assets/js/dark-mode-preview.js b/assets/js/dark-mode-preview.js deleted file mode 100644 index bb3169f..0000000 --- a/assets/js/dark-mode-preview.js +++ /dev/null @@ -1,25 +0,0 @@ -document.addEventListener("DOMContentLoaded", function () { - const toggleDarkMode = document.querySelector(".js-toggle-dark-mode") - const cssFile = document.querySelector('[rel="stylesheet"]') - const originalCssRef = cssFile.getAttribute("href") - const darkModeCssRef = originalCssRef.replace( - "just-the-docs.css", - "dark-mode-preview.css" - ) - const buttonCopy = ["Return to the light side", "Preview dark color scheme"] - const updateButtonText = function (toggleDarkMode) { - toggleDarkMode.textContent === buttonCopy[0] - ? (toggleDarkMode.textContent = buttonCopy[1]) - : (toggleDarkMode.textContent = buttonCopy[0]) - } - - jtd.addEvent(toggleDarkMode, "click", function () { - if (cssFile.getAttribute("href") === originalCssRef) { - cssFile.setAttribute("href", darkModeCssRef) - updateButtonText(toggleDarkMode) - } else { - cssFile.setAttribute("href", originalCssRef) - updateButtonText(toggleDarkMode) - } - }) -}) diff --git a/assets/js/just-the-docs.js b/assets/js/just-the-docs.js index 2f6cea0..c287ec0 100644 --- a/assets/js/just-the-docs.js +++ b/assets/js/just-the-docs.js @@ -24,24 +24,47 @@ jtd.onReady = function(ready) { // Show/hide mobile menu function initNav() { - const mainNav = document.querySelector('.js-main-nav'); - const pageHeader = document.querySelector('.js-page-header'); - const navTrigger = document.querySelector('.js-main-nav-trigger'); + jtd.addEvent(document, 'click', function(e){ + var target = e.target; + while (target && !(target.classList && target.classList.contains('nav-list-expander'))) { + target = target.parentNode; + } + if (target) { + e.preventDefault(); + target.parentNode.classList.toggle('active'); + } + }); - jtd.addEvent(navTrigger, 'click', function(e){ + const siteNav = document.getElementById('site-nav'); + const mainHeader = document.getElementById('main-header'); + const menuButton = document.getElementById('menu-button'); + + jtd.addEvent(menuButton, 'click', function(e){ e.preventDefault(); - var text = navTrigger.innerText; - var textToggle = navTrigger.getAttribute('data-text-toggle'); - mainNav.classList.toggle('nav-open'); - pageHeader.classList.toggle('nav-open'); - navTrigger.classList.toggle('nav-open'); - navTrigger.innerText = textToggle; - navTrigger.setAttribute('data-text-toggle', text); - textToggle = text; - }) + if (menuButton.classList.toggle('nav-open')) { + siteNav.classList.add('nav-open'); + mainHeader.classList.add('nav-open'); + } else { + siteNav.classList.remove('nav-open'); + mainHeader.classList.remove('nav-open'); + } + }); + + {%- if site.search_enabled != false and site.search.button %} + const searchInput = document.getElementById('search-input'); + const searchButton = document.getElementById('search-button'); + + jtd.addEvent(searchButton, 'click', function(e){ + e.preventDefault(); + + mainHeader.classList.add('nav-open'); + searchInput.focus(); + }); + {%- endif %} } +{%- if site.search_enabled != false %} // Site search function initSearch() { @@ -50,248 +73,397 @@ function initSearch() { request.onload = function(){ if (request.status >= 200 && request.status < 400) { - // Success! - var data = JSON.parse(request.responseText); + var docs = JSON.parse(request.responseText); - {% if site.search_tokenizer_separator != nil %} - lunr.tokenizer.separator = {{ site.search_tokenizer_separator }} - {% else %} - lunr.tokenizer.separator = /[\s\-/]+/ - {% endif %} - - var index = lunr(function () { + lunr.tokenizer.separator = {{ site.search.tokenizer_separator | default: site.search_tokenizer_separator | default: "/[\s\-/]+/" }} + + var index = lunr(function(){ this.ref('id'); this.field('title', { boost: 200 }); this.field('content', { boost: 2 }); - this.field('url'); + {%- if site.search.rel_url != false %} + this.field('relUrl'); + {%- endif %} this.metadataWhitelist = ['position'] - for (var i in data) { + for (var i in docs) { this.add({ id: i, - title: data[i].title, - content: data[i].content, - url: data[i].url + title: docs[i].title, + content: docs[i].content, + {%- if site.search.rel_url != false %} + relUrl: docs[i].relUrl + {%- endif %} }); } }); - searchResults(index, data); + searchLoaded(index, docs); } else { - // We reached our target server, but it returned an error console.log('Error loading ajax request. Request status:' + request.status); } }; request.onerror = function(){ - // There was a connection error of some sort console.log('There was a connection error'); }; request.send(); +} - function searchResults(index, data) { - var index = index; - var docs = data; - var searchInput = document.querySelector('.js-search-input'); - var searchResults = document.querySelector('.js-search-results'); +function searchLoaded(index, docs) { + var index = index; + var docs = docs; + var searchInput = document.getElementById('search-input'); + var searchResults = document.getElementById('search-results'); + var mainHeader = document.getElementById('main-header'); + var currentInput; + var currentSearchIndex = 0; - function hideResults() { - searchResults.innerHTML = ''; - searchResults.classList.remove('active'); + function showSearch() { + document.documentElement.classList.add('search-active'); + } + + function hideSearch() { + document.documentElement.classList.remove('search-active'); + } + + function update() { + currentSearchIndex++; + + var input = searchInput.value; + if (input === '') { + hideSearch(); + } else { + showSearch(); + // scroll search input into view, workaround for iOS Safari + window.scroll(0, -1); + setTimeout(function(){ window.scroll(0, 0); }, 0); + } + if (input === currentInput) { + return; + } + currentInput = input; + searchResults.innerHTML = ''; + if (input === '') { + return; } - jtd.addEvent(searchInput, 'keydown', function(e){ - switch (e.keyCode) { - case 38: // arrow up - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - active.classList.remove('active'); - if (active.parentElement.previousSibling) { - var previous = active.parentElement.previousSibling.querySelector('.search-result'); - previous.classList.add('active'); - } - } - return; - case 40: // arrow down - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - if (active.parentElement.nextSibling) { - var next = active.parentElement.nextSibling.querySelector('.search-result'); - active.classList.remove('active'); - next.classList.add('active'); - } - } else { - var next = document.querySelector('.search-result'); - if (next) { - next.classList.add('active'); - } - } - return; - case 13: // enter - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - active.click(); - } else { - var first = document.querySelector('.search-result'); - if (first) { - first.click(); - } - } - return; - } + var results = index.query(function (query) { + var tokens = lunr.tokenizer(input) + query.term(tokens, { + boost: 10 + }); + query.term(tokens, { + wildcard: lunr.Query.wildcard.TRAILING + }); }); - jtd.addEvent(searchInput, 'keyup', function(e){ - switch (e.keyCode) { - case 27: // When esc key is pressed, hide the results and clear the field - hideResults(); - searchInput.value = ''; - return; - case 38: // arrow up - case 40: // arrow down - case 13: // enter - e.preventDefault(); - return; + if ((results.length == 0) && (input.length > 2)) { + var tokens = lunr.tokenizer(input).filter(function(token, i) { + return token.str.length < 20; + }) + if (tokens.length > 0) { + results = index.query(function (query) { + query.term(tokens, { + editDistance: Math.round(Math.sqrt(input.length / 2 - 1)) + }); + }); } + } - hideResults(); + if (results.length == 0) { + var noResultsDiv = document.createElement('div'); + noResultsDiv.classList.add('search-no-result'); + noResultsDiv.innerText = 'No results found'; + searchResults.appendChild(noResultsDiv); - var input = this.value; - if (input === '') { + } else { + var resultsList = document.createElement('ul'); + resultsList.classList.add('search-results-list'); + searchResults.appendChild(resultsList); + + addResults(resultsList, results, 0, 10, 100, currentSearchIndex); + } + + function addResults(resultsList, results, start, batchSize, batchMillis, searchIndex) { + if (searchIndex != currentSearchIndex) { return; } + for (var i = start; i < (start + batchSize); i++) { + if (i == results.length) { + return; + } + addResult(resultsList, results[i]); + } + setTimeout(function() { + addResults(resultsList, results, start + batchSize, batchSize, batchMillis, searchIndex); + }, batchMillis); + } - var results = index.query(function (query) { - var tokens = lunr.tokenizer(input) - query.term(tokens, { - boost: 10 - }); - query.term(tokens, { - wildcard: lunr.Query.wildcard.TRAILING - }); - }); + function addResult(resultsList, result) { + var doc = docs[result.ref]; - if (results.length > 0) { - searchResults.classList.add('active'); - var resultsList = document.createElement('ul'); - resultsList.classList.add('search-results-list'); - searchResults.appendChild(resultsList); + var resultsListItem = document.createElement('li'); + resultsListItem.classList.add('search-results-list-item'); + resultsList.appendChild(resultsListItem); - for (var i in results) { - var result = results[i]; - var doc = docs[result.ref]; + var resultLink = document.createElement('a'); + resultLink.classList.add('search-result'); + resultLink.setAttribute('href', doc.url); + resultsListItem.appendChild(resultLink); - var resultsListItem = document.createElement('li'); - resultsListItem.classList.add('search-results-list-item'); - resultsList.appendChild(resultsListItem); + var resultTitle = document.createElement('div'); + resultTitle.classList.add('search-result-title'); + resultLink.appendChild(resultTitle); - var resultLink = document.createElement('a'); - resultLink.classList.add('search-result'); - resultLink.setAttribute('href', doc.url); - resultsListItem.appendChild(resultLink); + var resultDoc = document.createElement('div'); + resultDoc.classList.add('search-result-doc'); + resultDoc.innerHTML = ''; + resultTitle.appendChild(resultDoc); - var resultTitle = document.createElement('div'); - resultTitle.classList.add('search-result-title'); - resultTitle.innerText = doc.title; - resultLink.appendChild(resultTitle); + var resultDocTitle = document.createElement('div'); + resultDocTitle.classList.add('search-result-doc-title'); + resultDocTitle.innerHTML = doc.doc; + resultDoc.appendChild(resultDocTitle); + var resultDocOrSection = resultDocTitle; - var resultRelUrl = document.createElement('span'); - resultRelUrl.classList.add('search-result-rel-url'); - resultRelUrl.innerText = doc.relUrl; - resultTitle.appendChild(resultRelUrl); + if (doc.doc != doc.title) { + resultDoc.classList.add('search-result-doc-parent'); + var resultSection = document.createElement('div'); + resultSection.classList.add('search-result-section'); + resultSection.innerHTML = doc.title; + resultTitle.appendChild(resultSection); + resultDocOrSection = resultSection; + } - var metadata = result.matchData.metadata; - var contentFound = false; - for (var j in metadata) { - if (metadata[j].title) { - var position = metadata[j].title.position[0]; - var start = position[0]; - var end = position[0] + position[1]; - resultTitle.innerHTML = doc.title.substring(0, start) + '' + doc.title.substring(start, end) + '' + doc.title.substring(end, doc.title.length)+''+doc.relUrl+''; - - } else if (metadata[j].content && !contentFound) { - contentFound = true; - - var position = metadata[j].content.position[0]; - var start = position[0]; - var end = position[0] + position[1]; - var previewStart = start; - var previewEnd = end; - var ellipsesBefore = true; - var ellipsesAfter = true; - for (var k = 0; k < 3; k++) { - var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2); - var nextDot = doc.content.lastIndexOf('.', previewStart - 2); - if ((nextDot > 0) && (nextDot > nextSpace)) { - previewStart = nextDot + 1; - ellipsesBefore = false; - break; - } - if (nextSpace < 0) { - previewStart = 0; - ellipsesBefore = false; - break; - } - previewStart = nextSpace + 1; + var metadata = result.matchData.metadata; + var titlePositions = []; + var contentPositions = []; + for (var j in metadata) { + var meta = metadata[j]; + if (meta.title) { + var positions = meta.title.position; + for (var k in positions) { + titlePositions.push(positions[k]); + } + } + if (meta.content) { + var positions = meta.content.position; + for (var k in positions) { + var position = positions[k]; + var previewStart = position[0]; + var previewEnd = position[0] + position[1]; + var ellipsesBefore = true; + var ellipsesAfter = true; + for (var k = 0; k < {{ site.search.preview_words_before | default: 5 }}; k++) { + var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2); + var nextDot = doc.content.lastIndexOf('. ', previewStart - 2); + if ((nextDot >= 0) && (nextDot > nextSpace)) { + previewStart = nextDot + 1; + ellipsesBefore = false; + break; } - for (var k = 0; k < 10; k++) { - var nextSpace = doc.content.indexOf(' ', previewEnd + 1); - var nextDot = doc.content.indexOf('.', previewEnd + 1); - if ((nextDot > 0) && (nextDot < nextSpace)) { - previewEnd = nextDot; - ellipsesAfter = false; - break; - } - if (nextSpace < 0) { - previewEnd = doc.content.length; - ellipsesAfter = false; - break; - } - previewEnd = nextSpace; + if (nextSpace < 0) { + previewStart = 0; + ellipsesBefore = false; + break; } - var preview = doc.content.substring(previewStart, start); - if (ellipsesBefore) { - preview = '... ' + preview; - } - preview += '' + doc.content.substring(start, end) + ''; - preview += doc.content.substring(end, previewEnd); - if (ellipsesAfter) { - preview += ' ...'; - } - - var resultPreview = document.createElement('div'); - resultPreview.classList.add('search-result-preview'); - resultPreview.innerHTML = preview; - resultLink.appendChild(resultPreview); + previewStart = nextSpace + 1; } + for (var k = 0; k < {{ site.search.preview_words_after | default: 10 }}; k++) { + var nextSpace = doc.content.indexOf(' ', previewEnd + 1); + var nextDot = doc.content.indexOf('. ', previewEnd + 1); + if ((nextDot >= 0) && (nextDot < nextSpace)) { + previewEnd = nextDot; + ellipsesAfter = false; + break; + } + if (nextSpace < 0) { + previewEnd = doc.content.length; + ellipsesAfter = false; + break; + } + previewEnd = nextSpace; + } + contentPositions.push({ + highlight: position, + previewStart: previewStart, previewEnd: previewEnd, + ellipsesBefore: ellipsesBefore, ellipsesAfter: ellipsesAfter + }); } } } - }); - jtd.addEvent(searchInput, 'blur', function(){ - setTimeout(function(){ hideResults() }, 300); - }); + if (titlePositions.length > 0) { + titlePositions.sort(function(p1, p2){ return p1[0] - p2[0] }); + resultDocOrSection.innerHTML = ''; + addHighlightedText(resultDocOrSection, doc.title, 0, doc.title.length, titlePositions); + } + + if (contentPositions.length > 0) { + contentPositions.sort(function(p1, p2){ return p1.highlight[0] - p2.highlight[0] }); + var contentPosition = contentPositions[0]; + var previewPosition = { + highlight: [contentPosition.highlight], + previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, + ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter + }; + var previewPositions = [previewPosition]; + for (var j = 1; j < contentPositions.length; j++) { + contentPosition = contentPositions[j]; + if (previewPosition.previewEnd < contentPosition.previewStart) { + previewPosition = { + highlight: [contentPosition.highlight], + previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, + ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter + } + previewPositions.push(previewPosition); + } else { + previewPosition.highlight.push(contentPosition.highlight); + previewPosition.previewEnd = contentPosition.previewEnd; + previewPosition.ellipsesAfter = contentPosition.ellipsesAfter; + } + } + + var resultPreviews = document.createElement('div'); + resultPreviews.classList.add('search-result-previews'); + resultLink.appendChild(resultPreviews); + + var content = doc.content; + for (var j = 0; j < Math.min(previewPositions.length, {{ site.search.previews | default: 3 }}); j++) { + var position = previewPositions[j]; + + var resultPreview = document.createElement('div'); + resultPreview.classList.add('search-result-preview'); + resultPreviews.appendChild(resultPreview); + + if (position.ellipsesBefore) { + resultPreview.appendChild(document.createTextNode('... ')); + } + addHighlightedText(resultPreview, content, position.previewStart, position.previewEnd, position.highlight); + if (position.ellipsesAfter) { + resultPreview.appendChild(document.createTextNode(' ...')); + } + } + } + + {%- if site.search.rel_url != false %} + var resultRelUrl = document.createElement('span'); + resultRelUrl.classList.add('search-result-rel-url'); + resultRelUrl.innerText = doc.relUrl; + resultTitle.appendChild(resultRelUrl); + {%- endif %} + } + + function addHighlightedText(parent, text, start, end, positions) { + var index = start; + for (var i in positions) { + var position = positions[i]; + var span = document.createElement('span'); + span.innerHTML = text.substring(index, position[0]); + parent.appendChild(span); + index = position[0] + position[1]; + var highlight = document.createElement('span'); + highlight.classList.add('search-result-highlight'); + highlight.innerHTML = text.substring(position[0], index); + parent.appendChild(highlight); + } + var span = document.createElement('span'); + span.innerHTML = text.substring(index, end); + parent.appendChild(span); + } } + + jtd.addEvent(searchInput, 'focus', function(){ + setTimeout(update, 0); + }); + + jtd.addEvent(searchInput, 'keyup', function(e){ + switch (e.keyCode) { + case 27: // When esc key is pressed, hide the results and clear the field + searchInput.value = ''; + break; + case 38: // arrow up + case 40: // arrow down + case 13: // enter + e.preventDefault(); + return; + } + update(); + }); + + jtd.addEvent(searchInput, 'keydown', function(e){ + switch (e.keyCode) { + case 38: // arrow up + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + active.classList.remove('active'); + if (active.parentElement.previousSibling) { + var previous = active.parentElement.previousSibling.querySelector('.search-result'); + previous.classList.add('active'); + } + } + return; + case 40: // arrow down + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + if (active.parentElement.nextSibling) { + var next = active.parentElement.nextSibling.querySelector('.search-result'); + active.classList.remove('active'); + next.classList.add('active'); + } + } else { + var next = document.querySelector('.search-result'); + if (next) { + next.classList.add('active'); + } + } + return; + case 13: // enter + e.preventDefault(); + var active = document.querySelector('.search-result.active'); + if (active) { + active.click(); + } else { + var first = document.querySelector('.search-result'); + if (first) { + first.click(); + } + } + return; + } + }); + + jtd.addEvent(document, 'click', function(e){ + if (e.target != searchInput) { + hideSearch(); + } + }); +} +{%- endif %} + +// Switch theme + +jtd.getTheme = function() { + var cssFileHref = document.querySelector('[rel="stylesheet"]').getAttribute('href'); + return cssFileHref.substring(cssFileHref.lastIndexOf('-') + 1, cssFileHref.length - 4); } -function pageFocus() { - var mainContent = document.querySelector('.js-main-content'); - mainContent.focus(); +jtd.setTheme = function(theme) { + var cssFile = document.querySelector('[rel="stylesheet"]'); + cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | absolute_url }}' + theme + '.css'); } // Document ready jtd.onReady(function(){ initNav(); - pageFocus(); - if (typeof lunr !== 'undefined') { - initSearch(); - } + {%- if site.search_enabled != false %} + initSearch(); + {%- endif %} }); })(window.jtd = window.jtd || {}); diff --git a/assets/js/search-data.json b/assets/js/search-data.json deleted file mode 100644 index 0532f7c..0000000 --- a/assets/js/search-data.json +++ /dev/null @@ -1,12 +0,0 @@ ---- ---- -{ - {% assign comma = false %} - {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": { - "title": "{{ page.title | replace: '&', '&' }}", - "content": "{{ page.content | markdownify | replace: '' -%} + {%- assign title = titleAndContent[0] | replace_first: '>', '

' | split: '

' -%} + {%- assign title = title[1] | strip_html -%} + {%- assign content = titleAndContent[1] -%} + {%- assign url = page.url -%} + {%- if title == page.title and parts[0] == '' -%} + {%- assign title_found = true -%} + {%- else -%} + {%- assign id = titleAndContent[0] -%} + {%- assign id = id | split: 'id="' -%} + {%- if id.size == 2 -%} + {%- assign id = id[1] -%} + {%- assign id = id | split: '"' -%} + {%- assign id = id[0] -%} + {%- capture url -%}{{ url | append: '#' | append: id }}{%- endcapture -%} + {%- endif -%} + {%- endif -%} + {%- unless i == 0 -%},{%- endunless -%} + "{{ i }}": { + "doc": {{ page.title | jsonify }}, + "title": {{ title | jsonify }}, + "content": {{ content | replace: 'MIT license." + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo +gh_edit_branch: "master" # the branch that your docs is served from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately ``` +- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format +- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime) +- `gh_edit_repository` is the URL of the project's GitHub repository +- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master` +- `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode + ## Color scheme ```yaml -# Color scheme currently only supports "dark" or nil (default) -color_scheme: "dark" +# Color scheme supports "light" (default) and "dark" +color_scheme: dark ``` - + See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information. @@ -85,4 +138,5 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more # Google Analytics Tracking (optional) # e.g, UA-1234567-89 ga_tracking: UA-5555555-55 +ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default) ``` diff --git a/docs/customization.md b/docs/customization.md index 883c94c..cbcd38c 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -29,37 +29,77 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf {: .no_toc } ```yaml -# Color scheme currently only supports "dark" or nil (default) -color_scheme: "dark" +# Color scheme supports "light" (default) and "dark" +color_scheme: dark ``` - + -To customize your site’s aesthetic, open `_sass/custom/custom.scss` in your editor to see if there is a variable that you can override. Most styles like fonts, colors, spacing, etc. are derived from these variables. To override a specific variable, uncomment its line and change its value. +## Custom schemes -For example, to change the link color from the purple default to blue, open `_sass/custom/custom.css` and find the `$link-color` variable on line `50`. Uncomment it, and change its value to our `$blue-000` variable, or another shade of your choosing. +### Define a custom scheme + +You can add custom schemes. +If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name) +where you override theme variables to change colors, fonts, spacing, etc. + +Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_variables.scss) file. + +For example, to change the link color from the purple default to blue, include the following inside your scheme file: #### Example {: .no_toc } ```scss -// ... -// -// $body-text-color: $grey-dk-100; -// $body-heading-color: $grey-dk-300; $link-color: $blue-000; -// -// ... ``` _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail. +Please use scheme files. -## Override styles +### Use a custom scheme -For styles that aren't defined as a variables, you may want to modify specific CSS classes. To add your own CSS overrides at the end of the cascade, edit `_sass/overrides.scss`. This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied. +To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file: +```yaml +color_scheme: foo +``` + +### Switchable custom scheme + +If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name) +with the following content:` + +{% raw %} + --- + --- + {% include css/just-the-docs.scss.liquid color_scheme="foo" %} +{% endraw %} + +This allows you to switch the scheme via the following javascript. + +```js +jtd.setTheme('foo'); +``` + +## Override and completely custom styles + +For styles that aren't defined as variables, you may want to modify specific CSS classes. +Additionally, you may want to add completely custom CSS specific to your content. +To do this, put your styles in the file `_sass/custom/custom.scss`. +This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied. For example, if you'd like to add your own styles for printing a page, you could add the following styles. diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md index a4fef75..d5a7504 100644 --- a/docs/navigation-structure.md +++ b/docs/navigation-structure.md @@ -38,6 +38,13 @@ nav_order: 4 --- ``` +The specified `nav_order` parameters on a site should be all integers or all strings. +Pages without a `nav_order` parameter are ordered alphabetically by their `title`, +and appear after the explicitly-ordered pages at each level. +By default, all Capital letters are sorted before all lowercase letters; +adding `nav_sort: case_insensitive` in the configuration file ignores case +when sorting strings (but also sorts numbers lexicographically: `10` comes before `1`). + --- ## Excluding pages @@ -190,9 +197,9 @@ This would create the following navigation structure: --- -## Auxiliary Navigation +## Auxiliary Links -To add a auxiliary navigation item to your site (in the upper right on all pages), add it to the `aux_nav` [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-nav) in your site's `_config.yml` file. +To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file. #### Example {: .no_toc } @@ -224,4 +231,21 @@ To generate a Table of Contents on your docs pages, you can use the `{:toc}` met {:toc} ``` -This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. +This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`. + +### Collapsible Table of Contents + +The Table of Contents can be made collapsible using the `
` and `` elements , as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional. + +```markdown +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+``` + +The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page). diff --git a/docs/search.md b/docs/search.md index 3556786..495884d 100644 --- a/docs/search.md +++ b/docs/search.md @@ -15,62 +15,90 @@ nav_order: 7 --- -Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated HTML pages are indexed using the following data points: +Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. +All search results are shown in an auto-complete style interface (there is no search results page). +By default, all generated HTML pages are indexed using the following data points: - Page title - Page content - Page URL -## Set up search - -### Generate search index - -Before you can use search, you must initialize the feature by running this `rake` command that comes with `just-the-docs`: - -```bash -$ bundle exec just-the-docs rake search:init -``` - -This command creates the `search-data.json` file that Jekyll uses to create your search index. Alternatively, you can create the file manually in the `assets/js/` directory of your Jekyll site with this content: - -```liquid -{% raw %}--- ---- -{ - {% assign comma = false %} - {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": { - "title": "{{ page.title | replace: '&', '&' }}", - "content": "{{ page.content | markdownify | replace: ' Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +## Heading with `` in it. +{: .no_toc }

```markdown Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +## Heading with `` in it. ``` --- diff --git a/docs/utilities/color.md b/docs/utilities/color.md index ba90b3b..0f37597 100644 --- a/docs/utilities/color.md +++ b/docs/utilities/color.md @@ -2,7 +2,6 @@ layout: default title: Color parent: Utilities -nav_order: 3 --- # Color Utilities diff --git a/docs/utilities/layout.md b/docs/utilities/layout.md index 38ec1b2..c2f5eb3 100644 --- a/docs/utilities/layout.md +++ b/docs/utilities/layout.md @@ -2,7 +2,6 @@ layout: default title: Layout parent: Utilities -nav_order: 2 --- # Layout Utilities @@ -52,6 +51,9 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes | `6` | 2rem | 32px | | `7` | 2.5rem | 40px | | `8` | 3rem | 48px | +| `auto` | auto | auto | + +Use `mx-auto` to horizontally center elements. #### Examples {: .no_toc } @@ -66,6 +68,19 @@ This paragraph will have 2rem/32px of padding on the right and left at all scree {: .px-6 } ``` +## Horizontal Alignment + +| Classname | What it does | +|:------------------------|:---------------------------------| +| `.float-left` | `float: left` | +| `.float-right` | `float: right` | +| `.flex-justify-start` | `justify-content: flex-start` | +| `.flex-justify-end` | `justify-content: flex-end` | +| `.flex-justify-between` | `justify-content: space-between` | +| `.flex-justify-around` | `justify-content: space-around` | + +_Note: any of the `flex-` classes must be used on a parent element that has `d-flex` applied to it._ + ## Vertical Alignment | Classname | What it does | diff --git a/docs/utilities/responsive-modifiers.md b/docs/utilities/responsive-modifiers.md index bc5e2cb..c732530 100644 --- a/docs/utilities/responsive-modifiers.md +++ b/docs/utilities/responsive-modifiers.md @@ -2,7 +2,6 @@ layout: default title: Responsive Modifiers parent: Utilities -nav_order: 1 --- # Responsive modifiers diff --git a/docs/utilities/typography.md b/docs/utilities/typography.md index 786b65a..1c5dca9 100644 --- a/docs/utilities/typography.md +++ b/docs/utilities/typography.md @@ -2,7 +2,6 @@ layout: default title: Typography parent: Utilities -nav_order: 4 --- # Typography Utilities @@ -145,3 +144,13 @@ Default line height Default line height {: .fh-default } ``` + +## Text justification + +By default text is justified left. Use these `text-` classes to override settings: + +| Class | What it does | +|:---------------|:---------------------| +| `.text-left` | `text-align: left` | +| `.text-right` | `text-align: right` | +| `.text-center` | `text-align: center` | diff --git a/index.md b/index.md index 7be9b22..7bf9947 100644 --- a/index.md +++ b/index.md @@ -4,6 +4,7 @@ title: Home nav_order: 1 description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages." permalink: / +last_modified_date: 2020-04-27T17:54:08+0000 --- # Focus on writing good documentation @@ -68,7 +69,7 @@ If you're hosting your site on GitHub Pages, [set up GitHub Pages and Jekyll loc ## About the project -Just the Docs is © 2017-2019 by [Patrick Marsceill](http://patrickmarsceill.com). +Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](http://patrickmarsceill.com). ### License diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index a0b8607..16cee61 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -2,7 +2,7 @@ Gem::Specification.new do |spec| spec.name = "just-the-docs" - spec.version = "0.2.8" + spec.version = "0.3.1" spec.authors = ["Patrick Marsceill"] spec.email = ["patrick.marsceill@gmail.com"] @@ -12,9 +12,9 @@ Gem::Specification.new do |spec| spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } spec.executables << 'just-the-docs' - - spec.add_runtime_dependency "bundler", "~> 2.1.4" - spec.add_runtime_dependency "jekyll", ">= 3.8.5", "< 4.1.0" + + spec.add_development_dependency "bundler", "~> 2.1.4" + 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", "< 13.1.0" diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake index 5c03790..8e6305a 100644 --- a/lib/tasks/search.rake +++ b/lib/tasks/search.rake @@ -3,23 +3,68 @@ namespace :search do task :init do puts 'Creating search data json file...' mkdir_p 'assets/js' - touch 'assets/js/search-data.json' - content = %Q[{{ page.content | markdownify | replace: '\' -%} + {%- assign title = titleAndContent[0] | replace_first: \'>\', \'

\' | split: \'

\' -%} + {%- assign title = title[1] | strip_html -%} + {%- assign content = titleAndContent[1] -%} + {%- assign url = page.url -%} + {%- if title == page.title and parts[0] == \'\' -%} + {%- assign title_found = true -%} + {%- else -%} + {%- assign id = titleAndContent[0] -%} + {%- assign id = id | split: \'id="\' -%} + {%- if id.size == 2 -%} + {%- assign id = id[1] -%} + {%- assign id = id | split: \'"\' -%} + {%- assign id = id[0] -%} + {%- capture url -%}{{ url | append: \'#\' | append: id }}{%- endcapture -%} + {%- endif -%} + {%- endif -%} + {%- unless i == 0 -%},{%- endunless -%} + "{{ i }}": { + "doc": {{ page.title | jsonify }}, + "title": {{ title | jsonify }}, + "content": {{ content | replace: \'