steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-10 14:01:22 -06:00
Code Issues Packages Projects Releases Wiki Activity
just-the-docs/_config.yml
Peter Mosses 9d0ce1c22a
Fix the navigation panel (#1244) 
* Fix the nav html and cache it

- Remove `active` class from nav html
- Add js to insert `active` class on link to selected page
- Include attempt to generate page-specific css for same styling when js is off

* Refactor nav, breadcrumbs, children_nav

Fix #1118

Improve the modularity of building the nav-panel, breadcrumbs, and children-nav
by making them independent. This also significantly simplifies the Liquid code.

* Manual merge of fix-leakage

Also fix order of breadcrumbs

* Fix order of breadcrumbs

* Revert layout in HTML

Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.

* Update breadcrumbs.html

Revert inclusion of single breadcrumb for top-level pages.

* Update breadcrumbs.html

Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.

* Update children_nav.html

Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.

* Delete nav_init.html

* Update sidebar.html

Caches.

* Add a comment

* Update nav.html

- Comment on independence from page.
- Remove redundant comment.
- Remove superfluous conditionals.

* Update just-the-docs.gemspec

Revert jekyll version spec change.

* Update just-the-docs.gemspec

Revert runtime dependency on kramdown-parser-gfm.

* Revert inclusion of activation.scss.liquid

Inclusion makes HTML of all pages differ from 0.5.1

* Update default.html

Restore deleted "<!DOCTYPE html>"

* Update children_nav.html

Restore line break.

* Delete activation.scss.liquid

This was merely an example of page-specific CSS for use when JS off.

* Remove an unused include parameter

`nav.html` does not depend on `include.key`.

* Generate page-specific styling for nav links and lists in the side-nav

In this PR, the code in `includes/nav.html` is fixed, and none of its elements have class `active`. When JS is enabled, `activateNav()` adds the class `active` to all nav-list-items that enclose the nav-list-link to the current page, so the navigation works as usual. Unobtrusive JS requires the same behaviour when JS is disabled.

- Add `_includes/css/activation.scss.liquid` to compute the indices in the enclosing nav-lists of the nav-list-link to the current page, and generate page-specific styling.
- Insert Liquid code in `_includes/head.html` to include the CSS generated by `_includes/css/activation.scss.liquid` (which depends on `site.color_scheme`).
- Update the toggling in `initNav()` to allow also contraction of enclosing levels when JS is enabled.

Caveat: When JS is enabled, buttons can be used to switch the colour scheme dynamically. The page-specific styling of the site-nav is generated statically, and doesn't change, so the background-image of the nav-list-link to the current page is incorrect. (I guess that could be fixed by generating a style element for each available colour scheme, and using JS to reorder the stylesheets in the DOM.)

A further issue is that the `@import` rules used in `_includes/head.html` cause duplication. Replacing them by `@use` rules would avoid duplication, but that is out of scope for this PR.

* Fix activation for collections

- Adjust generated selectors to pages in collections.
- Expand all folded collections when JS is disabled.

This PR should now make unobtrusive use of JS:

- When JS is disabled, the navigation panel shows links to the top pages in all collections (in contrast to the current version of the theme).
- When JS is enabled, folded collections remain folded until their pages are selected.

* Respect `child_nav_order`

- Assumes reverse order when set to any truthy value.

* Suppress liquid line breaks

* Cache the search for favicon.ico

- Move the code for finding the favicon.ico file to `_includes/favicon.html`.
- Replace that code in `_includes.html` by a cached include of `favicon.html`.

* Add "jekyll-include-cache" in fixtures

Needed when CI ignores the gemspec.

* Add gem "jekyll-include-cache" in fixtures

Needed when CI ignores the gemspec.

* Update head.html

- Avoid duplication of color_scheme CSS in `style` element.
- Avoid generation of whitespace by Liquid code.

* Update sorted_pages.html

- Minor optimisation.
- Minor improvements to layout of Liquid code.

* Ensure split is not at start of rules generated by css/activation.scss.liquid

A custom color scheme might not import any highlighting style rules, so we should not assume that there is anything before the first occurrence of `.site-nav`.

* Update head.html

- Add implicit import of light color scheme.
- Revert to previous Liquid code for removing color scheme rules.

* Manual resolution of merge conflicts with v0.5.2

- Copied replacement of links on nav expanders by buttons.
- Removed (page-dependent) conditions associated with `active`.

* Manual resolution of merge conflict with v0.5.2

If previously "" (neither active nor passive), then `active && passive` is true, and the target is now "active".
If previously only "active", then the target is now just "passive".
If previously only "passive", then the target is now just "active".
The state "active passive" is never used.
The value of `active` is true just when the target is left "active".

* Update fixtures/Gemfile-github-pages

Co-authored-by: Matt Wang <matt@matthewwang.me>

* Update head.html

The result of `activation.scss.liquid` is "" for pages with no `title` or with `nav_exclude`. This update  stops `head.html`  including a `style` element with an invalid body on such pages.

Note that when the result of `scssify` doesn't contain `.site-nav`, `split` produces a one-element array, so `shift` produces an empty array, and `join` then produces an empty string.

* Fix omitted `.site-nav`

Restore the previous prepending of `.site-nav`, which was dropped when suppressing the generation of an incorrect `<style>` element for pages excluded from the navigation.

* Add a footnote about `.site-nav`

* Make setTheme remove background images from nav links

With a fixed nav panel, a <style> in the <head> sets a background image to highlight the nav list link to the current page. The image color depends on site.color_scheme.

Ideally, setTheme(theme) would change the image color to match the theme/scheme. Here, for simplicity, we merely remove the image.

* Explain `nav_fold` in collections.

* Refactor

Attempt at cleaning up the duplicated nav links code and simplifying removal of the background image:

* Add function `navLink()`
* Replace `removeNavBackgroundImages()` by `removeNavBackgroundImage()`
* Replace var `siteNav` by `document.getElementById('site-nav')`
* Replace code in `scrollNav` and `activateNav` by `navLink()`
* Replace a (non-local!) reference to `siteNav` by `document`

* Disable the page-specific stylesheet when JS is enabled

The page-specific `<style>` in the `<head>` is needed only when JS is disabled. Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme).

The page-specific stylesheet is assumed to have index 1 in the list of stylesheets. It would be safer to select it by `id`, but adding an `id` can break existing sites.

* Avoid constraint on use of `.site-nav`, and refactor

Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored.

Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`.

Remove the footnote about `.site-nav` in `docs/customization.md`.

Test the styling with JS disabled, since the resulting style element is disabled by JS.

* Revert "Avoid constraint on use of `.site-nav`, and refactor"

This reverts commit 5284892a7486ef9d2af9929c8a509b89731bb233.

* Avoid constraint on use of `.site-nav`, and refactor

(This corrects a bug in the previous reverted commit for excluded pages such as 404.html.)

Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored.

Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`.

Remove the footnote about `.site-nav` in `docs/customization.md`.

Test the styling with JS disabled, since the resulting style element is disabled by JS.

* Update comment

* Fix duplicate plugins setting

@mattxwang noticed that the second `plugins` setting was apparently overriding the first, leading to a missing plugin when using `fixtures/Gemfile-github-pages`.

* Avoid double inclusion of activation file

The previous changes to remove the constraint re ".site-nav" duplicated the inclusion of `css/activation.scss.liquid`.
That caused significant extra build time, which the current changes to `head_nav.html` avoid (without affecting the built site).

* Clarify collection configuration docs

* Update and clarify the CHANGELOG

---------

Co-authored-by: Matt Wang <matt@matthewwang.me>
2023-08-18 20:35:14 +02:00

187 lines
6.1 KiB
YAML
Raw Blame History

# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole site, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing these this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'jekyll serve'. If you change this file, please restart the server process.
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: Just the Docs
description: A Jekyll theme for documentation
baseurl: "" # the subpath of your site, e.g. /blog
url: "https://just-the-docs.com" # the base hostname & protocol for your site, e.g. http://example.com
repository: just-the-docs/just-the-docs # for github-metadata
permalink: pretty
exclude:
# from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/
# specific to the theme website:
- bin/
- lib/
- "*.gemspec"
- "*.gem"
- LICENSE.txt
- package.json
- package-lock.json
- Rakefile
- README.md
- CODE_OF_CONDUCT.md
- docker-compose.yml
- Dockerfile
# theme test code
- fixtures/
# Set a path/url to a logo that will be displayed instead of the title
#logo: "/assets/images/just-the-docs.png"
# Enable or disable the site search
# Supports true (default) or false
search_enabled: true
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: 2
# Maximum amount of words to display before a matched word in the preview
# Default: 5
preview_words_before: 3
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 3
# 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
# For copy button on code
enable_copy_code_button: true
# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
mermaid:
# Version of mermaid library
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
version: "9.1.6"
# Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
# See also docs/ui-components/code
# To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
# for (v10+):
# path: "/assets/js/mermaid.esm.min.mjs"
# for (<v10):
# path: "/assets/js/mermaid.min.js"
# Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
# Enable or disable heading anchors
heading_anchors: true
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/just-the-docs/just-the-docs"
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
# Sort order for navigation links
# 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
# Back to top link
back_to_top: true
back_to_top_text: "Back to top"
footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a> <a href=\"https://www.netlify.com/\">This site is powered by Netlify.</a>"
# 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/just-the-docs/just-the-docs" # the github URL for your repo
gh_edit_branch: "main" # the branch that your docs is served from
# gh_edit_source: docs # the source that your files originate 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
callouts_level: quiet # or loud
callouts:
highlight:
color: yellow
important:
title: Important
color: blue
new:
title: New
color: green
note:
title: Note
color: purple
warning:
title: Warning
color: red
# Google Analytics Tracking (optional)
# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
# Note: the main Just the Docs site does *not* use Google Analytics.
# ga_tracking: UA-2709176-10,G-5FG1HLH3XQ
# ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
plugins:
- jekyll-seo-tag
- jekyll-github-metadata
- jekyll-include-cache
kramdown:
syntax_highlighter_opts:
block:
line_numbers: false
compress_html:
clippings: all
comments: all
endings: all
startings: []
blanklines: false
profile: false
# ignore:
# envs: all
Reference in New Issue View Git Blame Copy Permalink