mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-09-12 21:03:32 -06:00
Update to new repo path
This commit is contained in:
Patrick Marsceill
committed by
GitHub
GitHub
parent
e842498637
commit
2aa9815064
@@ -5,23 +5,22 @@ nav_order: 2
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
|
||||
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's _config.yml file.
|
||||
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
## Table of contents
|
||||
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
|
||||
View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
|
||||
|
||||
View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/master/_config.yml) file as an example.
|
||||
|
||||
## Site logo
|
||||
|
||||
@@ -68,7 +67,7 @@ search:
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/pmarsceill/just-the-docs"
|
||||
- "//github.com/just-the-docs/just-the-docs"
|
||||
|
||||
# Makes Aux links open in a new tab. Default is false
|
||||
aux_links_new_tab: false
|
||||
@@ -91,7 +90,7 @@ heading_anchors: true
|
||||
# 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/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
|
||||
footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/master/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
|
||||
@@ -100,7 +99,7 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
|
||||
# Footer "Edit this page on GitHub" link text
|
||||
gh_edit_link: true # show or hide edit this page link
|
||||
gh_edit_link_text: "Edit this page on GitHub."
|
||||
gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
|
||||
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
|
||||
gh_edit_branch: "master" # 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
|
||||
@@ -121,6 +120,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie
|
||||
# Color scheme supports "light" (default) and "dark"
|
||||
color_scheme: dark
|
||||
```
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
@@ -154,6 +154,7 @@ By default, the navigation and search include normal [pages](https://jekyllrb.co
|
||||
Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
|
||||
|
||||
For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
|
||||
|
||||
```yaml
|
||||
# Define Jekyll collections
|
||||
collections:
|
||||
@@ -179,6 +180,7 @@ just_the_docs:
|
||||
|
||||
You can reference multiple collections.
|
||||
This creates categories in the navigation with the configured names.
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
docs:
|
||||
@@ -195,4 +197,3 @@ just_the_docs:
|
||||
tutorials:
|
||||
name: Tutorials
|
||||
```
|
||||
|
||||
|
||||
@@ -5,17 +5,20 @@ nav_order: 6
|
||||
---
|
||||
|
||||
# Customization
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Color schemes
|
||||
|
||||
{: .d-inline-block }
|
||||
|
||||
New
|
||||
@@ -26,12 +29,14 @@ Just the Docs supports two color schemes: light (default), and dark.
|
||||
To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file:
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
# Color scheme supports "light" (default) and "dark"
|
||||
color_scheme: dark
|
||||
```
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
@@ -53,14 +58,15 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
### Define a custom scheme
|
||||
|
||||
You can add custom schemes.
|
||||
If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
|
||||
If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
|
||||
where you override theme variables to change colors, fonts, spacing, etc.
|
||||
|
||||
Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_variables.scss) file.
|
||||
Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/master/_sass/support/_variables.scss) file.
|
||||
|
||||
For example, to change the link color from the purple default to blue, include the following inside your scheme file:
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```scss
|
||||
@@ -73,6 +79,7 @@ Please use scheme files.
|
||||
### Use a custom scheme
|
||||
|
||||
To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file:
|
||||
|
||||
```yaml
|
||||
color_scheme: foo
|
||||
```
|
||||
@@ -83,15 +90,15 @@ If you want to be able to change the scheme dynamically, for example via javascr
|
||||
with the following content:`
|
||||
|
||||
{% raw %}
|
||||
---
|
||||
---
|
||||
{% include css/just-the-docs.scss.liquid color_scheme="foo" %}
|
||||
---
|
||||
---
|
||||
{% 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');
|
||||
jtd.setTheme("foo")
|
||||
```
|
||||
|
||||
## Override and completely custom styles
|
||||
@@ -104,12 +111,19 @@ This will allow for all overrides to be kept in a single file, and for any upstr
|
||||
For example, if you'd like to add your own styles for printing a page, you could add the following styles.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```scss
|
||||
// Print-only styles.
|
||||
@media print {
|
||||
.side-bar, .page-header { display: none; }
|
||||
.main-content { max-width: auto; margin: 1em;}
|
||||
.side-bar,
|
||||
.page-header {
|
||||
display: none;
|
||||
}
|
||||
.main-content {
|
||||
max-width: auto;
|
||||
margin: 1em;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -5,6 +5,7 @@ nav_order: 5
|
||||
---
|
||||
|
||||
# Navigation Structure
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
<details open markdown="block">
|
||||
@@ -31,6 +32,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
|
||||
To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -39,6 +41,7 @@ layout: default
|
||||
title: Customization
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -47,7 +50,7 @@ The parameter values can be numbers (integers, floats) and/or strings. When you
|
||||
|
||||
By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional.
|
||||
|
||||
> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.
|
||||
> _Note for users of previous versions:_ `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.
|
||||
|
||||
---
|
||||
|
||||
@@ -56,6 +59,7 @@ By default, all Capital letters come before all lowercase letters; you can add `
|
||||
For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -64,11 +68,12 @@ layout: default
|
||||
title: 404
|
||||
nav_exclude: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
|
||||
|
||||
Pages with no `title` are automatically excluded from the navigation.
|
||||
Pages with no `title` are automatically excluded from the navigation.
|
||||
|
||||
---
|
||||
|
||||
@@ -104,9 +109,11 @@ Sometimes you will want to create a page with many children (a section). First,
|
||||
```
|
||||
|
||||
On the parent pages, add this YAML front matter parameter:
|
||||
- `has_children: true` (tells us that this is a parent page)
|
||||
|
||||
- `has_children: true` (tells us that this is a parent page)
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -116,16 +123,19 @@ title: UI Components
|
||||
nav_order: 2
|
||||
has_children: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav.
|
||||
|
||||
### Child pages
|
||||
|
||||
{: .text-gamma }
|
||||
|
||||
On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -135,6 +145,7 @@ title: Buttons
|
||||
parent: UI Components
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
The Buttons page appears as a child of UI Components and appears second in the UI Components section.
|
||||
@@ -144,6 +155,7 @@ The Buttons page appears as a child of UI Components and appears second in the U
|
||||
By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -154,9 +166,11 @@ nav_order: 2
|
||||
has_children: true
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
### Children with children
|
||||
|
||||
{: .text-gamma }
|
||||
|
||||
Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
|
||||
@@ -165,6 +179,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
|
||||
1. Add the `parent` and `grand_parent` attribute to the grandchild
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@@ -175,6 +190,7 @@ parent: UI Components
|
||||
nav_order: 2
|
||||
has_children: true
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
```yaml
|
||||
@@ -185,6 +201,7 @@ parent: Buttons
|
||||
grand_parent: UI Components
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
This would create the following navigation structure:
|
||||
@@ -210,13 +227,14 @@ This would create the following navigation structure:
|
||||
To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/pmarsceill/just-the-docs"
|
||||
- "//github.com/just-the-docs/just-the-docs"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -226,20 +244,23 @@ aux_links:
|
||||
To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```markdown
|
||||
# Navigation Structure
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
{:toc}
|
||||
```
|
||||
|
||||
This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`.
|
||||
This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`.
|
||||
|
||||
### Collapsible Table of Contents
|
||||
|
||||
|
||||
Reference in New Issue
Block a user