Add files
This commit is contained in:
@@ -0,0 +1,339 @@
|
||||
<!-- ---
|
||||
title: Configuration
|
||||
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.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
```yaml
|
||||
# Set a path/url to a logo that will be displayed instead of the title
|
||||
logo: "/assets/images/just-the-docs.png"
|
||||
```
|
||||
|
||||
## Site favicon
|
||||
|
||||
```yaml
|
||||
# Set a path/url to a favicon that will be displayed by the browser
|
||||
favicon_ico: "/assets/images/favicon.ico"
|
||||
```
|
||||
|
||||
If the path to your favicon is `/favicon.ico`, you can leave `favicon_ico` unset.
|
||||
|
||||
## Search
|
||||
|
||||
```yaml
|
||||
# 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: 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
|
||||
# Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
|
||||
focus_shortcut_key: 'k'
|
||||
```
|
||||
|
||||
## Mermaid Diagrams
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`:
|
||||
|
||||
```yaml
|
||||
mermaid:
|
||||
# Version of mermaid library
|
||||
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
|
||||
version: "9.1.3"
|
||||
```
|
||||
|
||||
Provide a `path` instead of a `version` key to load the mermaid library from a local file.
|
||||
|
||||
See [the Code documentation]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
|
||||
|
||||
## Aux links
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
```
|
||||
|
||||
## Navigation sidebar
|
||||
|
||||
```yaml
|
||||
# Enable or disable the side/mobile menu globally
|
||||
# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout
|
||||
nav_enabled: true
|
||||
```
|
||||
|
||||
## Heading anchor links
|
||||
|
||||
```yaml
|
||||
# Heading anchor links appear on hover over h1-h6 tags in page content
|
||||
# allowing users to deep link to a particular heading on a page.
|
||||
#
|
||||
# Supports true (default) or false
|
||||
heading_anchors: true
|
||||
```
|
||||
|
||||
## External navigation links
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
External links can be added to the navigation through the `nav_external_links` option.
|
||||
See [Navigation Structure]({% link docs/navigation/main/external.md %}) for more details.
|
||||
|
||||
## Footer content
|
||||
|
||||
```yaml
|
||||
# Footer content
|
||||
# appears at the bottom of every page's main content
|
||||
# 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 © 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
|
||||
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
|
||||
```
|
||||
|
||||
_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; for examples and information, please refer to the [official Ruby docs on `strftime` formatting](https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html)
|
||||
- `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 `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
|
||||
|
||||
```yaml
|
||||
# Color scheme supports "light" (default) and "dark"
|
||||
color_scheme: dark
|
||||
```
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
|
||||
|
||||
jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
if (jtd.getTheme() === 'dark') {
|
||||
jtd.setTheme('light');
|
||||
toggleDarkMode.textContent = 'Preview dark color scheme';
|
||||
} else {
|
||||
jtd.setTheme('dark');
|
||||
toggleDarkMode.textContent = 'Return to the light side';
|
||||
}
|
||||
});
|
||||
</script>
|
||||
|
||||
See [Customization]({% link docs/customization.md %}) for more information.
|
||||
|
||||
## Callouts
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:
|
||||
|
||||
```yaml
|
||||
callouts:
|
||||
warning:
|
||||
title: Warning
|
||||
color: red
|
||||
```
|
||||
|
||||
This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this:
|
||||
|
||||
```markdown
|
||||
{: .warning }
|
||||
A paragraph...
|
||||
```
|
||||
|
||||
[^dark]:
|
||||
If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
|
||||
|
||||
The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file:
|
||||
|
||||
```scss
|
||||
$pink-000: #f77ef1;
|
||||
$pink-100: #f967f1;
|
||||
$pink-200: #e94ee1;
|
||||
$pink-300: #dd2cd4;
|
||||
```
|
||||
|
||||
You can override the default `opacity` of the background for a particular callout, e.g.:
|
||||
|
||||
```yaml
|
||||
callouts:
|
||||
custom:
|
||||
color: pink
|
||||
opacity: 0.3
|
||||
```
|
||||
|
||||
You can change the default opacity (`0.2`) for all callouts, e.g.:
|
||||
|
||||
```yaml
|
||||
callouts_opacity: 0.3
|
||||
```
|
||||
|
||||
You can also adjust the overall level of callouts.
|
||||
The value of `callouts_level` is either `quiet` or `loud`;
|
||||
`loud` increases the saturation and lightness of the backgrounds.
|
||||
The default level is `quiet` when using the `light` or custom color schemes,
|
||||
and `loud` when using the `dark color scheme.`
|
||||
|
||||
See [Callouts]({% link docs/ui-components/callouts.md %}) for more information.
|
||||
|
||||
## Google Analytics
|
||||
|
||||
{: .warning }
|
||||
> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4.
|
||||
|
||||
Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported.
|
||||
|
||||
```yaml
|
||||
# Google Analytics Tracking (optional)
|
||||
# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
|
||||
ga_tracking: UA-2709176-10
|
||||
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
|
||||
```
|
||||
|
||||
### Multiple IDs
|
||||
{: .d-inline-block .no_toc }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while.
|
||||
|
||||
```yaml
|
||||
ga_tracking: "UA-1234567-89,G-1AB234CDE5"
|
||||
```
|
||||
|
||||
## Document collections
|
||||
|
||||
By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
|
||||
You can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
|
||||
|
||||
{: .warning }
|
||||
> Collection folders always start with an underscore (`_`), e.g. `_tests`. You won't see your collections if you omit the prefix.
|
||||
|
||||
For example, put all your test files in the `_tests` folder and create the `tests` collection:
|
||||
|
||||
```yaml
|
||||
# Define Jekyll collections
|
||||
collections:
|
||||
# Define a collection named "tests", its documents reside in the "_tests" directory
|
||||
tests:
|
||||
permalink: "/:collection/:path/"
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
# Define which collections are used in just-the-docs
|
||||
collections:
|
||||
# Reference the "tests" collection
|
||||
tests:
|
||||
# Give the collection a name
|
||||
name: Tests
|
||||
# Exclude the collection from the navigation
|
||||
# Supports true or false (default)
|
||||
# nav_exclude: true
|
||||
# Fold the collection in the navigation
|
||||
# Supports true or false (default)
|
||||
# nav_fold: true # note: this option is new in v0.4
|
||||
# Exclude the collection from the search
|
||||
# Supports true or false (default)
|
||||
# search_exclude: true
|
||||
```
|
||||
|
||||
The navigation for all your normal pages (if any) is displayed before those in collections.
|
||||
|
||||
<span>New (v0.4.0)</span>{: .label .label-green }
|
||||
Including `nav_fold: true` in a collection configuration *folds* that collection:
|
||||
an expander symbol appears next to the collection name,
|
||||
and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled]
|
||||
|
||||
[^js-disabled]: <span>New (v0.6.0)</span>{: .label .label-green }
|
||||
When JavaScript is disabled in the browser, all folded collections are automatically expanded,
|
||||
since clicking expander symbols has no effect.
|
||||
(In previous releases, navigation into folded collections required JavaScript to be enabled.)
|
||||
|
||||
You can reference multiple collections.
|
||||
This creates categories in the navigation with the configured names.
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
tests:
|
||||
permalink: "/:collection/:path/"
|
||||
output: true
|
||||
tutorials:
|
||||
permalink: "/:collection/:path/"
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
collections:
|
||||
tests:
|
||||
name: Tests
|
||||
tutorials:
|
||||
name: Tutorials
|
||||
```
|
||||
|
||||
When *all* your pages are in a single collection, its name is not displayed.
|
||||
|
||||
The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page. -->
|
||||
@@ -0,0 +1,371 @@
|
||||
<!-- ---
|
||||
title: Customization
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# Customization
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Color schemes
|
||||
|
||||
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: preview dark color scheme
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```yaml
|
||||
# Color scheme supports "light" (default) and "dark"
|
||||
color_scheme: dark
|
||||
```
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
|
||||
|
||||
jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
if (jtd.getTheme() === 'dark') {
|
||||
jtd.setTheme('light');
|
||||
toggleDarkMode.textContent = 'Preview dark color scheme';
|
||||
} else {
|
||||
jtd.setTheme('dark');
|
||||
toggleDarkMode.textContent = 'Return to the light side';
|
||||
}
|
||||
});
|
||||
</script>
|
||||
|
||||
### deprecated: `legacy_light`
|
||||
{: .d-inline-block .no_toc }
|
||||
|
||||
New (v0.4.2)
|
||||
{: .label .label-green }
|
||||
|
||||
|
||||
In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
|
||||
|
||||
## Custom schemes
|
||||
|
||||
### 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.
|
||||
|
||||
{: .note }
|
||||
Since the default color scheme is `light`, your custom scheme is implicitly based on the variable settings used by the `light` scheme.
|
||||
|
||||
If you want your custom scheme to be based on the `dark` scheme, you need to start your file with the following line:
|
||||
|
||||
```scss
|
||||
@import "./color_schemes/dark";
|
||||
```
|
||||
|
||||
You can define custom schemes based on other custom schemes in the same way.
|
||||
|
||||
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:
|
||||
|
||||
#### Example: custom link color
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```scss
|
||||
$link-color: $blue-000;
|
||||
```
|
||||
|
||||
Keep in mind that changing a variable will not automatically change the value of other variables that depend on it.
|
||||
For example, the default link color (`$link-color`) is set to `$purple-000`. However, redefining `$purple-000` in a custom color scheme will not automatically change `$link-color` to match it.
|
||||
Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from `_variables.scss` — in this case, rewriting `$link-color: $purple-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.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 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 define new variables
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
To define new SCSS variables or functions, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section) or overriding color scheme variables (in this case, you should create a new color scheme).
|
||||
|
||||
This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example,
|
||||
|
||||
```scss
|
||||
// _sass/custom/setup.scss
|
||||
$pink-000: #f77ef1;
|
||||
$pink-100: #f967f1;
|
||||
$pink-200: #e94ee1;
|
||||
$pink-300: #dd2cd4;
|
||||
```
|
||||
|
||||
In particular: this file is imported *after* the theme's variables and functions are defined, but *before* any CSS classes are emitted.
|
||||
|
||||
## Override and completely custom styles
|
||||
|
||||
For styles that aren't defined as SCSS 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.
|
||||
|
||||
### Example: custom print styles
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
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.
|
||||
@media print {
|
||||
.side-bar,
|
||||
.page-header {
|
||||
display: none;
|
||||
}
|
||||
.main-content {
|
||||
max-width: auto;
|
||||
margin: 1em;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Override includes
|
||||
|
||||
You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides.
|
||||
|
||||
To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
|
||||
|
||||
Just the Docs provides the following custom includes files:
|
||||
|
||||
### Custom TOC Heading
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
`_includes/toc_heading_custom.html`
|
||||
|
||||
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: changing TOC heading
|
||||
{: .no_toc }
|
||||
|
||||
To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
|
||||
```html
|
||||
<h2 class="text-delta">Contents</h2>
|
||||
```
|
||||
|
||||
The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} .
|
||||
|
||||
### Custom Footer
|
||||
|
||||
`_includes/footer_custom.html`
|
||||
|
||||
This content appears at the bottom of every page's main content. More info for this include can be found in the [Configuration - Footer content]({% link docs/configuration.md %}#footer-content).
|
||||
|
||||
### Custom Head
|
||||
|
||||
`_includes/head_custom.html`
|
||||
|
||||
Any HTML added to this file will be inserted before the closing `<head>` tag. This might include additional `<meta>`, `<link>`, or `<script>` tags.
|
||||
|
||||
The `<head>` tag automatically includes a link to an existing favicon if you set `favicon_ico` to the corresponding path in your configuration, or if the path to the favicon is `/favicon.ico`.
|
||||
|
||||
### Custom Header
|
||||
|
||||
`_includes/header_custom.html`
|
||||
|
||||
Content added to this file appears at the top of every page's main content between the site search and auxiliary links if they are enabled. If `search_enabled` were set to false and `aux_links` were removed, the content of `header_custom.html` would occupy the space at the top of every page.
|
||||
|
||||
### Custom Nav Footer
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
`_includes/nav_footer_custom.html`
|
||||
|
||||
Any content added to this file will appear at the bottom left of the page below the site's navigation. By default an attribution to Just the Docs is displayed which reads, `This site uses Just the Docs, a documentation theme for Jekyll.`.
|
||||
|
||||
### Custom Search Placeholder
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
`_includes/search_placeholder_custom.html`
|
||||
|
||||
Content added to this file will replace the default placeholder text in the search bar (and its `aria-label`), after stripping HTML and leading/trailing whitespace. By default, the content of the include is:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```liquid
|
||||
Search {{site.title}}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Override this file to render a custom placeholder. One common use-case is internationalization; for example,
|
||||
|
||||
{% raw %}
|
||||
|
||||
```liquid
|
||||
Chercher notre site
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
would make the placeholder text "Chercher notre site". [Liquid code](https://jekyllrb.com/docs/liquid/) (including [Jekyll variables](https://jekyllrb.com/docs/variables/)) is also supported.
|
||||
|
||||
## Custom layouts and includes
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
Advanced
|
||||
{: .label .label-yellow }
|
||||
|
||||
Just the Docs uses Jekyll's powerful [layouts](https://jekyllrb.com/docs/layouts/) and [includes](https://jekyllrb.com/docs/includes/) features to generate and compose various elements of the site. Jekyll users and developers can extend or replace existing layouts and includes to customize the entire site layout.
|
||||
|
||||
### Default layout and includable components
|
||||
|
||||
The `default` layout is inherited by most of the "out-of-the-box" pages provided by Just the Docs. It composes various re-usable components of the site, including the sidebar, navbar, footer, breadcrumbs, and various imports. Most users who create new pages or layouts will inherit from `default`.
|
||||
|
||||
Here is a simplified code example of what it looks like:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```liquid
|
||||
<!-- a simplified version of _layouts/default.html
|
||||
<html>
|
||||
{% include head.html %}
|
||||
<body>
|
||||
{% include icons/icons.html %}
|
||||
{% include components/sidebar.html %}
|
||||
{% include components/header.html %}
|
||||
{% include components/breadcrumbs.html %}
|
||||
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content ... %}
|
||||
{% else %}
|
||||
{{ content }}
|
||||
{% endif %}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
{% include components/children_nav.html %}
|
||||
{% endif %}
|
||||
|
||||
{% include components/footer.html %}
|
||||
|
||||
{% if site.search_enabled != false %}
|
||||
{% include components/search_footer.html %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.mermaid %}
|
||||
{% include components/mermaid.html %}
|
||||
{% endif %}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
#### Component summary
|
||||
{: .no_toc }
|
||||
|
||||
{: .warning }
|
||||
Defining a new `_includes` with the same name as any of these components will significantly change the existing layout. Please proceed with caution when adjusting them.
|
||||
|
||||
To briefly summarize each component:
|
||||
|
||||
- `_includes/head.html` is the entire `<head>` tag for the site; this imports stylesheets, various JavaScript files (ex: analytics, mermaid, search, and Just the Docs code), and SEO / meta information.
|
||||
- `_includes/icons/icons.html` imports all SVG icons that are used throughout the site. Some, such as those relating to search or code snippet copying, are only loaded when those features are enabled.
|
||||
- `_includes/components/sidebar.html` renders the sidebar, containing the site header, navigation links, external links, collections, and nav footer.
|
||||
- `_includes/components/header.html` renders the navigation header, containing the search bar, custom header, and aux links
|
||||
- `_includes/components/breadcrumbs.html` renders the breadcrumbs feature
|
||||
- `vendor/anchor_headings.html` is a local copy of Vladimir Jimenez's [jekyll-anchor-headings](https://github.com/allejo/jekyll-anchor-headings) snippet
|
||||
- `_includes/components/children_nav.html` renders a list of nav links to child pages on parent pages
|
||||
- `_includes/components/footer.html` renders the bottom-of-page footer
|
||||
- `_includes/components/search_footer.html` renders DOM elements that are necessary for the search bar to work
|
||||
- `_includes/components/mermaid.html` initializes mermaid if the feature is enabled
|
||||
|
||||
Each of these components can be overridden individually using the same process described in the [Override includes](#override-includes) section. In particular, the granularity of components should allow users to replace certain components (such as the sidebar) without having to adjust the rest of the code.
|
||||
|
||||
Future versions may subdivide components further; we guarantee that we will only place them in folders (ex `components/`, `icons/`, or a new `js/`) to avoid top-level namespace collisions.
|
||||
|
||||
### Alternative layouts and example (`minimal`)
|
||||
|
||||
Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, which disables the navigation sidebar. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
|
||||
|
||||
Users can indicate this alternative layout in page front matter:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
---
|
||||
layout: minimal
|
||||
title: Minimal layout test
|
||||
---
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Similarly, users and developers can create other alternative layouts using Just the Docs' reusable includable components.
|
||||
|
||||
### Default layout and inheritance chain
|
||||
|
||||
Under the hood,
|
||||
|
||||
- `default` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
|
||||
- `table_wrappers` inherits from `vendor/compress`, which is a local copy of Anatol Broder's [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) Jekyll plugin
|
||||
|
||||
The `minimal` layout inherits from the `default` but assigns `nav_enabled: false` to disable the navigation sidebar.
|
||||
|
||||
### Overridden default Jekyll layouts
|
||||
|
||||
By default, Jekyll (and its default theme `minima`) provide the `about`, `home`, `page`, and `post` layouts. In Just the Docs, we override all of these layouts with the `default` layout. Each of those layouts is simply:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
{{ content }}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
@@ -0,0 +1,327 @@
|
||||
<!-- ---
|
||||
title: Markdown kitchen sink
|
||||
nav_order: 99
|
||||
---
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
|
||||
|
||||
jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
if (jtd.getTheme() === 'dark') {
|
||||
jtd.setTheme('light');
|
||||
toggleDarkMode.textContent = 'Preview dark color scheme';
|
||||
} else {
|
||||
jtd.setTheme('dark');
|
||||
toggleDarkMode.textContent = 'Return to the light side';
|
||||
}
|
||||
});
|
||||
</script>
|
||||
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
> 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
|
||||
|
||||
```js
|
||||
// Javascript code with syntax highlighting.
|
||||
var fun = function lang(l) {
|
||||
dateformat.i18n = require('./lang/' + l)
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
```ruby
|
||||
# Ruby code with syntax highlighting
|
||||
GitHubPages::Dependencies.gems.each do |gem, version|
|
||||
s.add_dependency(gem, "= #{version}")
|
||||
end
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
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
|
||||
|
||||
[This is a very long link which wraps and therefore doesn't overflow
|
||||
even when it comes at the beginning](.) of the line.
|
||||
|
||||
- [This is a very long link which wraps and therefore doesn't overflow the line
|
||||
when used first in an item ](.) in a list.
|
||||
|
||||
| head1 | head two | three |
|
||||
|:-------------|:------------------|:------|
|
||||
| ok | good swedish fish | nice |
|
||||
| out of stock | good and plenty | nice |
|
||||
| ok | good `oreos` | hmm |
|
||||
| ok | good `zoute` drop | yumm |
|
||||
|
||||
### There's a horizontal rule below this.
|
||||
|
||||
* * *
|
||||
|
||||
### Here is an unordered list:
|
||||
|
||||
* Item foo
|
||||
* Item bar
|
||||
* Item baz
|
||||
* Item zip
|
||||
|
||||
### And an ordered list:
|
||||
|
||||
1. Item one
|
||||
1. Item two
|
||||
1. Item three
|
||||
1. Item four
|
||||
|
||||
### And an ordered list, continued:
|
||||
|
||||
1. Item one
|
||||
1. Item two
|
||||
|
||||
Some text
|
||||
|
||||
{:style="counter-reset:none"}
|
||||
1. Item three
|
||||
1. Item four
|
||||
|
||||
### And an ordered list starting from 42:
|
||||
|
||||
{:style="counter-reset:step-counter 41"}
|
||||
1. Item 42
|
||||
1. Item 43
|
||||
1. Item 44
|
||||
|
||||
### And a nested list:
|
||||
|
||||
- level 1 item
|
||||
- level 2 item
|
||||
- level 2 item
|
||||
- level 3 item
|
||||
- level 3 item
|
||||
- level 1 item
|
||||
- level 2 item
|
||||
- level 2 item
|
||||
- level 2 item
|
||||
- level 1 item
|
||||
- level 2 item
|
||||
- level 2 item
|
||||
- level 1 item
|
||||
|
||||
### Nesting an ol in ul in an ol
|
||||
|
||||
- level 1 item (ul)
|
||||
1. level 2 item (ol)
|
||||
1. level 2 item (ol)
|
||||
- level 3 item (ul)
|
||||
- level 3 item (ul)
|
||||
- level 1 item (ul)
|
||||
1. level 2 item (ol)
|
||||
1. level 2 item (ol)
|
||||
- level 3 item (ul)
|
||||
- level 3 item (ul)
|
||||
1. level 4 item (ol)
|
||||
1. level 4 item (ol)
|
||||
- level 3 item (ul)
|
||||
- level 3 item (ul)
|
||||
- level 1 item (ul)
|
||||
|
||||
### And a task list
|
||||
|
||||
- [ ] Hello, this is a TODO item
|
||||
- [ ] Hello, this is another TODO item
|
||||
- [x] Goodbye, this item is done
|
||||
|
||||
### Nesting task lists
|
||||
|
||||
- [ ] level 1 item (task)
|
||||
- [ ] level 2 item (task)
|
||||
- [ ] level 2 item (task)
|
||||
- [ ] level 1 item (task)
|
||||
- [ ] level 1 item (task)
|
||||
|
||||
### Nesting a ul in a task list
|
||||
|
||||
- [ ] level 1 item (task)
|
||||
- level 2 item (ul)
|
||||
- level 2 item (ul)
|
||||
- [ ] level 1 item (task)
|
||||
- [ ] level 1 item (task)
|
||||
|
||||
### Nesting a task list in a ul
|
||||
|
||||
- level 1 item (ul)
|
||||
- [ ] level 2 item (task)
|
||||
- [ ] level 2 item (task)
|
||||
- level 1 item (ul)
|
||||
- level 1 item (ul)
|
||||
|
||||
### Small image
|
||||
|
||||
|
||||
|
||||
### Large image
|
||||
|
||||
|
||||
|
||||
"[Wroclaw University Library digitizing rare archival texts](https://www.flickr.com/photos/97810305@N08/9401451269)" by [j_cadmus](https://www.flickr.com/photos/97810305@N08) is marked with [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/?ref=openverse).
|
||||
|
||||
### Labels
|
||||
|
||||
I'm a label
|
||||
{: .label }
|
||||
|
||||
blue
|
||||
{: .label .label-blue }
|
||||
green
|
||||
{: .label .label-green }
|
||||
purple
|
||||
{: .label .label-purple }
|
||||
yellow
|
||||
{: .label .label-yellow }
|
||||
red
|
||||
{: .label .label-red }
|
||||
|
||||
**bold**
|
||||
{: .label }
|
||||
*italic*
|
||||
{: .label }
|
||||
***bold + italic***
|
||||
{: .label }
|
||||
|
||||
### Definition lists can be used with HTML syntax.
|
||||
|
||||
<dl>
|
||||
<dt>Name</dt>
|
||||
<dd>Godzilla</dd>
|
||||
<dt>Born</dt>
|
||||
<dd>1952</dd>
|
||||
<dt>Birthplace</dt>
|
||||
<dd>Japan</dd>
|
||||
<dt>Color</dt>
|
||||
<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
|
||||
|
||||
```python{% raw %}
|
||||
def dump_args(func):
|
||||
"This decorator dumps out the arguments passed to a function before calling it"
|
||||
argnames = func.func_code.co_varnames[:func.func_code.co_argcount]
|
||||
fname = func.func_name
|
||||
def echo_func(*args,**kwargs):
|
||||
print fname, ":", ', '.join(
|
||||
'%s=%r' % entry
|
||||
for entry in zip(argnames,args) + kwargs.items())
|
||||
return func(*args, **kwargs)
|
||||
return echo_func
|
||||
|
||||
@dump_args
|
||||
def f1(a,b,c):
|
||||
print a + b + c
|
||||
|
||||
f1(1, 2, 3)
|
||||
|
||||
def precondition(precondition, use_conditions=DEFAULT_ON):
|
||||
return conditions(precondition, None, use_conditions)
|
||||
|
||||
def postcondition(postcondition, use_conditions=DEFAULT_ON):
|
||||
return conditions(None, postcondition, use_conditions)
|
||||
|
||||
class conditions(object):
|
||||
__slots__ = ('__precondition', '__postcondition')
|
||||
|
||||
def __init__(self, pre, post, use_conditions=DEFAULT_ON):
|
||||
if not use_conditions:
|
||||
pre, post = None, None
|
||||
|
||||
self.__precondition = pre
|
||||
self.__postcondition = post
|
||||
{% endraw %}```
|
||||
|
||||
```
|
||||
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.
|
||||
```
|
||||
|
||||
### Mermaid Diagrams
|
||||
|
||||
The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`.
|
||||
|
||||
```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;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
### Collapsed Section
|
||||
|
||||
The following uses the [`<details>`](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) tag to create a collapsed section.
|
||||
|
||||
<details markdown="block">
|
||||
<summary>Shopping list (click me!)</summary>
|
||||
|
||||
This is content inside a `<details>` dropdown.
|
||||
|
||||
- [ ] Apples
|
||||
- [ ] Oranges
|
||||
- [ ] Milk
|
||||
|
||||
</details> -->
|
||||
@@ -0,0 +1,52 @@
|
||||
<!-- ---
|
||||
title: Layout
|
||||
layout: default
|
||||
nav_order: 5.5
|
||||
---
|
||||
|
||||
# Layout
|
||||
|
||||
You specify the layout for a page in its [front matter]. Just the Docs has a `default` layout with a sidebar, used for almost all pages in the theme docs, and a `minimal` layout that omits the sidebar.
|
||||
{: .fs-5 .fw-300 }
|
||||
|
||||
## The layout concept
|
||||
|
||||
See the [Jekyll docs page about layouts] for an explanation of the general idea of layouts and how to specify them.
|
||||
|
||||
You can use [Jekyll's front matter defaults] to specify the same layout for many pages.
|
||||
|
||||
## The `default` layout
|
||||
|
||||
This page uses the default layout. This site configures `layout: default` as a [front matter default](https://jekyllrb.com/docs/configuration/front-matter-defaults/) value for all pages in the `docs` directory.
|
||||
|
||||
The default layout of Just the Docs is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
|
||||
|
||||
All pages except top-level pages automatically have a list of so-called *breadcrumbs*: links to their parent pages and any higher-level ancestors. They show the breadcrumbs above the main content of the page.
|
||||
|
||||
Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content.
|
||||
|
||||
## The `minimal` layout
|
||||
|
||||
A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar---and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
|
||||
|
||||
## Selectively hiding or showing the sidebar
|
||||
|
||||
[Jekyll's front matter defaults] can be used to apply the `minimal` layout for many pages. But there are also other variables that can control the page layout. In `_config.yml`, you can set `nav_enabled: false` to disable the sidebar navigation panel across the entire site. This can then be selectively enabled on a page-by-page basis by assigning the `nav_enabled: true` page [front matter] variable. For instance, this could be used to enable sidebar navigation on a home page while all other pages have sidebar navigation disabled.
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
nav_enabled: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
## Other layouts
|
||||
|
||||
Just the Docs has further layouts: `about`, `home`, `page`, and `post`. Currently, they are all based on the `default` layout. See the [Jekyll docs about inheritance] for how to customize them.
|
||||
|
||||
[front matter]: https://jekyllrb.com/docs/front-matter/ "Jekyll docs about front matter"
|
||||
[Jekyll docs page about layouts]: https://jekyllrb.com/docs/layouts/ "Jekyll docs about layouts"
|
||||
[Jekyll's front matter defaults]: https://jekyllrb.com/docs/configuration/front-matter-defaults/ "Jekyll docs about front matter defaults"
|
||||
[Jekyll docs about inheritance]: https://jekyllrb.com/docs/layouts/#inheritance "Jekyll docs about inheritance" -->
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Default layout child page
|
||||
layout: default
|
||||
parent: A minimal layout page
|
||||
grand_parent: Layout
|
||||
---
|
||||
|
||||
# Default layout child page
|
||||
|
||||
This is a child page that uses the `default` layout as compared to its parent page (which uses the `minimal` layout).
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Minimal layout child page
|
||||
layout: minimal
|
||||
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.
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: A minimal layout page
|
||||
layout: minimal
|
||||
parent: Layout
|
||||
---
|
||||
|
||||
# A minimal layout page
|
||||
|
||||
This page illustrates the built-in layout `minimal`.
|
||||
|
||||
One of its child pages also uses the minimal layout; the other child pages uses the default layout.
|
||||
@@ -0,0 +1,11 @@
|
||||
<!-- ---
|
||||
layout: minimal
|
||||
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. -->
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Auxiliary Links
|
||||
parent: Navigation
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# Auxiliary Links
|
||||
|
||||
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 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:
|
||||
Just the Docs on GitHub:
|
||||
- https://github.com/just-the-docs/just-the-docs
|
||||
```
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Child Pages
|
||||
parent: Navigation
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Child Pages
|
||||
|
||||
By default, all parent pages will automatically have a so-called 'Table of Contents' at the bottom, showing links to all their child pages.
|
||||
|
||||
To disable this automatic list, set `has_toc: false` in the parent page's front matter.
|
||||
|
||||
## Example: disabling table of contents
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: UI Components
|
||||
nav_order: 3
|
||||
has_toc: false
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: In-Page Navigation
|
||||
parent: Navigation
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# In-Page Navigation
|
||||
{: .no_toc }
|
||||
|
||||
## Table of Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
{: .note }
|
||||
`{:toc}` can be used only once on each page.
|
||||
|
||||
You **must** have a list immediately preceding the table of contents. The type of list determines the style of your table of contents.
|
||||
|
||||
For an *ordered* table of contents, use the following markdown code:
|
||||
|
||||
```md
|
||||
1. TOC
|
||||
{:toc}
|
||||
```
|
||||
|
||||
The `{:toc}` line *must* follow the `1. TOC` line, which begins a list.
|
||||
|
||||
For an *unordered* table of contents, instead use the following markdown code:
|
||||
|
||||
```
|
||||
- TOC
|
||||
{:toc}
|
||||
```
|
||||
|
||||
## Omitting Heading from Table of Contents
|
||||
|
||||
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
|
||||
{: .no_toc }
|
||||
|
||||
## Table of Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
```
|
||||
|
||||
This example omits the top-level heading (`In-Page Navigation`) from the TOC, as well as the heading for the *Table of Contents* itself.
|
||||
|
||||
## Collapsible Table of Contents (with `<details>` and `<summary>`)
|
||||
|
||||
You can make the Table of Contents collapsible using the `<details>` and `<summary>` elements, as in the following example.
|
||||
|
||||
```markdown
|
||||
<details open markdown="block">
|
||||
<summary>
|
||||
Table of contents
|
||||
</summary>
|
||||
{: .text-delta }
|
||||
1. TOC
|
||||
{:toc}
|
||||
</details>
|
||||
```
|
||||
|
||||
The attribute `open` (which expands the Table of Contents by default) and the styling (here with `text-delta`) are optional.
|
||||
|
||||
## Back to Top {#back-to-top-doc}
|
||||
|
||||
{: .warning }
|
||||
The default id for a section with heading "Back to Top" is `"back-to-top"`.
|
||||
To avoid invalid HTML, sites that set the `back_to_top` configuration variable
|
||||
should override the default id for such sections. The Markdown source file for
|
||||
the current page uses `## Back to Top {#back-to-top-doc}`.
|
||||
|
||||
You can add a link from the bottom of each page to its top. You do this by including the `back_to_top` configuration option in your site's `_config.yml` file, together with `back_to_top_text` for the anchor link.
|
||||
|
||||
### Example
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
back_to_top: true
|
||||
back_to_top_text: "Back to top"
|
||||
```
|
||||
|
||||
{: .warning }
|
||||
Back-to-top links currently appear only when *other* configuration options require footer generation!
|
||||
@@ -0,0 +1,16 @@
|
||||
<!-- ---
|
||||
title: Navigation
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Navigation
|
||||
|
||||
The default page layout supports various navigation features:
|
||||
|
||||
* a **main navigation** panel, highlighting the currently selected page;
|
||||
* a list of **auxiliary** links, shown on all pages;
|
||||
* lists of **breadcrumbs**, shown on all except top level pages;
|
||||
* optional lists of links to **child pages** (so-called 'tables of contents'); and
|
||||
* section heading links for **in-page navigation**, with an optional **back-to-top** link.
|
||||
|
||||
See the following pages for how to specify these features, with illustrative examples. -->
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Ancestry
|
||||
parent: Main Navigation
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Ancestry
|
||||
|
||||
If no two pages on your website have the same `title`, you only need to set the `parent` titles to fix the hierarchy. You can also have the same `title` on pages that have no children, provided that they have different parent pages.
|
||||
|
||||
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: distinguishing parents with `grand_parent`
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: T
|
||||
parent: S
|
||||
grand_parent: X
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: T
|
||||
parent: S
|
||||
grand_parent: Y
|
||||
---
|
||||
```
|
||||
|
||||
The `ancestor` field of a page generalizes `grand_parent` to higher levels.
|
||||
|
||||
The following pages illustrate `parent` disambiguation using `grand_parent` and `ancestor` titles. Some descendants of both [Page X][X] and [Page Y][Y] have the same title, so references to those descendants as `parent` always require disambiguation.
|
||||
|
||||
- [X][X] is a parent page
|
||||
- [S][XS] is the only child of [X][X]. The `parent` reference to [X][X] is unambiguous.
|
||||
- [T][XT] is the only child of [S][XS]. Its `parent` is disambiguated by its `grand_parent`.
|
||||
- [U][XU] is the only child of [T][XT]. Its `parent` is disambiguated by its `ancestor`.
|
||||
- [Y][Y] is a sibling of [X][X].
|
||||
- [S][YS] is the only child of [Y][Y]. The `parent` reference to [Y][Y] is unambiguous.
|
||||
- [T][YT] is the only child of [S][YS]. Its `parent` is disambiguated by its `ancestor`
|
||||
- [U][YU] is the only child of [T][YT]. Its `parent` is disambiguated by its `ancestor`.
|
||||
|
||||
[X]: {% link docs/navigation/main/x.md %}
|
||||
[XS]: {% link docs/navigation/main/xs.md %}
|
||||
[XT]: {% link docs/navigation/main/xt.md %}
|
||||
[XU]: {% link docs/navigation/main/xu.md %}
|
||||
[Y]: {% link docs/navigation/main/y.md %}
|
||||
[YS]: {% link docs/navigation/main/ys.md %}
|
||||
[YT]: {% link docs/navigation/main/yt.md %}
|
||||
[YU]: {% link docs/navigation/main/yu.md %}
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Collections
|
||||
parent: Main Navigation
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Collections
|
||||
|
||||
By default, the navigation includes only [normal pages](https://jekyllrb.com/docs/pages/).
|
||||
However, you can configure Just the Docs to include also pages from [Jekyll collections](https://jekyllrb.com/docs/collections/).
|
||||
|
||||
{: .note }
|
||||
> You store collection pages in directories that start with an underscore (`_`), e.g., `_tests`. You won't see your `tests` collection pages in the navigation if you store them in a `tests` directory![^1]
|
||||
|
||||
[^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: 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`:
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
tests:
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
collections:
|
||||
tests:
|
||||
name: Tests
|
||||
```
|
||||
|
||||
Together with the `name` to be used for a collection in the navigation, you can configure the following options:
|
||||
|
||||
* `nav_exclude: true` to exclude the entire collection from the main navigation
|
||||
* `nav_fold: true` to fold the collection, instead of showing links to all its top-level pages[^2]
|
||||
* `search_exclude: true` to exclude all the collection pages from search results
|
||||
|
||||
[^2]:
|
||||
When JavaScript is disabled in the browser, all folded collections are automatically expanded,
|
||||
since clicking expander symbols has no effect.
|
||||
|
||||
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.
|
||||
|
||||
## Example: multiple collections
|
||||
{: .text-delta }
|
||||
|
||||
You can configure multiple collections. This creates categories in the main navigation with the configured names.
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
tests:
|
||||
output: true
|
||||
tutorials:
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
collections:
|
||||
tests:
|
||||
name: Tests
|
||||
search_exclude: true
|
||||
tutorials:
|
||||
name: Tutorials
|
||||
nav_fold: true
|
||||
```
|
||||
|
||||
The navigation for each collection is a separate name space for page titles: a page in one collection cannot be the `parent` of a page in a different collection, nor of a normal page.
|
||||
|
||||
----
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Excluding Pages
|
||||
parent: Main Navigation
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# Excluding Pages
|
||||
|
||||
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: using `nav_exclude`
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: default
|
||||
title: 404
|
||||
nav_exclude: true
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
Child pages are automatically excluded from the main navigation when their parent page is excluded.
|
||||
|
||||
{: .warning }
|
||||
It is currently possible to exclude all the child pages of a page from the main navigation by setting `has_children: false` in its front matter. However, the `has_children` parameter may be ignored altogether in a future release, so it is better to use the `nav_exclude` parameter on each child page.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: External Links
|
||||
parent: Main Navigation
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# External Links
|
||||
|
||||
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: external links
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
# External navigation links
|
||||
nav_external_links:
|
||||
- title: Just the Docs on GitHub
|
||||
url: https://github.com/just-the-docs/just-the-docs
|
||||
hide_icon: false # set to true to hide the external link icon - defaults to false
|
||||
opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
|
||||
```
|
||||
|
||||
## Opening external links in a new tab
|
||||
|
||||
The external links are decorated by an icon, which distinguishes them from internal links.
|
||||
You can suppress the icon by setting `hide_icon: true`.
|
||||
|
||||
By default, external links are not opened in a new tab. However, this can be enabled by:
|
||||
|
||||
1. setting `opens_in_new_tab: true` in the link's configuration object
|
||||
2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
|
||||
|
||||
When they conflict, `opens_in_new_tab` takes precedence.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Main Navigation
|
||||
parent: Navigation
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Main Navigation
|
||||
|
||||
The main navigation for your Just the Docs site is at the left side of the page on large screens, and at the top (behind a tap) on small screens.
|
||||
|
||||
You need to specify the `title` of each page in its front matter. Page titles are independent of file names and directory structure. The navigation uses the title of the page as an anchor for links to the page.
|
||||
|
||||
By default, links to all pages appear in the main navigation at the top level, ordered alphabetically by their titles. By adding further fields to the front matter of individual pages, you can [change their order]({% link docs/navigation/main/order.md %}), [exclude pages]({% link docs/navigation/main/exclude.md %}), and change their [parent pages]({% link docs/navigation/main/levels.md %}).
|
||||
|
||||
{: .new-title }
|
||||
> New (v0.10.0)
|
||||
>
|
||||
> The main navigation can be structured as a multi-level menu of unlimited depth:
|
||||
> pages can always have child pages.
|
||||
|
||||
For the construction of the navigation display to work (and to avoid potential confusion when browsing) ***the page titles on your site need to satisfy the following requirements:***
|
||||
|
||||
* Top-level pages must have different titles.
|
||||
* Pages with the same parent must have different titles.
|
||||
* The title of each page must be different from the titles of all its child pages, and from the titles of their child pages, etc.
|
||||
|
||||
{: .new-title }
|
||||
> New (v0.10.0)
|
||||
>
|
||||
> If *all* the pages of your site have different titles, you need only to specify the `title` of each page, and the `parent` title of each lower-level page.[^1]
|
||||
|
||||
[^1]: Previous versions of Just the Docs restricted the navigation to three levels. You also needed to specify `has_children: true` on all parent pages, and a `grand_parent` title on all grandchild pages. The `has_children` parameter is now redundant, and the `grand_parent` parameter can usually be omitted.
|
||||
|
||||
If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter.
|
||||
|
||||
{: .new-title }
|
||||
> New (v0.10.0)
|
||||
>
|
||||
> For deeper navigation structures, you can specify the title of a grandparent or higher level page as an `ancestor` title.
|
||||
|
||||
----
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: Page Levels
|
||||
parent: Main Navigation
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Page Levels
|
||||
|
||||
Sometimes you will want to create a page with many children. First, it is recommended that you store related pages together in a directory. For example, in these docs, we keep all of the written documentation pages in the `./docs` directory, and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like this:
|
||||
|
||||
{: .lh-0 }
|
||||
```
|
||||
┌─ ...
|
||||
├─ (Jekyll files)
|
||||
├─ docs
|
||||
├─ configuration.md
|
||||
├─ ui-components
|
||||
├─ index.md (parent page)
|
||||
├─ buttons.md
|
||||
├─ callouts.md
|
||||
├─ code
|
||||
├─ index.md (parent page)
|
||||
└─ line-numbers.md
|
||||
├─ labels.md
|
||||
├─ tables.md
|
||||
└─ typography.md
|
||||
├─ ...
|
||||
└─ MIGRATION.md
|
||||
├─ index.md (home page)
|
||||
├─ (Jekyll files)
|
||||
└─ ...
|
||||
```
|
||||
|
||||
## Example: page with no parents
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: UI Components
|
||||
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.
|
||||
|
||||
## 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: creating a child page
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
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 pages.
|
||||
|
||||
{: .new-title }
|
||||
> New (v0.10.0)
|
||||
>
|
||||
> The `has_children` field is now redundant (and ignored, except when significant for backwards compatibility).
|
||||
|
||||
## Multi-level Child Pages
|
||||
|
||||
Child pages can themselves have children, to any number of levels.
|
||||
|
||||
### Example: pages with (recursive) children
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Main Navigation
|
||||
parent: Navigation
|
||||
nav_order: 1
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Ancestry
|
||||
parent: Main Navigation
|
||||
nav_order: 4
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: X
|
||||
parent: Ancestry
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Y
|
||||
parent: Ancestry
|
||||
---
|
||||
```
|
||||
|
||||
This creates the following navigation structure:
|
||||
|
||||
{: .lh-0 }
|
||||
```
|
||||
┌─ ...
|
||||
├─ ...
|
||||
├─ Navigation
|
||||
├─ ...
|
||||
├─ Main Navigation
|
||||
├─ ...
|
||||
├─ Ancestry
|
||||
├─ X
|
||||
└─ Y
|
||||
├─ ...
|
||||
└─ ...
|
||||
├─ ...
|
||||
└─ ...
|
||||
├─ ...
|
||||
└─ ...
|
||||
```
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Ordering Pages
|
||||
parent: Main Navigation
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Ordering Pages
|
||||
|
||||
To specify a page order, you can use the `nav_order` parameter in the front matter of the pages.
|
||||
|
||||
## Example: using `nav_order`
|
||||
{: .text-delta }
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Customization
|
||||
nav_order: 6
|
||||
---
|
||||
```
|
||||
|
||||
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[^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.
|
||||
|
||||
{: .warning }
|
||||
The order of pages with equal `nav_order` parameters is unstable: it may change with each build.
|
||||
|
||||
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.[^case-insensitive]
|
||||
|
||||
Enclosing strings in quotation marks in front matter is optional, unless they contain "`[`", "`]`", "`{`", "`}`", "`,`", "`: `", or "` #`". Boolean, integer, and float values are treated as strings when enclosed in quotation marks.
|
||||
|
||||
----
|
||||
|
||||
[^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.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: X
|
||||
parent: Ancestry
|
||||
---
|
||||
# X
|
||||
|
||||
```yaml
|
||||
title: X
|
||||
parent: Ancestry
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: S
|
||||
parent: X
|
||||
---
|
||||
# S
|
||||
|
||||
```yaml
|
||||
title: S
|
||||
parent: X
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: T
|
||||
parent: S
|
||||
grand_parent: X
|
||||
---
|
||||
# T
|
||||
|
||||
```yaml
|
||||
title: T
|
||||
parent: S
|
||||
grand_parent: X
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: U
|
||||
parent: T
|
||||
ancestor: X
|
||||
---
|
||||
# U
|
||||
|
||||
```yaml
|
||||
title: U
|
||||
parent: T
|
||||
ancestor: X
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Y
|
||||
parent: Ancestry
|
||||
---
|
||||
# Y
|
||||
|
||||
```yaml
|
||||
title: Y
|
||||
parent: Ancestry
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: S
|
||||
parent: Y
|
||||
---
|
||||
# S
|
||||
|
||||
```yaml
|
||||
title: S
|
||||
parent: Y
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: T
|
||||
parent: S
|
||||
ancestor: Y
|
||||
---
|
||||
# T
|
||||
|
||||
```yaml
|
||||
title: T
|
||||
parent: S
|
||||
ancestor: Y
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: U
|
||||
parent: T
|
||||
ancestor: Y
|
||||
---
|
||||
# U
|
||||
|
||||
```yaml
|
||||
title: U
|
||||
parent: T
|
||||
ancestor: Y
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Breadcrumbs
|
||||
parent: Navigation
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Breadcrumbs
|
||||
|
||||
When using the default layout, all pages except top-level pages will automatically have a list of 'breadcrumbs' at the top, linking to the parent page and to any higher-level ancestors.
|
||||
|
||||
The default layout does not provide an option to suppress the list of breadcrumbs. To do that, you would need to define a new layout, or override the file `_includes/components/breadcrumbs.html` (e.g., with an empty file).
|
||||
+180
@@ -0,0 +1,180 @@
|
||||
<!-- ---
|
||||
title: Search
|
||||
nav_order: 7
|
||||
---
|
||||
|
||||
# Search
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
Just the Docs uses [lunr.js](https://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
|
||||
|
||||
## Enable search in configuration
|
||||
|
||||
In your site's `_config.yml`, enable search:
|
||||
|
||||
```yaml
|
||||
# Enable or disable the site search
|
||||
# Supports true (default) or false
|
||||
search_enabled: true
|
||||
```
|
||||
|
||||
### Search granularity
|
||||
|
||||
Pages are split into sections that can be searched individually.
|
||||
The sections are defined by the headings on the page.
|
||||
Each section is displayed in a separate search result.
|
||||
|
||||
```yaml
|
||||
# Split pages into sections that can be searched individually
|
||||
# Supports 1 - 6, default: 2
|
||||
search.heading_level: 2
|
||||
```
|
||||
|
||||
### Search previews
|
||||
|
||||
A search result can contain previews that show where the search words are found in the specific section.
|
||||
|
||||
```yaml
|
||||
# Maximum amount of previews per search result
|
||||
# Default: 3
|
||||
search.previews: 3
|
||||
|
||||
# Maximum amount of words to display before a matched word in the preview
|
||||
# Default: 5
|
||||
search.preview_words_before: 5
|
||||
|
||||
# Maximum amount of words to display after a matched word in the preview
|
||||
# Default: 10
|
||||
search.preview_words_after: 10
|
||||
```
|
||||
|
||||
### Search tokenizer
|
||||
|
||||
The default is for hyphens to separate tokens in search terms:
|
||||
`gem-based` is equivalent to `gem based`, matching either word.
|
||||
To allow search for hyphenated words:
|
||||
|
||||
```yaml
|
||||
# Set the search token separator
|
||||
# Default: /[\s\-/]+/
|
||||
# Example: enable support for hyphenated search words
|
||||
search.tokenizer_separator: /[\s/]+/
|
||||
```
|
||||
|
||||
### Display URL in search results
|
||||
|
||||
```yaml
|
||||
# Display the relative url in search results
|
||||
# Supports true (default) or false
|
||||
search.rel_url: false
|
||||
```
|
||||
|
||||
### Display search button
|
||||
|
||||
The search button displays in the bottom right corner of the screen and triggers the search input when clicked.
|
||||
|
||||
```yaml
|
||||
# Enable or disable the search button that appears in the bottom right corner of every page
|
||||
# Supports true or false (default)
|
||||
search.button: true
|
||||
```
|
||||
|
||||
### Focus search bar with a keyboard shortcut
|
||||
|
||||
Just the Docs supports focusing the search bar input with a keyboard shortcut. After setting the `search.focus_shortcut_key` config item key, users who press <kbd>Ctrl</kbd> + `search.focus_shortcut_key` (or on macOS, <kbd>Command</kbd> + `search.focus_shortcut_key`) will focus the search bar.
|
||||
|
||||
Note that this feature is **disabled by default**. `search.focus_shortcut_key` should be a [valid value from `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key); this involves all ASCII alphanumeric values, as well as modifier keys.
|
||||
|
||||
For example,
|
||||
|
||||
```yaml
|
||||
search:
|
||||
focus_shortcut_key: 'k'
|
||||
```
|
||||
|
||||
Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users (and <kbd>Command</kbd> + <kbd>K</kbd> on macOS).
|
||||
|
||||
## 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:
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: default
|
||||
title: Page not found
|
||||
nav_exclude: true
|
||||
search_exclude: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
## Generate search index when used as a gem
|
||||
|
||||
If you use Just the Docs as a remote theme, you do not need the following steps.
|
||||
|
||||
If you use the theme as a gem, you must initialize the search by running this `rake` command that comes with `just-the-docs`:
|
||||
|
||||
```bash
|
||||
$ 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/main/assets/js/zzzz-search-data.json).
|
||||
|
||||
## Custom content for search index
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
Advanced
|
||||
{: .label .label-yellow }
|
||||
|
||||
By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed.
|
||||
|
||||
{: .warning }
|
||||
> Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge.
|
||||
|
||||
1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json` is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem).
|
||||
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: adding custom `usage` and `examples` fields
|
||||
{: .text-delta }
|
||||
|
||||
This example adds front matter `usage` and `examples` fields to the search index.
|
||||
|
||||
`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields. Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences). `jsonify` will probably work for most scenarios.
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{%- capture newline %}
|
||||
{% endcapture -%}
|
||||
"myusage": {{ include.page.usage | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
|
||||
"myexamples": {{ include.page.examples | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`. All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`. Finally, append your custom fields on to the already existing `docs[i].content`.
|
||||
|
||||
```javascript
|
||||
const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples];
|
||||
docs[i].content = content_to_merge.join(' ');
|
||||
``` -->
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Buttons
|
||||
parent: UI Components
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# Buttons
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Basic button styles
|
||||
|
||||
### Links that look like buttons
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-purple }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-green }
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-outline }
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-purple }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-green }
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn .btn-outline }
|
||||
```
|
||||
|
||||
### Button element
|
||||
|
||||
GitHub Flavored Markdown does not support the `button` element, so you'll have to use inline HTML for this:
|
||||
|
||||
<div class="code-example">
|
||||
<button type="button" name="button" class="btn">Button element</button>
|
||||
</div>
|
||||
```html
|
||||
<button type="button" name="button" class="btn">Button element</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using utilities with buttons
|
||||
|
||||
### Button size
|
||||
|
||||
Wrap the button in a container that uses the [font-size utility classes]({% link docs/utilities/typography.md %}) to scale buttons:
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
<span class="fs-6">
|
||||
[Big ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
|
||||
<span class="fs-3">
|
||||
[Tiny ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
</div>
|
||||
```markdown
|
||||
<span class="fs-8">
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
|
||||
<span class="fs-3">
|
||||
[Tiny ass button](https://just-the-docs.com){: .btn }
|
||||
</span>
|
||||
```
|
||||
|
||||
### Spacing between buttons
|
||||
|
||||
Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
|
||||
[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
</div>
|
||||
```markdown
|
||||
[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
|
||||
[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
|
||||
[Button](https://just-the-docs.com){: .btn .btn-blue }
|
||||
```
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: Callouts
|
||||
parent: UI Components
|
||||
nav_order: 7
|
||||
---
|
||||
|
||||
# Callouts
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
|
||||
|
||||
Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
|
||||
|
||||
{: .warning }
|
||||
These callout names are *not* pre-defined by the theme: you need to define your own names.
|
||||
|
||||
When you have [configured]({% link docs/configuration.md %}#callouts) the `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
|
||||
|
||||
[^postfix]:
|
||||
You can put the callout markup either before or after its content.
|
||||
|
||||
## An untitled callout
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
{: .highlight }
|
||||
A paragraph
|
||||
```
|
||||
|
||||
{: .highlight }
|
||||
A paragraph
|
||||
|
||||
|
||||
## A single paragraph callout
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
{: .note }
|
||||
A paragraph
|
||||
```
|
||||
|
||||
{: .note }
|
||||
A paragraph
|
||||
|
||||
```markdown
|
||||
{: .note-title }
|
||||
> My note title
|
||||
>
|
||||
> A paragraph with a custom title callout
|
||||
```
|
||||
|
||||
{: .note-title }
|
||||
> My note title
|
||||
>
|
||||
> A paragraph with a custom title callout
|
||||
|
||||
## A multi-paragraph callout
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
{: .important }
|
||||
> A paragraph
|
||||
>
|
||||
> Another paragraph
|
||||
>
|
||||
> The last paragraph
|
||||
```
|
||||
|
||||
{: .important }
|
||||
> A paragraph
|
||||
>
|
||||
> Another paragraph
|
||||
>
|
||||
> The last paragraph
|
||||
|
||||
```markdown
|
||||
{: .important-title }
|
||||
> My important title
|
||||
>
|
||||
> A paragraph
|
||||
>
|
||||
> Another paragraph
|
||||
>
|
||||
> The last paragraph
|
||||
```
|
||||
|
||||
{: .important-title }
|
||||
> My important title
|
||||
>
|
||||
> A paragraph
|
||||
>
|
||||
> Another paragraph
|
||||
>
|
||||
> The last paragraph
|
||||
|
||||
## An indented callout
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
> {: .highlight }
|
||||
A paragraph
|
||||
```
|
||||
|
||||
> {: .highlight }
|
||||
A paragraph
|
||||
|
||||
## Indented multi-paragraph callouts
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
> {: .new }
|
||||
> > A paragraph
|
||||
> >
|
||||
> > Another paragraph
|
||||
> >
|
||||
> > The last paragraph
|
||||
```
|
||||
|
||||
> {: .new }
|
||||
> > A paragraph
|
||||
> >
|
||||
> > Another paragraph
|
||||
> >
|
||||
> > The last paragraph
|
||||
|
||||
|
||||
## Nested callouts
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
{: .important }
|
||||
> {: .warning }
|
||||
> A paragraph
|
||||
```
|
||||
|
||||
{: .important }
|
||||
> {: .warning }
|
||||
> A paragraph
|
||||
|
||||
## Opaque background
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
```markdown
|
||||
{: .important }
|
||||
> {: .opaque }
|
||||
> <div markdown="block">
|
||||
> {: .warning }
|
||||
> A paragraph
|
||||
> </div>
|
||||
```
|
||||
|
||||
{: .important }
|
||||
> {: .opaque }
|
||||
> <div markdown="block">
|
||||
> {: .warning }
|
||||
> A paragraph
|
||||
> </div>
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
title: Code
|
||||
parent: UI Components
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# Code
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Inline code
|
||||
|
||||
Code can be rendered inline by wrapping it in single back ticks.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
||||
|
||||
## Heading with `<inline code snippet>` in it.
|
||||
{: .no_toc }
|
||||
</div>
|
||||
```markdown
|
||||
Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
||||
|
||||
## Heading with `<inline code snippet>` in it.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Syntax highlighted code blocks
|
||||
|
||||
Use Jekyll's built-in syntax highlighting with Rouge for code blocks by using three backticks, followed by the language name:
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
```js
|
||||
// Javascript code with syntax highlighting.
|
||||
var fun = function lang(l) {
|
||||
dateformat.i18n = require('./lang/' + l)
|
||||
return true;
|
||||
}
|
||||
```
|
||||
</div>
|
||||
{% highlight markdown %}
|
||||
```js
|
||||
// Javascript code with syntax highlighting.
|
||||
var fun = function lang(l) {
|
||||
dateformat.i18n = require('./lang/' + l)
|
||||
return true;
|
||||
}
|
||||
```
|
||||
{% endhighlight %}
|
||||
|
||||
Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/code/line-numbers.md %}).
|
||||
|
||||
---
|
||||
|
||||
## Code blocks with rendered examples
|
||||
|
||||
To demonstrate front end code, sometimes it's useful to show a rendered example of that code. After including the styles from your project that you'll need to show the rendering, you can use a `<div>` with the `code-example` class, followed by the code block syntax. If you want to render your output with Markdown instead of HTML, use the `markdown="1"` attribute to tell Jekyll that the code you are rendering will be in Markdown format... This is about to get meta...
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
```
|
||||
|
||||
</div>
|
||||
{% highlight markdown %}
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
|
||||
</div>
|
||||
```markdown
|
||||
[Link button](https://just-the-docs.com){: .btn }
|
||||
```
|
||||
{% endhighlight %}
|
||||
|
||||
---
|
||||
|
||||
## Mermaid diagram code blocks
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
|
||||
|
||||
The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
|
||||
|
||||
```yaml
|
||||
mermaid:
|
||||
# Version of mermaid library
|
||||
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
|
||||
version: "9.1.3"
|
||||
```
|
||||
|
||||
Additional configuration options are loaded through `_includes/mermaid_config.js`. By default, the contents of the file are the empty object:
|
||||
|
||||
```js
|
||||
// _includes/mermaid_config.js
|
||||
{}
|
||||
```
|
||||
|
||||
This loads the default settings.
|
||||
|
||||
The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to:
|
||||
|
||||
```js
|
||||
// _includes/mermaid_config.js
|
||||
{
|
||||
theme: "forest"
|
||||
}
|
||||
```
|
||||
|
||||
Once mermaid is installed, it can be used in markdown files. The markdown for a simple flowchart example might look like the following:
|
||||
|
||||
{% 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;
|
||||
C-->D;
|
||||
```
|
||||
{% endhighlight %}
|
||||
|
||||
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;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*
|
||||
|
||||
### Using a local mermaid library
|
||||
|
||||
To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g.
|
||||
|
||||
```yaml
|
||||
mermaid:
|
||||
version: "10.1.0"
|
||||
# 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/`.
|
||||
```
|
||||
|
||||
For mermaid versions `>=10`, this file is imported directly as an ESM module (rather than as a plain `<script>` tag); users should use the `mermaid.esm.min.mjs` file. In contrast, for mermaid versions `<10`, this file is loaded as a script tag; it should be a standalone CJS file (i.e. `mermaid.min.js`).
|
||||
|
||||
{: .warning }
|
||||
Mermaid versions `10.0` - `10.1` (and possibly, future releases) still encode relative imports in `mermaid.esm.min.mjs`. Local users must copy *all* of the contents of the `dist` folder to the specified path (preserving the relative location of the files). Just the Docs is actively monitoring mermaid releases; an upstream fix is planned.
|
||||
|
||||
### Using mermaid with AsciiDoc
|
||||
|
||||
Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.
|
||||
|
||||
By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. The simplest way to resolve this is to use a [passthrough block](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/):
|
||||
{% highlight asciidoc %}
|
||||
++++
|
||||
<pre class="language-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;
|
||||
C-->D;
|
||||
</pre>
|
||||
++++
|
||||
{% endhighlight %}
|
||||
|
||||
Alternatively, community member [@flyx](https://github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://github.com/flyx)!
|
||||
|
||||
The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
|
||||
|
||||
## Copy button
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
The copy button for code blocks can be enabled or disabled via the `enable_copy_code_button` key in `_config.yml`. By default, the value of this key is `false`; users need to opt-in.
|
||||
|
||||
```yaml
|
||||
# For copy button on code
|
||||
enable_copy_code_button: true
|
||||
```
|
||||
|
||||
Note that this feature requires JavaScript; if JavaScript is disabled in the browser, this feature will not work. In addition, this feature uses `navigator.clipboard`, which is only available in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (such as over HTTPS). If the site is viewed in an insecure context, the copy button will not work ([relevant issue: #1202](https://github.com/just-the-docs/just-the-docs/issues/1202)).
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Line Numbers
|
||||
parent: Code
|
||||
---
|
||||
|
||||
# Code Snippets with Line Numbers
|
||||
|
||||
{: .warning }
|
||||
In prior versions of the docs, we provided "workarounds" to rendering issues arising from code snippets with line numbers. While these seemed to resolve visual layout issues, they did not resolve core issues with Jekyll generating invalid HTML. See [the detailed explanation](#detailed-error-explanation) for more information.
|
||||
|
||||
The default settings for HTML compression are incompatible with the HTML
|
||||
produced by Jekyll 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 %}
|
||||
|
||||
## Detailed Error Explanation
|
||||
|
||||
Consider this following code snippet, intended to highlight a simple Ruby program:
|
||||
|
||||
```
|
||||
{% raw %}{% highlight ruby linenos %}
|
||||
def foo
|
||||
puts 'foo'
|
||||
end
|
||||
{% endhighlight %}{% endraw %}
|
||||
```
|
||||
|
||||
If this is directly placed within a file processed by Jekyll (via Just the Docs, with HTML compression enabled), the following markup will be generated:
|
||||
|
||||
```html
|
||||
<figure class="highlight">><code class="language-ruby" data-lang="ruby"><div class="table-wrapper"><table class="rouge-table"><tbody><tr><td class="gutter gl"><pre class="lineno">1
|
||||
2
|
||||
3
|
||||
</pre><td class="code"><pre><span class="k">def</span> <span class="nf">foo</span>
|
||||
<span class="nb">puts</span> <span class="s1">'foo'</span>
|
||||
<span class="k">end</span>
|
||||
</pre></figure>
|
||||
```
|
||||
|
||||
This HTML is invalid; in particular, there are two issues:
|
||||
|
||||
1. there are many missing closing tags, and a superfluous `>`, which produce visually garbled output
|
||||
2. a `<table>` is placed within a `<code>` element, which is syntactically invalid HTML (but is often allowed by browsers)
|
||||
|
||||
To emphasize this first difference, here is the same markup output, indented by tag:
|
||||
|
||||
```html
|
||||
<figure class="highlight">
|
||||
>
|
||||
<code class="language-ruby" data-lang="ruby">
|
||||
<div class="table-wrapper">
|
||||
<table class="rouge-table">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="gutter gl">
|
||||
<pre class="lineno">
|
||||
1
|
||||
2
|
||||
3
|
||||
</pre>
|
||||
<td class="code">
|
||||
<pre>
|
||||
<span class="k">def</span>
|
||||
<span class="nf">foo</span>
|
||||
<span class="nb">puts</span>
|
||||
<span class="s1">'foo'</span>
|
||||
<span class="k">end</span>
|
||||
</pre>
|
||||
</figure>
|
||||
```
|
||||
|
||||
In order, there are missing `</td>`, `</td>`, `</tr>`, `</tbody>`, `</table>`, `</div>`, and `</code>` tags. As a result, the following elements of the page - including the site footer - become visually garbled as browsers attempt to recover gracefully.
|
||||
|
||||
Prior workarounds we suggested (such as [Dmitry Hrabrov's in `jekyll-compress-html`#71](https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901)) resolve the missing tag problem. However, they still place a `<table>` within a `<code>` element. The HTML spec normatively states that `<code>` elements should only contain "[phrasing content](https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2)", which does not include `<table>` ([spec ref](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element)). To avoid incorrectly rendered HTML, the previously-suggested workaround using the current version of `_includes/fix_linenos.html` should _not_ be used!
|
||||
@@ -0,0 +1,9 @@
|
||||
<!-- ---
|
||||
title: UI Components
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# UI Components
|
||||
|
||||
To make it as easy as possible to write documentation in plain Markdown, most UI components are styled using default Markdown elements with few additional CSS classes needed.
|
||||
{: .fs-6 .fw-300 } -->
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Labels
|
||||
parent: UI Components
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Labels
|
||||
|
||||
Use labels as a way to add an additional mark to a section of your docs. Labels come in a few colors. By default, labels will be blue.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Default label
|
||||
{: .label }
|
||||
|
||||
Blue label
|
||||
{: .label .label-blue }
|
||||
|
||||
Stable
|
||||
{: .label .label-green }
|
||||
|
||||
New release
|
||||
{: .label .label-purple }
|
||||
|
||||
Coming soon
|
||||
{: .label .label-yellow }
|
||||
|
||||
Deprecated
|
||||
{: .label .label-red }
|
||||
</div>
|
||||
```markdown
|
||||
Default label
|
||||
{: .label }
|
||||
|
||||
Blue label
|
||||
{: .label .label-blue }
|
||||
|
||||
Stable
|
||||
{: .label .label-green }
|
||||
|
||||
New release
|
||||
{: .label .label-purple }
|
||||
|
||||
Coming soon
|
||||
{: .label .label-yellow }
|
||||
|
||||
Deprecated
|
||||
{: .label .label-red }
|
||||
```
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: Lists
|
||||
parent: UI Components
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Lists
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
Most lists can be rendered with pure Markdown.
|
||||
|
||||
## Unordered list
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
- Item 1
|
||||
- Item 2
|
||||
- Item 3
|
||||
|
||||
_or_
|
||||
|
||||
* Item 1
|
||||
* Item 2
|
||||
* Item 3
|
||||
</div>
|
||||
```markdown
|
||||
- Item 1
|
||||
- Item 2
|
||||
- Item 3
|
||||
|
||||
_or_
|
||||
|
||||
* Item 1
|
||||
* Item 2
|
||||
* Item 3
|
||||
```
|
||||
|
||||
## Ordered list
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
1. Item 1
|
||||
1. Item 2
|
||||
1. Item 3
|
||||
</div>
|
||||
```markdown
|
||||
1. Item 1
|
||||
1. Item 2
|
||||
1. Item 3
|
||||
```
|
||||
|
||||
## Task list
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
- [ ] hello, this is a todo item
|
||||
- [ ] hello, this is another todo item
|
||||
- [x] goodbye, this item is done
|
||||
</div>
|
||||
```markdown
|
||||
- [ ] hello, this is a todo item
|
||||
- [ ] hello, this is another todo item
|
||||
- [x] goodbye, this item is done
|
||||
```
|
||||
|
||||
## Definition list
|
||||
|
||||
Definition lists require HTML syntax and aren't supported with the GitHub Flavored Markdown compiler.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
<dl>
|
||||
<dt>Name</dt>
|
||||
<dd>Godzilla</dd>
|
||||
<dt>Born</dt>
|
||||
<dd>1952</dd>
|
||||
<dt>Birthplace</dt>
|
||||
<dd>Japan</dd>
|
||||
<dt>Color</dt>
|
||||
<dd>Green</dd>
|
||||
</dl>
|
||||
</div>
|
||||
```html
|
||||
<dl>
|
||||
<dt>Name</dt>
|
||||
<dd>Godzilla</dd>
|
||||
<dt>Born</dt>
|
||||
<dd>1952</dd>
|
||||
<dt>Birthplace</dt>
|
||||
<dd>Japan</dd>
|
||||
<dt>Color</dt>
|
||||
<dd>Green</dd>
|
||||
</dl>
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Tables
|
||||
parent: UI Components
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Tables
|
||||
|
||||
Tables are responsive by default, allowing wide tables to have a horizontal scroll to access columns outside of the normal viewport.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
|
||||
| head1 | head two | three |
|
||||
|:-------------|:------------------|:------|
|
||||
| ok | good swedish fish | nice |
|
||||
| out of stock | good and plenty | nice |
|
||||
| ok | good `oreos` | hmm |
|
||||
| ok | good `zoute` drop | yumm |
|
||||
|
||||
</div>
|
||||
```markdown
|
||||
| head1 | head two | three |
|
||||
|:-------------|:------------------|:------|
|
||||
| ok | good swedish fish | nice |
|
||||
| out of stock | good and plenty | nice |
|
||||
| ok | good `oreos` | hmm |
|
||||
| ok | good `zoute` drop | yumm |
|
||||
```
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Typography
|
||||
parent: UI Components
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Typography
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Font stack
|
||||
|
||||
By default, Just the Docs uses a native system font stack for sans-serif fonts:
|
||||
|
||||
```scss
|
||||
system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Segoe UI Emoji"
|
||||
```
|
||||
|
||||
ABCDEFGHIJKLMNOPQRSTUVWXYZ
|
||||
abcdefghijklmnopqrstuvwxyz
|
||||
{: .fs-5 .ls-10 .code-example }
|
||||
|
||||
For monospace type, like code snippets or the `<pre>` element, Just the Docs uses a native system font stack for monospace fonts:
|
||||
|
||||
```scss
|
||||
"SFMono-Regular", Menlo, Consolas, Monospace
|
||||
```
|
||||
|
||||
ABCDEFGHIJKLMNOPQRSTUVWXYZ
|
||||
abcdefghijklmnopqrstuvwxyz
|
||||
{: .fs-5 .ls-10 .text-mono .code-example }
|
||||
|
||||
---
|
||||
|
||||
## Responsive type scale
|
||||
|
||||
Just the Docs uses a responsive type scale that shifts depending on the viewport size.
|
||||
|
||||
| Selector | Small screen size `font-size` | Large screen size `font-size` |
|
||||
|:----------------------|:---------------------------------|:------------------------------|
|
||||
| `h1`, `.text-alpha` | 32px | 36px |
|
||||
| `h2`, `.text-beta` | 18px | 24px |
|
||||
| `h3`, `.text-gamma` | 16px | 18px |
|
||||
| `h4`, `.text-delta` | 14px | 16px |
|
||||
| `h5`, `.text-epsilon` | 16px | 18px |
|
||||
| `h6`, `.text-zeta` | 18px | 24px |
|
||||
| `body` | 14px | 16px |
|
||||
|
||||
---
|
||||
|
||||
## Headings
|
||||
|
||||
Headings are rendered like this:
|
||||
|
||||
<div class="code-example">
|
||||
<h1>Heading 1</h1>
|
||||
<h2>Heading 2</h2>
|
||||
<h3>Heading 3</h3>
|
||||
<h4>Heading 4</h4>
|
||||
<h5>Heading 5</h5>
|
||||
<h6>Heading 6</h6>
|
||||
</div>
|
||||
```markdown
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
#### Heading 4
|
||||
##### Heading 5
|
||||
###### Heading 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Body text
|
||||
|
||||
Default body text is rendered like this:
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
</div>
|
||||
```markdown
|
||||
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inline elements
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
</div>
|
||||
```markdown
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~.
|
||||
|
||||
[Link to another page]({{site.baseurl}}/).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Typographic Utilities
|
||||
|
||||
There are a number of specific typographic CSS classes that allow you to override default styling for font size, font weight, line height, and capitalization.
|
||||
|
||||
[View typography utilities]({% link docs/utilities/typography.md %}){: .btn .btn-outline }
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Color
|
||||
parent: Utilities
|
||||
---
|
||||
|
||||
# Color Utilities
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
All the colors used in Just the Docs have been systematized into a series of variables that have been extended to both font color and background color utility classes.
|
||||
|
||||
## Light Greys
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-lt-000"></span> `grey-lt-000` | `.text-grey-lt-000` | `.bg-grey-lt-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-lt-100"></span> `grey-lt-100` | `.text-grey-lt-100` | `.bg-grey-lt-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-lt-200"></span> `grey-lt-200` | `.text-grey-lt-200` | `.bg-grey-lt-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-lt-300"></span> `grey-lt-300` | `.text-grey-lt-300` | `.bg-grey-lt-300` |
|
||||
|
||||
## Dark Greys
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-000"></span> `grey-dk-000` | `.text-grey-dk-000` | `.bg-grey-dk-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-100"></span> `grey-dk-100` | `.text-grey-dk-100` | `.bg-grey-dk-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-200"></span> `grey-dk-200` | `.text-grey-dk-200` | `.bg-grey-dk-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-250"></span> `grey-dk-250` | `.text-grey-dk-250` | `.bg-grey-dk-250` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-300"></span> `grey-dk-300` | `.text-grey-dk-300` | `.bg-grey-dk-300` |
|
||||
|
||||
## Purples
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-purple-000"></span> `purple-000` | `.text-purple-000` | `.bg-purple-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-purple-100"></span> `purple-100` | `.text-purple-100` | `.bg-purple-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-purple-200"></span> `purple-200` | `.text-purple-200` | `.bg-purple-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-purple-300"></span> `purple-300` | `.text-purple-300` | `.bg-purple-300` |
|
||||
|
||||
## Blues
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-blue-000"></span> `blue-000` | `.text-blue-000` | `.bg-blue-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-blue-100"></span> `blue-100` | `.text-blue-100` | `.bg-blue-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-blue-200"></span> `blue-200` | `.text-blue-200` | `.bg-blue-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-blue-300"></span> `blue-300` | `.text-blue-300` | `.bg-blue-300` |
|
||||
|
||||
## Greens
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-green-000"></span> `green-000` | `.text-green-000` | `.bg-green-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-green-100"></span> `green-100` | `.text-green-100` | `.bg-green-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-green-200"></span> `green-200` | `.text-green-200` | `.bg-green-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-green-300"></span> `green-300` | `.text-green-300` | `.bg-green-300` |
|
||||
|
||||
## Yellows
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-yellow-000"></span> `yellow-000` | `.text-yellow-000` | `.bg-yellow-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-yellow-100"></span> `yellow-100` | `.text-yellow-100` | `.bg-yellow-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-yellow-200"></span> `yellow-200` | `.text-yellow-200` | `.bg-yellow-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-yellow-300"></span> `yellow-300` | `.text-yellow-300` | `.bg-yellow-300` |
|
||||
|
||||
## Reds
|
||||
|
||||
| Color value | Font color utility | Background color utility |
|
||||
|:---------------|:---------------------|:-------------------------|
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-red-000"></span> `red-000` | `.text-red-000` | `.bg-red-000` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-red-100"></span> `red-100` | `.text-red-100` | `.bg-red-100` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-red-200"></span> `red-200` | `.text-red-200` | `.bg-red-200` |
|
||||
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-red-300"></span> `red-300` | `.text-red-300` | `.bg-red-300` |
|
||||
@@ -0,0 +1,10 @@
|
||||
<!-- ---
|
||||
title: Utilities
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Utilities
|
||||
{: .no_toc }
|
||||
|
||||
CSS utility classes come in handy when you want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
|
||||
{: .fs-6 .fw-300 } -->
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: Layout
|
||||
parent: Utilities
|
||||
---
|
||||
|
||||
# Layout Utilities
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Spacing
|
||||
|
||||
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 | Related CSS Property |
|
||||
|:-----------------|:------------------------------|
|
||||
| `.m-` | `margin` |
|
||||
| `.mx-` | `margin-left`, `margin-right` |
|
||||
| `.my-` | `margin top`, `margin bottom` |
|
||||
| `.mt-` | `margin-top` |
|
||||
| `.mr-` | `margin-right` |
|
||||
| `.mb-` | `margin-bottom` |
|
||||
| `.ml-` | `margin-left` |
|
||||
|
||||
| Classname prefix | Related CSS Property |
|
||||
|:-----------------|:--------------------------------|
|
||||
| `.p-` | `padding` |
|
||||
| `.px-` | `padding-left`, `padding-right` |
|
||||
| `.py-` | `padding top`, `padding bottom` |
|
||||
| `.pt-` | `padding-top` |
|
||||
| `.pr-` | `padding-right` |
|
||||
| `.pb-` | `padding-bottom` |
|
||||
| `.pl-` | `padding-left` |
|
||||
|
||||
Spacing values are based on a `1rem = 16px` spacing scale, broken down into these units:
|
||||
|
||||
| Spacer/suffix | Size in rems | Rem converted to px |
|
||||
|:---------------|:--------------|:--------------------|
|
||||
| `1` | 0.25rem | 4px |
|
||||
| `2` | 0.5rem | 8px |
|
||||
| `3` | 0.75rem | 12px |
|
||||
| `4` | 1rem | 16px |
|
||||
| `5` | 1.5rem | 24px |
|
||||
| `6` | 2rem | 32px |
|
||||
| `7` | 2.5rem | 40px |
|
||||
| `8` | 3rem | 48px |
|
||||
| `auto` | auto | auto |
|
||||
|
||||
Use `mx-auto` to horizontally center elements.
|
||||
|
||||
### Applying Spacing Utilities with `{: }`
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
```markdown
|
||||
This paragraph will have a margin bottom of 1rem/16px on large screens.
|
||||
{: .mb-lg-4 }
|
||||
|
||||
This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.
|
||||
{: .px-6 }
|
||||
```
|
||||
|
||||
## Horizontal Alignment
|
||||
|
||||
| CSS Class | Applied CSS Declaration |
|
||||
|:------------------------|:---------------------------------|
|
||||
| `.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
|
||||
|
||||
| CSS Class | Applied CSS Declaration |
|
||||
|:-----------------------|:--------------------------------|
|
||||
| `.v-align-baseline` | `vertical-align: baseline` |
|
||||
| `.v-align-bottom` | `vertical-align: bottom` |
|
||||
| `.v-align-middle` | `vertical-align: middle` |
|
||||
| `.v-align-text-bottom` | `vertical-align: text-bottom` |
|
||||
| `.v-align-text-top` | `vertical-align: text-top` |
|
||||
| `.v-align-top` | `vertical-align: top` |
|
||||
|
||||
## Display
|
||||
|
||||
Display classes aid in adapting the layout of the elements on a page:
|
||||
|
||||
| CSS Class | Applied CSS Declaration |
|
||||
|:------------------|:------------------------|
|
||||
| `.d-block` | `display: block` |
|
||||
| `.d-flex` | `display: flex` |
|
||||
| `.d-inline` | `display: inline` |
|
||||
| `.d-inline-block` | `display: inline-block` |
|
||||
| `.d-none` | `display: none` |
|
||||
|
||||
Use these classes in conjunction with the responsive modifiers.
|
||||
|
||||
### Applying Display Utilities with `{: }`
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
```markdown
|
||||
This button will be hidden until medium screen sizes:
|
||||
|
||||
[ A button ](#url)
|
||||
{: .d-none .d-md-inline-block }
|
||||
|
||||
These headings will be `inline-block`:
|
||||
|
||||
### heading 3
|
||||
{: .d-inline-block }
|
||||
|
||||
### heading 3
|
||||
{: .d-inline-block }
|
||||
```
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Responsive Modifiers
|
||||
parent: Utilities
|
||||
---
|
||||
|
||||
# Responsive modifiers
|
||||
|
||||
Just the Docs spacing works in conjunction with a variety of modifiers that allow you to target specific screen sizes responsively. Use these in conjunction with spacing and display prefix and suffix classes.
|
||||
|
||||
| Modifier | Screen size |
|
||||
|:----------|:-------------------------------------|
|
||||
| (none) | All screens until the next modifier |
|
||||
| `xs` | 320px (20rem) and up |
|
||||
| `sm` | 500px (31.25rem) and up |
|
||||
| `md` | 740px (46.25rem) and up |
|
||||
| `lg` | 1120px (70rem) and up |
|
||||
| `xl` | 1400px (87.5rem) and up |
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Typography
|
||||
parent: Utilities
|
||||
---
|
||||
|
||||
# Typography Utilities
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Font size
|
||||
|
||||
Use the `.fs-1` - `.fs-10` to set an explicit `font-size`.
|
||||
|
||||
| Class | Small screen size `font-size` | Large screen size `font-size` |
|
||||
|:--------|:-------------------------------|:------------------------------|
|
||||
| `.fs-1` | 9px | 10px |
|
||||
| `.fs-2` | 11px | 12px |
|
||||
| `.fs-3` | 12px | 14px |
|
||||
| `.fs-4` | 14px | 16px |
|
||||
| `.fs-5` | 16px | 18px |
|
||||
| `.fs-6` | 18px | 24px |
|
||||
| `.fs-7` | 24px | 32px |
|
||||
| `.fs-8` | 32px | 38px |
|
||||
| `.fs-9` | 38px | 42px |
|
||||
| `.fs-10`| 42px | 48px |
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Font size 1
|
||||
{: .fs-1 }
|
||||
Font size 2
|
||||
{: .fs-2 }
|
||||
Font size 3
|
||||
{: .fs-3 }
|
||||
Font size 4
|
||||
{: .fs-4 }
|
||||
Font size 5
|
||||
{: .fs-5 }
|
||||
Font size 6
|
||||
{: .fs-6 }
|
||||
Font size 7
|
||||
{: .fs-7 }
|
||||
Font size 8
|
||||
{: .fs-8 }
|
||||
Font size 9
|
||||
{: .fs-9 }
|
||||
Font size 10
|
||||
{: .fs-10 }
|
||||
</div>
|
||||
```markdown
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
Font size 1
|
||||
{: .fs-1 }
|
||||
Font size 2
|
||||
{: .fs-2 }
|
||||
Font size 3
|
||||
{: .fs-3 }
|
||||
Font size 4
|
||||
{: .fs-4 }
|
||||
Font size 5
|
||||
{: .fs-5 }
|
||||
Font size 6
|
||||
{: .fs-6 }
|
||||
Font size 7
|
||||
{: .fs-7 }
|
||||
Font size 8
|
||||
{: .fs-8 }
|
||||
Font size 9
|
||||
{: .fs-9 }
|
||||
Font size 10
|
||||
{: .fs-10 }
|
||||
```
|
||||
|
||||
## Font weight
|
||||
|
||||
Use the `.fw-300` - `.fw-700` to set an explicit `font-weight`.
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
Font weight 300
|
||||
{: .fw-300 }
|
||||
Font weight 400
|
||||
{: .fw-400 }
|
||||
Font weight 500
|
||||
{: .fw-500 }
|
||||
Font weight 700
|
||||
{: .fw-700 }
|
||||
</div>
|
||||
```markdown
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
Font weight 300
|
||||
{: .fw-300 }
|
||||
Font weight 400
|
||||
{: .fw-400 }
|
||||
Font weight 500
|
||||
{: .fw-500 }
|
||||
Font weight 700
|
||||
{: .fw-700 }
|
||||
```
|
||||
|
||||
## Line height
|
||||
|
||||
Use the `lh-` classes to explicitly apply line height to text.
|
||||
|
||||
| Class | `line-height` value | Notes |
|
||||
|:--------------|:---------------------|:------------------------------|
|
||||
| `.lh-0` | 0 | |
|
||||
| `.lh-tight` | 1.1 | Default for headings |
|
||||
| `.lh-default` | 1.4 | Default for body (paragraphs) |
|
||||
|
||||
<div class="code-example" markdown="1">
|
||||
No Line height
|
||||
No Line height
|
||||
{: .lh-0 }
|
||||
|
||||
Tight line height
|
||||
Tight line height
|
||||
{: .lh-tight }
|
||||
|
||||
Default line height
|
||||
Default line height
|
||||
{: .fh-default }
|
||||
</div>
|
||||
```markdown
|
||||
In Markdown, use the `{: }` wrapper to apply custom classes:
|
||||
|
||||
No Line height
|
||||
No Line height
|
||||
{: .lh-0 }
|
||||
|
||||
Tight line height
|
||||
Tight line height
|
||||
{: .lh-tight }
|
||||
|
||||
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` |
|
||||
Reference in New Issue
Block a user