mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-09-13 13:23:32 -06:00
Merge branch 'master' into master
This commit is contained in:
Matthew Wang
GitHub
@@ -22,12 +22,23 @@ Just the Docs has some specific configuration parameters that can be defined in
|
||||
|
||||
View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
|
||||
|
||||
## Search enabled
|
||||
## 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"
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
```yaml
|
||||
# Enable or disable the site search
|
||||
# Support true (default) or false
|
||||
# Supports true (default) or false
|
||||
search_enabled: true
|
||||
|
||||
# Enable support for hyphenated search words:
|
||||
search_tokenizer_separator: /[\s/]+/
|
||||
|
||||
```
|
||||
|
||||
## Aux links
|
||||
@@ -35,18 +46,17 @@ search_enabled: true
|
||||
```yaml
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/pmarsceill/just-the-docs"
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/pmarsceill/just-the-docs"
|
||||
```
|
||||
|
||||
## 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.
|
||||
# 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.
|
||||
#
|
||||
# Supprts true (default) or false/nil
|
||||
# Supports true (default) or false/nil
|
||||
heading_anchors: true
|
||||
```
|
||||
|
||||
@@ -75,20 +85,7 @@ color_scheme: "dark"
|
||||
```
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
|
||||
const cssFile = document.querySelector('[rel="stylesheet"]');
|
||||
const originalCssRef = cssFile.getAttribute('href');
|
||||
const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css');
|
||||
|
||||
jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
if (cssFile.getAttribute('href') === originalCssRef) {
|
||||
cssFile.setAttribute('href', darkModeCssRef);
|
||||
} else {
|
||||
cssFile.setAttribute('href', originalCssRef);
|
||||
}
|
||||
})
|
||||
</script>
|
||||
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
|
||||
|
||||
See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
|
||||
|
||||
|
||||
@@ -34,20 +34,7 @@ color_scheme: "dark"
|
||||
```
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
|
||||
const cssFile = document.querySelector('[rel="stylesheet"]');
|
||||
const originalCssRef = cssFile.getAttribute('href');
|
||||
const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css');
|
||||
|
||||
jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
if (cssFile.getAttribute('href') === originalCssRef) {
|
||||
cssFile.setAttribute('href', darkModeCssRef);
|
||||
} else {
|
||||
cssFile.setAttribute('href', originalCssRef);
|
||||
}
|
||||
})
|
||||
</script>
|
||||
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
|
||||
|
||||
## Specific visual customization
|
||||
|
||||
@@ -69,3 +56,20 @@ $link-color: $blue-000;
|
||||
```
|
||||
|
||||
_Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail.
|
||||
|
||||
## Override styles
|
||||
|
||||
For styles that aren't defined as a variables, you may want to modify specific CSS classes. To add your own CSS overrides at the end of the cascade, edit `_sass/overrides.scss`. This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
|
||||
|
||||
For example, if you'd like to add your own styles for printing a page, you could add the following styles.
|
||||
|
||||
#### Example
|
||||
{: .no_toc }
|
||||
|
||||
```scss
|
||||
// Print-only styles.
|
||||
@media print {
|
||||
.side-bar, .page-header { display: none; }
|
||||
.main-content { max-width: auto; margin: 1em;}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -67,7 +67,7 @@ Sometimes you will want to create a page with many children (a section). First,
|
||||
|
|
||||
|-- docs
|
||||
| |-- ui-components
|
||||
| | |-- ui-components.md (parent page)
|
||||
| | |-- index.md (parent page)
|
||||
| | |-- buttons.md
|
||||
| | |-- code.md
|
||||
| | |-- labels.md
|
||||
@@ -75,7 +75,7 @@ Sometimes you will want to create a page with many children (a section). First,
|
||||
| | +-- typography.md
|
||||
| |
|
||||
| |-- utilities
|
||||
| | |-- utilities.md (parent page)
|
||||
| | |-- index.md (parent page)
|
||||
| | |-- color.md
|
||||
| | |-- layout.md
|
||||
| | |-- responsive-modifiers.md
|
||||
@@ -88,9 +88,8 @@ Sometimes you will want to create a page with many children (a section). First,
|
||||
+-- ..
|
||||
```
|
||||
|
||||
On the parent pages, add 2 YAML front matter parameters:
|
||||
On the parent pages, add this YAML front matter parameter:
|
||||
- `has_children: true` (tells us that this is a parent page)
|
||||
- `permalink:` set this to the site directory that contains the child pages
|
||||
|
||||
#### Example
|
||||
{: .no_toc }
|
||||
@@ -101,7 +100,6 @@ layout: default
|
||||
title: UI Components
|
||||
nav_order: 2
|
||||
has_children: true
|
||||
permalink: /docs/ui-components
|
||||
---
|
||||
```
|
||||
|
||||
@@ -140,7 +138,6 @@ title: UI Components
|
||||
nav_order: 2
|
||||
has_children: true
|
||||
has_toc: false
|
||||
permalink: /docs/ui-components
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -37,13 +37,13 @@ This command creates the `search-data.json` file that Jekyll uses to create your
|
||||
{% raw %}---
|
||||
---
|
||||
{
|
||||
{% for page in site.html_pages %}{% if page.search_exclude != true %}"{{ forloop.index0 }}": {
|
||||
"id": "{{ forloop.index0 }}",
|
||||
{% assign comma = false %}
|
||||
{% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
|
||||
"title": "{{ page.title | replace: '&', '&' }}",
|
||||
"content": "{{ page.content | markdownify | strip_html | escape_once | remove: 'Table of contents' | remove: '```' | remove: '---' | replace: '\', ' ' | normalize_whitespace }}",
|
||||
"content": "{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```' | remove: '---' | replace: '\', ' ' | replace: ' . . . ', ' . ' | replace: ' . . ', ' . ' | normalize_whitespace }}",
|
||||
"url": "{{ page.url | absolute_url }}",
|
||||
"relUrl": "{{ page.url }}"
|
||||
}{% unless forloop.last %},{% endunless %}
|
||||
}{% assign comma = true %}
|
||||
{% endif %}{% endfor %}
|
||||
}{% endraw %}
|
||||
```
|
||||
@@ -59,6 +59,15 @@ In your site's `_config.yml`, enable search:
|
||||
search_enabled: true
|
||||
```
|
||||
|
||||
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
|
||||
search_tokenizer_separator: /[\s/]+/
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
Reference in New Issue
Block a user