diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e06c8d..c70a0ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,10 +25,12 @@ Docs changes made since the latest release: - Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440] - Added: sitemap (via `jekyll-sitemap` plugin) by [@mattxwang] in [#1530] +- Fixed: (non-systemic) accessibility issues flagged by aXe by [@mattxwang] in [#1531] [#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431 [#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440 [#1530]: https://github.com/just-the-docs/just-the-docs/pull/1530 +[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1531 ## Release v0.9.0 diff --git a/docs/customization.md b/docs/customization.md index 8d70b44..61ec820 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -20,8 +20,8 @@ Just the Docs supports two color schemes: light (default), and dark. To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file: -#### Example -{: .no_toc } +### Example: preview dark color scheme +{: .no_toc .text-delta } ```yaml # Color scheme supports "light" (default) and "dark" @@ -76,8 +76,8 @@ Available variables are listed in the [\_variables.scss](https://github.com/just For example, to change the link color from the purple default to blue, include the following inside your scheme file: -#### Example -{: .no_toc } +#### Example: custom link color +{: .no_toc .text-delta } ```scss $link-color: $blue-000; @@ -142,10 +142,10 @@ 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. +### Example: custom print styles +{: .no_toc .text-delta } -#### Example -{: .no_toc } +For example, if you'd like to add your own styles for printing a page, you could add the following styles. ```scss // Print-only styles. @@ -179,7 +179,7 @@ New (v0.4.0) If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation/children.md %}) after the page's content. -#### Example +#### Example: changing TOC heading {: .no_toc } To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add: diff --git a/docs/index-test.md b/docs/index-test.md index 7e0c62b..d664c78 100644 --- a/docs/index-test.md +++ b/docs/index-test.md @@ -27,17 +27,17 @@ There should be whitespace between paragraphs. There should be whitespace between paragraphs. We recommend including a README, or a file with information about your project. -# [](#header-1)Header 1 +# Header 1 This is a normal paragraph following a header. GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. -## [](#header-2)Header 2 +## Header 2 > This is a blockquote following a header. > > When something is important enough, you do it even if the odds are not in your favor. -### [](#header-3)Header 3 +### Header 3 ```js // Javascript code with syntax highlighting. @@ -54,19 +54,19 @@ GitHubPages::Dependencies.gems.each do |gem, version| end ``` -#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed` +#### Header 4 `with code not transformed` * This is an unordered list following a header. * This is an unordered list following a header. * This is an unordered list following a header. -##### [](#header-5)Header 5 +##### Header 5 1. This is an ordered list following a header. 2. This is an ordered list following a header. 3. This is an ordered list following a header. -###### [](#header-6)Header 6 +###### Header 6 [This is a very long link which wraps and therefore doesn't overflow even when it comes at the beginning](.) of the line. @@ -303,6 +303,8 @@ The following code is displayed as a diagram only when a `mermaid` key supplied ```mermaid graph TD; + accTitle: the diamond pattern + accDescr: a graph with four nodes: A points to B and C, while B and C both point to D A-->B; A-->C; B-->D; diff --git a/docs/layout/minimal/default-child.md b/docs/layout/minimal/default-child.md index 3035580..9e09c95 100644 --- a/docs/layout/minimal/default-child.md +++ b/docs/layout/minimal/default-child.md @@ -1,8 +1,10 @@ --- title: Default layout child page layout: default -parent: A minimal layout page +parent: A minimal layout page grand_parent: Layout --- +# A minimal layout page + This is a child page that uses the same minimal layout as its parent page. diff --git a/docs/layout/minimal/minimal-child.md b/docs/layout/minimal/minimal-child.md index 26bcff7..2553b26 100644 --- a/docs/layout/minimal/minimal-child.md +++ b/docs/layout/minimal/minimal-child.md @@ -5,4 +5,6 @@ parent: A minimal layout page grand_parent: Layout --- +# Minimal layout child page + This is a child page that uses the same minimal layout as its parent page. diff --git a/docs/minimal-test.md b/docs/minimal-test.md index aa754d3..72b5905 100644 --- a/docs/minimal-test.md +++ b/docs/minimal-test.md @@ -4,6 +4,8 @@ title: Minimal layout test nav_exclude: true --- +# Minimal Layout Test Page + [Return to main website]({{site.baseurl}}/). This page demonstrates the packaged `minimal` layout, which does not render the sidebar or header. It can be used for standalone pages. It is also an example of using the new modular site components to define custom layouts; see ["Custom layouts and includes" in the customization docs]({{site.baseurl}}/docs/customization/#custom-layouts-and-includes) for more information. diff --git a/docs/navigation/auxiliary.md b/docs/navigation/auxiliary.md index d1e4818..621dc3c 100644 --- a/docs/navigation/auxiliary.md +++ b/docs/navigation/auxiliary.md @@ -8,7 +8,10 @@ nav_order: 2 You can add a list of auxiliary links to your site, shown at the top right on all pages. You do this by including the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file. -#### Example +## Example Auxiliary Link +{: .text-delta } + +This website has an auxiliary link: "Just the Docs on GitHub". It is rendered with the following code: ```yaml aux_links: diff --git a/docs/navigation/children.md b/docs/navigation/children.md index 4813205..1df8c3e 100644 --- a/docs/navigation/children.md +++ b/docs/navigation/children.md @@ -10,7 +10,8 @@ By default, all parent pages will automatically have a so-called 'Table of Conte To disable this automatic list, set `has_toc: false` in the parent page's front matter. -#### Example +## Example: disabling table of contents +{: .text-delta } ```yaml --- diff --git a/docs/navigation/in-page.md b/docs/navigation/in-page.md index b84a95b..cc96332 100644 --- a/docs/navigation/in-page.md +++ b/docs/navigation/in-page.md @@ -15,14 +15,13 @@ nav_order: 5 To support in-page navigation, you can generate a *Table of Contents* (TOC) with links to headings, like the one shown above, as well as a link to the top of the page. -## Table of Contents +## Generating Table of Contents To generate a *Table of Contents* in a page, you use Kramdown's `{:toc}` method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels. -If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names). +## Omitting Heading from Table of Contents -#### Example -{: .no_toc } +If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names). ```markdown # In-Page Navigation @@ -39,13 +38,10 @@ This example omits the top-level heading (`In-Page Navigation`) from the TOC, as To get an unordered list, replace `1. TOC` by `- TOC` in the above example. -## Collapsible Table of Contents +## Collapsible Table of Contents (with `
` and ``) You can make the Table of Contents collapsible using the `
` and `` elements, as in the following example. -#### Example -{: .no_toc } - ```markdown
diff --git a/docs/navigation/main/ancestry.md b/docs/navigation/main/ancestry.md index 8b7dac0..189dec3 100644 --- a/docs/navigation/main/ancestry.md +++ b/docs/navigation/main/ancestry.md @@ -10,7 +10,8 @@ If no two pages on your website have the same `title`, you only need to set the If two parents have the same `title`, but different grandparents, you can set their `grand_parent` titles to distinguish between their parents. The `grand_parent` title needs to be the same as the `parent` of the `parent`. -#### Example +## Example: distinguishing parents with `grand_parent` +{: .text-delta } ```yaml --- diff --git a/docs/navigation/main/collections.md b/docs/navigation/main/collections.md index 9ef1bd3..acfba55 100644 --- a/docs/navigation/main/collections.md +++ b/docs/navigation/main/collections.md @@ -14,7 +14,8 @@ However, you can configure Just the Docs to include also pages from [Jekyll coll [^1]: You can optionally specify a directory to store all your collections. For example, if you specify `collections_dir: my_collections` in `_config.yml`, you should then store the pages of the `tests` collection in the `my_collections/_tests` directory. -#### Example +## Example: defining custom collections +{: .text-delta } To define a Jekyll `tests` collection named `Tests` in your main navigation, store its pages in the `_tests` directory, and add the following to `_config.yml`: @@ -41,9 +42,10 @@ Together with the `name` to be used for a collection in the navigation, you can The main navigation for all your normal pages (if any) is displayed before those in collections. When *all* your pages are in a single collection, its name is not displayed. -You can configure multiple collections. This creates categories in the main navigation with the configured names. +## Example: multiple collections +{: .text-delta } -#### Example +You can configure multiple collections. This creates categories in the main navigation with the configured names. ```yaml collections: diff --git a/docs/navigation/main/exclude.md b/docs/navigation/main/exclude.md index 93f223f..5711cbf 100644 --- a/docs/navigation/main/exclude.md +++ b/docs/navigation/main/exclude.md @@ -8,7 +8,8 @@ nav_order: 2 For specific pages that you do not wish to include in the main navigation (e.g., a 404 page or a landing page) set `nav_exclude: true` in their front matter. -#### Example +## Example: using `nav_exclude` +{: .text-delta } ```yaml --- @@ -19,7 +20,7 @@ permalink: /404 --- ``` -The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation. +The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation. Pages with no `title` are automatically excluded from the main navigation, except when they are in collections (where Jekyll provides default titles based on file names). diff --git a/docs/navigation/main/external.md b/docs/navigation/main/external.md index a0dfd8b..e4c3c66 100644 --- a/docs/navigation/main/external.md +++ b/docs/navigation/main/external.md @@ -9,7 +9,8 @@ nav_order: 6 To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file. External links will appear in the navigation after the links to ordinary pages, but before any collections. -#### Example +## Example: external links +{: .text-delta } ```yaml # External navigation links diff --git a/docs/navigation/main/levels.md b/docs/navigation/main/levels.md index 2855ae8..6ed73b5 100644 --- a/docs/navigation/main/levels.md +++ b/docs/navigation/main/levels.md @@ -31,7 +31,8 @@ Sometimes you will want to create a page with many children. First, it is recomm └─ ... ``` -#### Example +## Example: page with no parents +{: .text-delta } ```yaml --- @@ -42,13 +43,14 @@ nav_order: 3 Here we're setting up the UI Components landing page that is available at URL `/docs/ui-components`, which is ordered second in the main navigation. -The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active. +The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active. ## Child Pages On child pages, simply set the `parent` front matter to the parent page's `title`, and set a navigation order (relative to pages having the same parent). -#### Example +### Example: creating a child page +{: .text-delta } ```yaml --- @@ -67,9 +69,10 @@ The Buttons page appears as a child of UI Components and appears second in the U ## Multi-level Child Pages -Child pages can themselves have children, to any number of levels. +Child pages can themselves have children, to any number of levels. -#### Example +### Example: pages with (recursive) children +{: .text-delta } ```yaml --- diff --git a/docs/navigation/main/order.md b/docs/navigation/main/order.md index e2bdaa2..f99578c 100644 --- a/docs/navigation/main/order.md +++ b/docs/navigation/main/order.md @@ -8,7 +8,8 @@ nav_order: 1 To specify a page order, you can use the `nav_order` parameter in the front matter of the pages. -#### Example +## Example: using `nav_order` +{: .text-delta } ```yaml --- @@ -30,6 +31,6 @@ Enclosing strings in quotation marks in front matter is optional, unless they co ---- -[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*. +[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*. -[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. +[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. diff --git a/docs/search.md b/docs/search.md index 7d12004..066b806 100644 --- a/docs/search.md +++ b/docs/search.md @@ -113,8 +113,6 @@ Will make Ctrl + K focus the search bar for Windows users Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter: -#### Example - {: .no_toc } ```yaml @@ -158,7 +156,8 @@ By default, the search feature indexes a page's `.content`, `.title`, and *some* 2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`. 3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code. -#### Example +### Example: adding custom `usage` and `examples` fields +{: .text-delta } This example adds front matter `usage` and `examples` fields to the search index. diff --git a/docs/ui-components/callouts.md b/docs/ui-components/callouts.md index bb3f41b..bf6dee5 100644 --- a/docs/ui-components/callouts.md +++ b/docs/ui-components/callouts.md @@ -22,8 +22,8 @@ When you have [configured]({% link docs/configuration.md %}#callouts) the `colo [^postfix]: You can put the callout markup either before or after its content. -#### An untitled callout -{: .no_toc } +## An untitled callout +{: .no_toc .text-delta } ```markdown {: .highlight } @@ -34,8 +34,8 @@ A paragraph A paragraph -#### A single paragraph callout -{: .no_toc } +## A single paragraph callout +{: .no_toc .text-delta } ```markdown {: .note } @@ -57,8 +57,8 @@ A paragraph > > A paragraph with a custom title callout -#### A multi-paragraph callout -{: .no_toc } +## A multi-paragraph callout +{: .no_toc .text-delta } ```markdown {: .important } @@ -96,8 +96,8 @@ A paragraph > > The last paragraph -#### An indented callout -{: .no_toc } +## An indented callout +{: .no_toc .text-delta } ```markdown > {: .highlight } @@ -107,8 +107,8 @@ A paragraph > {: .highlight } A paragraph -#### Indented multi-paragraph callouts -{: .no_toc } +## Indented multi-paragraph callouts +{: .no_toc .text-delta } ```markdown > {: .new } @@ -127,8 +127,8 @@ A paragraph > > The last paragraph -#### Nested callouts -{: .no_toc } +## Nested callouts +{: .no_toc .text-delta } ```markdown {: .important } @@ -140,8 +140,8 @@ A paragraph > {: .warning } > A paragraph -#### Opaque background -{: .no_toc } +## Opaque background +{: .no_toc .text-delta } ```markdown {: .important } diff --git a/docs/ui-components/code/index.md b/docs/ui-components/code/index.md index d4a70e2..bc3857d 100644 --- a/docs/ui-components/code/index.md +++ b/docs/ui-components/code/index.md @@ -129,6 +129,8 @@ Once mermaid is installed, it can be used in markdown files. The markdown for a {% highlight markdown %} ```mermaid graph TD; + accTitle: the diamond pattern + accDescr: a graph with four nodes: A points to B and C, while B and C both point to D A-->B; A-->C; B-->D; @@ -140,6 +142,8 @@ which renders: ```mermaid graph TD; + accTitle: the diamond pattern + accDescr: a graph with four nodes: A points to B and C, while B and C both point to D A-->B; A-->C; B-->D; @@ -177,6 +181,8 @@ By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. T ++++ 
 graph TD;
+    accTitle: the diamond pattern
+    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;
diff --git a/docs/utilities/layout.md b/docs/utilities/layout.md
index 65d371e..13138e9 100644
--- a/docs/utilities/layout.md
+++ b/docs/utilities/layout.md
@@ -18,7 +18,7 @@ parent: Utilities
 
 These spacers are available to use for margins and padding with responsive utility classes. Combine these prefixes with a screen size and spacing scale to use them responsively.
 
-| Classname prefix | What it does                  |
+| Classname prefix | Related CSS Property          |
 |:-----------------|:------------------------------|
 | `.m-`            | `margin`                      |
 | `.mx-`           | `margin-left`, `margin-right` |
@@ -28,7 +28,7 @@ These spacers are available to use for margins and padding with responsive utili
 | `.mb-`           | `margin-bottom`               |
 | `.ml-`           | `margin-left`                 |
 
-| Classname prefix | What it does                    |
+| Classname prefix | Related CSS Property            |
 |:-----------------|:--------------------------------|
 | `.p-`            | `padding`                       |
 | `.px-`           | `padding-left`, `padding-right` |
@@ -54,8 +54,8 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes
 
 Use `mx-auto` to horizontally center elements.
 
-#### Examples
-{: .no_toc }
+### Applying Spacing Utilities with `{: }`
+{: .no_toc .text-delta }
 
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
@@ -69,7 +69,7 @@ This paragraph will have 2rem/32px of padding on the right and left at all scree
 
 ## Horizontal Alignment
 
-| Classname               | What it does                     |
+| CSS Class               | Applied CSS Declaration          |
 |:------------------------|:---------------------------------|
 | `.float-left`           | `float: left`                    |
 | `.float-right`          | `float: right`                   |
@@ -82,7 +82,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 ## Vertical Alignment
 
-| Classname              | What it does                    |
+| CSS Class              | Applied CSS Declaration         |
 |:-----------------------|:--------------------------------|
 | `.v-align-baseline`    | `vertical-align: baseline`      |
 | `.v-align-bottom`      | `vertical-align: bottom`        |
@@ -95,7 +95,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 Display classes aid in adapting the layout of the elements on a page:
 
-| Class             |                         |
+| CSS Class         | Applied CSS Declaration |
 |:------------------|:------------------------|
 | `.d-block`        | `display: block`        |
 | `.d-flex`         | `display: flex`         |
@@ -105,8 +105,8 @@ Display classes aid in adapting the layout of the elements on a page:
 
 Use these classes in conjunction with the responsive modifiers.
 
-#### Examples
-{: .no_toc }
+### Applying Display Utilities with `{: }`
+{: .no_toc .text-delta }
 
 In Markdown, use the `{: }` wrapper to apply custom classes: