steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-13 13:23:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into JeffGuKang-patch-1

Browse Source
This commit is contained in:
Patrick Marsceill
2022-03-03 15:39:00 -05:00
committed by GitHub
parent 3726697fab 25aa612617
commit aae3d0309f
108 changed files with 2779 additions and 1264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
docs/configuration.md
View File

@@ -7,8 +7,7 @@ nav_order: 2
# Configuration
{: .no_toc }
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's _config.yml file.
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file.
{: .fs-6 .fw-300 }
## Table of contents
@@ -19,8 +18,7 @@ Just the Docs has some specific configuration parameters that can be defined in
---
View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example.
## Site logo
@@ -67,7 +65,7 @@ search:
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs"
- "//github.com/just-the-docs/just-the-docs"
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
@@ -86,9 +84,11 @@ heading_anchors: true
## Footer content
```yaml
# Footer content
# Footer content
# appears at the bottom of every page's main content
footer_content: "Copyright &copy; 2017-2019 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust
markup / liquid-based content.
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>"
# Footer last edited timestamp
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
@@ -97,15 +97,19 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
# 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_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
```
_note: `footer_content` is deprecated, but still supported. For a better experience we have moved this into an include called `_includes/footer_custom.html` which will allow for robust markup / liquid-based content._
- 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_branch` is the branch that the docs site is served from; defaults to `main`
- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
- `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
@@ -114,6 +118,7 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script>
@@ -140,3 +145,53 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more
ga_tracking: UA-5555555-55
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
```
## Document collections
By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
```yaml
# Define Jekyll collections
collections:
# Define a collection named "docs", its documents reside in the "_docs" directory
docs:
permalink: "/:collection/:path/"
output: true
just_the_docs:
# Define which collections are used in just-the-docs
collections:
# Reference the "docs" collection
docs:
# Give the collection a name
name: Documentation
# Exclude the collection from the navigation
# Supports true or false (default)
nav_exclude: false
# Exclude the collection from the search
# Supports true or false (default)
search_exclude: false
```
You can reference multiple collections.
This creates categories in the navigation with the configured names.
```yaml
collections:
docs:
permalink: "/:collection/:path/"
output: true
tutorials:
permalink: "/:collection/:path/"
output: true
just_the_docs:
collections:
docs:
name: Documentation
tutorials:
name: Tutorials
```

21
docs/customization.md
View File

@@ -16,6 +16,7 @@ nav_order: 6
---
## Color schemes
{: .d-inline-block }
New
@@ -32,6 +33,7 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script>
@@ -53,10 +55,10 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
### 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)
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.
Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_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:
@@ -73,6 +75,7 @@ Please use scheme files.
### Use a custom scheme
To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file:
```yaml
color_scheme: foo
```
@@ -80,7 +83,7 @@ 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:`
with the following content:
{% raw %}
---
@@ -91,7 +94,7 @@ with the following content:`
This allows you to switch the scheme via the following javascript.
```js
jtd.setTheme('foo');
jtd.setTheme("foo")
```
## Override and completely custom styles
@@ -109,7 +112,13 @@ For example, if you'd like to add your own styles for printing a page, you could
```scss
// Print-only styles.
@media print {
.side-bar, .page-header { display: none; }
.main-content { max-width: auto; margin: 1em;}
.side-bar,
.page-header {
display: none;
}
.main-content {
max-width: auto;
margin: 1em;
}
}
```

33
docs/index-test.md
View File

@@ -39,7 +39,7 @@ GitHubPages::Dependencies.gems.each do |gem, version|
end
```
#### [](#header-4)Header 4
#### [](#header-4)Header 4 `with code not transformed`
* This is an unordered list following a header.
* This is an unordered list following a header.
@@ -140,6 +140,37 @@ end
<dd>Green</dd>
</dl>
#### Multiple description terms and values
Term
: Brief description of Term
Longer Term
: Longer description of Term,
possibly more than one line
Term
: First description of Term,
possibly more than one line
: Second description of Term,
possibly more than one line
Term1
Term2
: Single description of Term1 and Term2,
possibly more than one line
Term1
Term2
: First description of Term1 and Term2,
possibly more than one line
: Second description of Term1 and Term2,
possibly more than one line
### More code
```
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
```

57
docs/navigation-structure.md
View File

@@ -5,13 +5,17 @@ nav_order: 5
---
# Navigation Structure
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
---
@@ -25,9 +29,10 @@ By default, all pages will appear as top level pages in the main nav unless a pa
## Ordering pages
To specify a page order, use the `nav_order` parameter in your pages' YAML front matter.
To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
#### Example
{: .no_toc }
```yaml
@@ -36,14 +41,16 @@ layout: default
title: Customization
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`).
The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
The parameter values can be numbers (integers, floats) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional.
> _Note for users of previous versions:_ `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.
---
@@ -52,6 +59,7 @@ when sorting strings (but also sorts numbers lexicographically: `10` comes befor
For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
#### Example
{: .no_toc }
```yaml
@@ -60,8 +68,13 @@ layout: default
title: 404
nav_exclude: true
---
```
The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
Pages with no `title` are automatically excluded from the navigation.
---
## Pages with children
@@ -96,9 +109,11 @@ Sometimes you will want to create a page with many children (a section). First,
```
On the parent pages, add this YAML front matter parameter:
- `has_children: true` (tells us that this is a parent page)
- `has_children: true` (tells us that this is a parent page)
#### Example
{: .no_toc }
```yaml
@@ -108,16 +123,19 @@ title: UI Components
nav_order: 2
has_children: true
---
```
Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav.
### Child pages
{: .text-gamma }
On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
#### Example
{: .no_toc }
```yaml
@@ -127,6 +145,7 @@ title: Buttons
parent: UI Components
nav_order: 2
---
```
The Buttons page appears as a child of UI Components and appears second in the UI Components section.
@@ -136,6 +155,7 @@ The Buttons page appears as a child of UI Components and appears second in the U
By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
#### Example
{: .no_toc }
```yaml
@@ -146,9 +166,11 @@ nav_order: 2
has_children: true
has_toc: false
---
```
### Children with children
{: .text-gamma }
Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
@@ -157,6 +179,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
1. Add the `parent` and `grand_parent` attribute to the grandchild
#### Example
{: .no_toc }
```yaml
@@ -167,6 +190,7 @@ parent: UI Components
nav_order: 2
has_children: true
---
```
```yaml
@@ -177,6 +201,7 @@ parent: Buttons
grand_parent: UI Components
nav_order: 1
---
```
This would create the following navigation structure:
@@ -202,13 +227,14 @@ This would create the following navigation structure:
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 }
```yaml
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs"
- "//github.com/just-the-docs/just-the-docs"
```
---
@@ -218,20 +244,23 @@ aux_links:
To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
#### Example
{: .no_toc }
```markdown
# Navigation Structure
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
{: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. To get an unordered list, replace `1. TOC` above by `- 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. To get an unordered list, replace `1. TOC` above by `- TOC`.
### Collapsible Table of Contents

12
docs/search.md
View File

@@ -5,13 +5,15 @@ nav_order: 7
---
# Search
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
{:toc}
---
@@ -76,7 +78,7 @@ To allow search for hyphenated words:
search.tokenizer_separator: /[\s/]+/
```
### Display URL in search results
### Display URL in search results
```yaml
# Display the relative url in search results
@@ -94,13 +96,13 @@ The search button displays in the bottom right corner of the screen and triggers
search.button: true
```
## Hiding pages from search
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
@@ -110,8 +112,8 @@ title: Page not found
nav_exclude: true
search_exclude: true
---
```
```
## Generate search index when used as a gem
@@ -124,4 +126,4 @@ $ bundle exec just-the-docs rake search:init
```
This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index.
Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/master/assets/js/zzzz-search-data.json).
Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).

22
docs/tests/index.md Normal file
View File

@@ -0,0 +1,22 @@
---
layout: default
title: Tests
has_children: true
nav_order: 100
---
# Tests
The main documentation pages of this theme illustrate the use of many of its features, which to some extent tests their implementation. The pages linked below provide further test cases for particular features, and may be useful for regression testing when developing new features.
The default configuration does not include the test pages. To include them, *commment-out* the following line in `_config.yml`:
```yaml
, "docs/tests/"
```
so that it is:
```yaml
# , "docs/tests/"
```
(Apparently Jekyll's `include` does *not* override `exclude` for the same folder...)

14
docs/tests/navigation/disambiguation/a.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: Tests for disambiguation A
has_children: true
---
# A
A top-level page
```yaml
title: Tests for disambiguation A
has_children: true
```

14
docs/tests/navigation/disambiguation/b.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: Tests for disambiguation B
has_children: true
---
# B
A top-level page
```yaml
title: Tests for disambiguation B
has_children: true
```

16
docs/tests/navigation/disambiguation/ca.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Tests for disambiguation C
parent: Tests for disambiguation A
has_children: true
---
# C
A child of page A, and parent of page D
```yaml
title: Tests for disambiguation C
parent: Tests for disambiguation A
has_children: true
```

16
docs/tests/navigation/disambiguation/cb.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Tests for disambiguation C
parent: Tests for disambiguation B
has_children: true
---
# C
A child of page B, and parent of page D
```yaml
title: Tests for disambiguation C
parent: Tests for disambiguation B
has_children: true
```

16
docs/tests/navigation/disambiguation/dca.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Tests for disambiguation D
parent: Tests for disambiguation C
grand_parent: Tests for disambiguation A
---
# D
A grandchild of page A
```yaml
title: Tests for disambiguation D
parent: Tests for disambiguation C
grand_parent: Tests for disambiguation A
```

16
docs/tests/navigation/disambiguation/dcb.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Tests for disambiguation D
parent: Tests for disambiguation C
grand_parent: Tests for disambiguation B
---
# D
A grandchild of page B
```yaml
title: Tests for disambiguation D
parent: Tests for disambiguation C
grand_parent: Tests for disambiguation B
```

14
docs/tests/navigation/disambiguation/index.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: Disambiguation
parent: Navigation
grand_parent: Tests
---
# Disambiguation
When different pages with children have the same title, referencing the relevant grandparent in the children disambiguates which page is intended.
- [Page A](a/) has a child [page with title C](ca/), and a grandchild [page with title D](dca/).
- [Page B](b/) has a child [page with title C](cb/), and a grandchild [page with title D](dcb/).
- The grandchild pages specify their parent and grandparent pages, so there is no ambiguity.

13
docs/tests/navigation/exclusion/0.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Tests for exclusion 0
has_children: true
nav_exclude: true
---
# Tests for exclusion 0
```yaml
title: Tests for exclusion 0
has_children: true
nav_exclude: true
```

15
docs/tests/navigation/exclusion/00.md Normal file
View File

@@ -0,0 +1,15 @@
---
layout: default
title: Tests for exclusion 00
parent: Tests for exclusion 0
has_children: true
nav_exclude: true
---
# Tests for exclusion 00
```yaml
title: Tests for exclusion 00
parent: Tests for exclusion 0
has_children: true
nav_exclude: true
```

17
docs/tests/navigation/exclusion/000.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 000
parent: Tests for exclusion 00
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: true
---
# Tests for exclusion 000
```yaml
title: Tests for exclusion 000
parent: Tests for exclusion 00
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: true
```

17
docs/tests/navigation/exclusion/001.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 001
parent: Tests for exclusion 00
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: false
---
# Tests for exclusion 001
```yaml
title: Tests for exclusion 001
parent: Tests for exclusion 00
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: false
```

15
docs/tests/navigation/exclusion/01.md Normal file
View File

@@ -0,0 +1,15 @@
---
layout: default
title: Tests for exclusion 01
parent: Tests for exclusion 0
has_children: true
nav_exclude: false
---
# Tests for exclusion 01
```yaml
title: Tests for exclusion 01
parent: Tests for exclusion 0
has_children: true
nav_exclude: false
```

17
docs/tests/navigation/exclusion/010.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 010
parent: Tests for exclusion 01
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: true
---
# Tests for exclusion 010
```yaml
title: Tests for exclusion 010
parent: Tests for exclusion 01
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: true
```

17
docs/tests/navigation/exclusion/011.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 011
parent: Tests for exclusion 01
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: false
---
# Tests for exclusion 011
```yaml
title: Tests for exclusion 011
parent: Tests for exclusion 01
grand_parent: Tests for exclusion 0
has_children: false
nav_exclude: false
```

13
docs/tests/navigation/exclusion/1.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Tests for exclusion 1
has_children: true
nav_exclude: false
---
# Tests for exclusion 1
```yaml
title: Tests for exclusion 1
has_children: true
nav_exclude: false
```

15
docs/tests/navigation/exclusion/10.md Normal file
View File

@@ -0,0 +1,15 @@
---
layout: default
title: Tests for exclusion 10
parent: Tests for exclusion 1
has_children: true
nav_exclude: true
---
# Tests for exclusion 10
```yaml
title: Tests for exclusion 10
parent: Tests for exclusion 1
has_children: true
nav_exclude: true
```

17
docs/tests/navigation/exclusion/100.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 100
parent: Tests for exclusion 10
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: true
---
# Tests for exclusion 100
```yaml
title: Tests for exclusion 100
parent: Tests for exclusion 10
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: true
```

17
docs/tests/navigation/exclusion/101.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 101
parent: Tests for exclusion 10
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: false
---
# Tests for exclusion 101
```yaml
title: Tests for exclusion 101
parent: Tests for exclusion 10
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: false
```

15
docs/tests/navigation/exclusion/11.md Normal file
View File

@@ -0,0 +1,15 @@
---
layout: default
title: Tests for exclusion 11
parent: Tests for exclusion 1
has_children: true
nav_exclude: false
---
# Tests for exclusion 11
```yaml
title: Tests for exclusion 11
parent: Tests for exclusion 1
has_children: true
nav_exclude: false
```

17
docs/tests/navigation/exclusion/110.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 110
parent: Tests for exclusion 11
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: true
---
# Tests for exclusion 110
```yaml
title: Tests for exclusion 110
parent: Tests for exclusion 11
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: true
```

17
docs/tests/navigation/exclusion/111.md Normal file
View File

@@ -0,0 +1,17 @@
---
layout: default
title: Tests for exclusion 111
parent: Tests for exclusion 11
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: false
---
# Tests for exclusion 111
```yaml
title: Tests for exclusion 111
parent: Tests for exclusion 11
grand_parent: Tests for exclusion 1
has_children: false
nav_exclude: false
```

11
docs/tests/navigation/exclusion/excluded.md Normal file
View File

@@ -0,0 +1,11 @@
---
layout: default
nav_exclude: true
---
# Tests for exclusion untitled and excluded
This page does not have a `title`, and it is explicitly excluded from the navigation
```yaml
nav_exclude: true
```

36
docs/tests/navigation/exclusion/index.md Normal file
View File

@@ -0,0 +1,36 @@
---
layout: default
title: Exclusion
parent: Navigation
grand_parent: Tests
---
# Exclusion
Pages excluded from the main navigation can have parents and children. Navigation to and between excluded pages can be supported by the auto-generating list of child pages inserted at the bottom of each page, and by links to parents in the breadcrumbs at the top of each page.
The following tests cover all combinations of excluded and included pages for the top level, child pages, and grandchild pages. The last binary digit in a page title indicates whether the page is included (1) or excluded (0); preceding digits refer to its parent and grandparent.
## Included in main navigation
- [Tests for exclusion 1](1/)
- [Tests for exclusion 11](11/)
- [Tests for exclusion 111](111/)
## Included only in child navigation
- [Tests for exclusion 110](110/)
- [Tests for exclusion 10](10/)
- [Tests for exclusion 101](101/)
- [Tests for exclusion 100](100/)
- [Tests for exclusion 01](01/)
- [Tests for exclusion 011](011/)
- [Tests for exclusion 010](010/)
- [Tests for exclusion 00](00/)
- [Tests for exclusion 001](001/)
- [Tests for exclusion 000](000/)
## Not included in main or child navigation
- [Tests for exclusion 0](0/)
- ["Untitled"](untitled/)

6
docs/tests/navigation/exclusion/untitled.md Normal file
View File

@@ -0,0 +1,6 @@
---
layout: default
---
# Tests for exclusion untitled
This page does not have a `title`, and it is excluded from the navigation -- unless it is located in a Jekyll collection (which provides default titles). To exclude a title-less page from the navigation, regardless of whether it is located in a collection, set `nav_exclude: true`.

8
docs/tests/navigation/index.md Normal file
View File

@@ -0,0 +1,8 @@
---
layout: default
title: Navigation
parent: Tests
has_children: true
---
# Navigation

14
docs/tests/navigation/order/default/10.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: "10"
parent: Default
grand_parent: Tests for order
---
# 10
```yaml
title: "10"
parent: Default
grand_parent: Tests for order
```

14
docs/tests/navigation/order/default/2.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: "2"
parent: Default
grand_parent: Tests for order
---
# 2
```yaml
title: "2"
parent: Default
grand_parent: Tests for order
```

14
docs/tests/navigation/order/default/a.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: A
parent: Default
grand_parent: Tests for order
---
# A
```yaml
title: A
parent: Default
grand_parent: Tests for order
```

14
docs/tests/navigation/order/default/aa-lower.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: aa
parent: Default
grand_parent: Tests for order
---
# aa
```yaml
title: aa
parent: Default
grand_parent: Tests for order
```

14
docs/tests/navigation/order/default/aa.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: Aa
parent: Default
grand_parent: Tests for order
---
# Aa
```yaml
title: Aa
parent: Default
grand_parent: Tests for order
```

15
docs/tests/navigation/order/default/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
layout: default
title: Default
parent: Tests for order
nav_order: 1
has_children: true
---
# Default Order
When `nav_order` fields are omitted, the pages are ordered alphabetically by their titles.
By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
Digits precede letters, and numeric titles are ordered lexicographically: `10` precedes `2` (in contrast to explicit numeric `nav_order` values).

16
docs/tests/navigation/order/floats/-1.1.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "-1.1"
nav_order: -1.1
parent: Floats
grand_parent: Tests for order
---
# -1.1
```yaml
title: "-1.1"
nav_order: -1.1
parent: Floats
grand_parent: Tests for order
```

16
docs/tests/navigation/order/floats/0.0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "0.0"
nav_order: 0.0
parent: Floats
grand_parent: Tests for order
---
# 0.0
```yaml
title: "0.0"
nav_order: 0.0
parent: Floats
grand_parent: Tests for order
```

16
docs/tests/navigation/order/floats/10.0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "10.0"
nav_order: 10.0
parent: Floats
grand_parent: Tests for order
---
# 10.0
```yaml
title: "10.0"
nav_order: 10.0
parent: Floats
grand_parent: Tests for order
```

16
docs/tests/navigation/order/floats/2.2222.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "2.2222"
nav_order: 2.2222
parent: Floats
grand_parent: Tests for order
---
# 2.2222
```yaml
title: "2.2222"
nav_order: 2.2222
parent: Floats
grand_parent: Tests for order
```

13
docs/tests/navigation/order/floats/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Floats
parent: Tests for order
nav_order: 4
has_children: true
---
# Floating-Point Order
When `nav_order` fields are floating-point numbers, the pages are ordered in increasing order of the numerical values.
Floats include `0.0` and negative values.

16
docs/tests/navigation/order/index.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Order
parent: Navigation
grand_parent: Tests
---
# Order
The value of `nav_order` can be numbers (integers, floats) and/or strings. The following tests illustrate their effects.
- [Default](default/), using `title` instead of `nav_order` fields.
- [Strings](strings/), lexicographically ordered, possibly case-insensitively.
- [Integers](integers/), numerically ordered.
- [Floats](floats/), numerically ordered.
- [Mixture](mixture/), with numbers before strings.

16
docs/tests/navigation/order/integers/-1.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "-1"
nav_order: -1
parent: Integers
grand_parent: Tests for order
---
# -1
```yaml
title: "-1"
nav_order: -1
parent: Integers
grand_parent: Tests for order
```

16
docs/tests/navigation/order/integers/0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "0"
nav_order: 0
parent: Integers
grand_parent: Tests for order
---
# 0
```yaml
title: "0"
nav_order: 0
parent: Integers
grand_parent: Tests for order
```

16
docs/tests/navigation/order/integers/10.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "10"
nav_order: 10
parent: Integers
grand_parent: Tests for order
---
# 10
```yaml
title: "10"
nav_order: 10
parent: Integers
grand_parent: Tests for order
```

16
docs/tests/navigation/order/integers/2.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "2"
nav_order: 2
parent: Integers
grand_parent: Tests for order
---
# 2
```yaml
title: "2"
nav_order: 2
parent: Integers
grand_parent: Tests for order
```

13
docs/tests/navigation/order/integers/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Integers
parent: Tests for order
nav_order: 3
has_children: true
---
# Integer Order
When `nav_order` fields are integers, the pages are ordered in increasing order of the numerical values.
Integers include `0` and negative values. Integers can be reused for top-level pages and for different sets of child pages.

16
docs/tests/navigation/order/mixture/-1.1.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "-1.1"
nav_order: -1.1
parent: Mixture
grand_parent: Tests for order
---
# -1.1
```yaml
title: "-1.1"
nav_order: -1.1
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/-1.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "-1"
nav_order: -1
parent: Mixture
grand_parent: Tests for order
---
# -1
```yaml
title: "-1"
nav_order: -1
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/0.0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "0.0"
nav_order: 0.0
parent: Mixture
grand_parent: Tests for order
---
# 0.0
```yaml
title: "0.0"
nav_order: 0.0
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "0"
nav_order: 0
parent: Mixture
grand_parent: Tests for order
---
# 0
```yaml
title: "0"
nav_order: 0
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/10.0.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "10.0"
nav_order: 10.0
parent: Mixture
grand_parent: Tests for order
---
# 10.0
```yaml
title: "10.0"
nav_order: 10.0
parent: Mixture
grand_parent: Tests for order
```

14
docs/tests/navigation/order/mixture/10.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: "10"
parent: Mixture
grand_parent: Tests for order
---
# 10
```yaml
title: "10"
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/2.2222.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "2.2222"
nav_order: 2.2222
parent: Mixture
grand_parent: Tests for order
---
# 2.2222
```yaml
title: "2.2222"
nav_order: 2.2222
parent: Mixture
grand_parent: Tests for order
```

14
docs/tests/navigation/order/mixture/2.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: "2"
parent: Mixture
grand_parent: Tests for order
---
# 2
```yaml
title: "2"
parent: Mixture
grand_parent: Tests for order
```

14
docs/tests/navigation/order/mixture/a.md Normal file
View File

@@ -0,0 +1,14 @@
---
layout: default
title: A
parent: Mixture
grand_parent: Tests for order
---
# A
```yaml
title: A
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/aa-lower.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: aa
nav_order: "aa"
parent: Mixture
grand_parent: Tests for order
---
# aa
```yaml
title: aa
nav_order: "aa"
parent: Mixture
grand_parent: Tests for order
```

16
docs/tests/navigation/order/mixture/aa.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Aa
nav_order: "Aa"
parent: Mixture
grand_parent: Tests for order
---
# Aa
```yaml
title: Aa
nav_order: "Aa"
parent: Mixture
grand_parent: Tests for order
```

11
docs/tests/navigation/order/mixture/index.md Normal file
View File

@@ -0,0 +1,11 @@
---
layout: default
title: Mixture
parent: Tests for order
nav_order: 5
has_children: true
---
# Mixed Order
It seems unlikely that different types of `nav_order` values are needed for the children of the same parent.

7
docs/tests/navigation/order/order.md Normal file
View File

@@ -0,0 +1,7 @@
---
layout: default
title: Tests for order
has_children: true
---
# Order

16
docs/tests/navigation/order/strings/10.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "10"
nav_order: "10"
parent: Strings
grand_parent: Tests for order
---
# 10
```yaml
title: "10"
nav_order: "10"
parent: Strings
grand_parent: Tests for order
```

16
docs/tests/navigation/order/strings/2.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: "2"
nav_order: "2"
parent: Strings
grand_parent: Tests for order
---
# 2
```yaml
title: "2"
nav_order: "2"
parent: Strings
grand_parent: Tests for order
```

16
docs/tests/navigation/order/strings/a.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: A
nav_order: A
parent: Strings
grand_parent: Tests for order
---
# A
```yaml
title: A
nav_order: A
parent: Strings
grand_parent: Tests for order
```

16
docs/tests/navigation/order/strings/aa-lower.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: aa
nav_order: "aa"
parent: Strings
grand_parent: Tests for order
---
# aa
```yaml
title: aa
nav_order: "aa"
parent: Strings
grand_parent: Tests for order
```

16
docs/tests/navigation/order/strings/aa.md Normal file
View File

@@ -0,0 +1,16 @@
---
layout: default
title: Aa
nav_order: "Aa"
parent: Strings
grand_parent: Tests for order
---
# Aa
```yaml
title: Aa
nav_order: "Aa"
parent: Strings
grand_parent: Tests for order
```

13
docs/tests/navigation/order/strings/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
layout: default
title: Strings
parent: Tests for order
nav_order: 2
has_children: true
---
# String Order
By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
Digits precede letters, and numeric titles are ordered lexicographically: `"10"` precedes `"2"` (in contrast to explicit numeric `nav_order` values).

83
docs/tests/styling/dl.md Normal file
View File

@@ -0,0 +1,83 @@
---
layout: default
title: Description lists
parent: Styling
grand_parent: Tests
---
# Description lists
The first child element of each `dd` element in a `dl` list should be aligned with the preceding `dt` element in the following examples.
term
: paragraph text
paragraph text
term
: ### Header
paragraph text
term
: > block quote
paragraph text
term
: ```sh
fenced code block
```
paragraph text
term
: + unordered list item
+ unordered list item
paragraph text
term
: 1. ordered list item
2. ordered list item
paragraph text
term
: sub-term
: sub-description
sub-term
: sub-description
paragraph text
term
: |-----------------+------------+-----------------+----------------|
| Default aligned |Left aligned| Center aligned | Right aligned |
|-----------------|:-----------|:---------------:|---------------:|
| First body part |Second cell | Third cell | fourth cell |
| Second line |foo | **strong** | baz |
| Third line |quux | baz | bar |
|-----------------+------------+-----------------+----------------|
| Second body | | | |
| 2 line | | | |
|=================+============+=================+================|
| Footer row | | | |
|-----------------+------------+-----------------+----------------|
paragraph text
term
: ***
paragraph text

8
docs/tests/styling/index.md Normal file
View File

@@ -0,0 +1,8 @@
---
layout: default
title: Styling
parent: Tests
has_children: true
---
# Styling

65
docs/tests/styling/ol.md Normal file
View File

@@ -0,0 +1,65 @@
---
layout: default
title: Ordered lists
parent: Styling
grand_parent: Tests
---
# Ordered lists
The first child element of each `li` element in an `ol` list should be aligned with the preceding label in the following examples.
1. paragraph text
paragraph text
1. ### Header
paragraph text
1. > block quote
paragraph text
1. ```sh
fenced code block
```
paragraph text
1. + unordered list item
+ unordered list item
paragraph text
1. 1. ordered list item
2. ordered list item
paragraph text
1. term
: description
term
: description
paragraph text
1. |-----------------+------------+-----------------+----------------|
| Default aligned |Left aligned| Center aligned | Right aligned |
|-----------------|:-----------|:---------------:|---------------:|
| First body part |Second cell | Third cell | fourth cell |
| Second line |foo | **strong** | baz |
| Third line |quux | baz | bar |
|-----------------+------------+-----------------+----------------|
| Second body | | | |
| 2 line | | | |
|=================+============+=================+================|
| Footer row | | | |
|-----------------+------------+-----------------+----------------|
paragraph text
1. ***
paragraph text

65
docs/tests/styling/ul.md Normal file
View File

@@ -0,0 +1,65 @@
---
layout: default
title: Unordered lists
parent: Styling
grand_parent: Tests
---
# Unordered lists
The first child element of each `li` element in a `ul` list should be aligned with the preceding bullet in the following examples.
- paragraph text
paragraph text
- ### Header
paragraph text
- > block quote
paragraph text
- ```sh
fenced code block
```
paragraph text
- + unordered list item
+ unordered list item
paragraph text
- 1. ordered list item
2. ordered list item
paragraph text
- term
: description
term
: description
paragraph text
- |-----------------+------------+-----------------+----------------|
| Default aligned |Left aligned| Center aligned | Right aligned |
|-----------------|:-----------|:---------------:|---------------:|
| First body part |Second cell | Third cell | fourth cell |
| Second line |foo | **strong** | baz |
| Third line |quux | baz | bar |
|-----------------+------------+-----------------+----------------|
| Second body | | | |
| 2 line | | | |
|=================+============+=================+================|
| Footer row | | | |
|-----------------+------------+-----------------+----------------|
paragraph text
- ***
paragraph text

1
docs/ui-components/code.md
View File

@@ -2,6 +2,7 @@
layout: default
title: Code
parent: UI Components
has_children: true
nav_order: 6
---

115
docs/ui-components/line-nos.md Normal file
View File

@@ -0,0 +1,115 @@
---
layout: default
title: Code with line numbers
parent: Code
grand_parent: UI Components
permalink: /docs/ui-components/code/line-numbers/
---
# Code snippets with line numbers
The default settings for HTML compression are incompatible with the HTML
produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
-- both when using Kramdown code fences and when using Liquid highlight tags.
To avoid non-conforming HTML and unsatisfactory layout, HTML compression
can be turned off by using the following configuration option:
{% highlight yaml %}
compress_html:
ignore:
envs: all
{% endhighlight %}
When using Kramdown code fences, line numbers are turned on globally by the
following configuration option:
{% highlight yaml %}
kramdown:
syntax_highlighter_opts:
block:
line_numbers: true
{% endhighlight %}
Line numbers can then be suppressed locally using Liquid tags (_without_ the
`linenos` option) instead of fences:
{% highlight yaml %}
{% raw %}{% highlight some_language %}
Some code
{% endhighlight %}{% endraw %}
{% endhighlight %}
## Workarounds
To use HTML compression together with line numbers, all highlighted code
needs to be wrapped using one of the following workarounds.
(The variable name `some_var` can be changed to avoid clashes; it can also
be replaced by `code` -- but note that `code=code` cannot be removed).
### Code fences (three backticks)
{% highlight default %}
{% raw %}{% capture some_var %}
```some_language
Some code
```
{% endcapture %}
{% assign some_var = some_var | markdownify %}
{% include fix_linenos.html code=some_var %}{% endraw %}
{% endhighlight %}
### Liquid highlighting
{% highlight default %}
{% raw %}{% capture some_var %}
{% highlight some_language linenos %}
Some code
{% endhighlight %}
{% endcapture %}
{% include fix_linenos.html code=some_var %}{% endraw %}
{% endhighlight %}
_Credit:_ The original version of the above workaround was suggested by
Dmitry Hrabrov at
<https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901>.
## Examples
✅ Using code fences + workaround (will only show line numbers if enabled globally in `_config.yml`):
{% capture code_fence %}
```js
// Javascript code with syntax highlighting in fences
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l)
return true;
}
```
{% endcapture %}
{% assign code_fence = code_fence | markdownify %}
{% include fix_linenos.html code=code_fence %}
✅ Using liquid highlighting + workaround:
{% capture code %}
{% highlight ruby linenos %}
# Ruby code with syntax highlighting and fixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
{% endhighlight %}
{% endcapture %}
{% include fix_linenos.html code=code %}
{% assign code = nil %}
❌ With the default configuration options, the following example illustrates
the **incorrect** formatting arising from the incompatibility of HTML compression
and the non-conforming HTML produced by Jekyll for line numbers:
{% highlight ruby linenos %}
# Ruby code with syntax highlighting and unfixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
{% endhighlight %}

2
docs/ui-components/typography.md
View File

@@ -21,7 +21,7 @@ nav_order: 1
By default, Just the Docs uses a native system font stack for sans-serif fonts:
```scss
-apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif
system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
```
ABCDEFGHIJKLMNOPQRSTUVWXYZ