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

Merge remote-tracking branch 'upstream/master'

Browse Source
This commit is contained in:
Henrique Vianna
2020-06-27 17:34:59 -03:00
parent 7cfc63e138 972da61cf9
commit 1f492b68f3
55 changed files with 1989 additions and 1210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/configuration.md
View File

@@ -36,9 +36,29 @@ logo: "/assets/images/just-the-docs.png"
# Supports true (default) or false
search_enabled: true
# Enable support for hyphenated search words:
search_tokenizer_separator: /[\s/]+/
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
```
## Aux links
@@ -48,6 +68,9 @@ search_tokenizer_separator: /[\s/]+/
aux_links:
"Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs"
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
```
## Heading anchor links
@@ -56,26 +79,56 @@ aux_links:
# 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/nil
# Supports true (default) or false
heading_anchors: true
```
## Footer content
```yaml
# Footer content appears at the bottom of every page's main content
# Footer content
# appears at the bottom of every page's main content
footer_content: "Copyright &copy; 2017-2019 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
# 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/pmarsceill/just-the-docs" # the github URL for your repo
gh_edit_branch: "master" # the branch that your docs is served from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
```
- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format
- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
- `gh_edit_repository` is the URL of the project's GitHub repository
- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master`
- `gh_edit_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 currently only supports "dark" or nil (default)
color_scheme: "dark"
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
<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]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
@@ -85,4 +138,5 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more
# Google Analytics Tracking (optional)
# e.g, UA-1234567-89
ga_tracking: UA-5555555-55
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
```

68
docs/customization.md
View File

@@ -29,37 +29,77 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf
{: .no_toc }
```yaml
# Color scheme currently only supports "dark" or nil (default)
color_scheme: "dark"
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
<script>
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
## Specific visual customization
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>
To customize your site’s aesthetic, open `_sass/custom/custom.scss` in your editor to see if there is a variable that you can override. Most styles like fonts, colors, spacing, etc. are derived from these variables. To override a specific variable, uncomment its line and change its value.
## Custom schemes
For example, to change the link color from the purple default to blue, open `_sass/custom/custom.css` and find the `$link-color` variable on line `50`. Uncomment it, and change its value to our `$blue-000` variable, or another shade of your choosing.
### 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.
Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/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
// ...
//
// $body-text-color: $grey-dk-100;
// $body-heading-color: $grey-dk-300;
$link-color: $blue-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.
## Override styles
### Use a custom scheme
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.
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 completely custom styles
For styles that aren't defined as 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.
For example, if you'd like to add your own styles for printing a page, you could add the following styles.

11
docs/navigation-structure.md
View File

@@ -38,6 +38,13 @@ nav_order: 4
---
```
The specified `nav_order` parameters on a site should be all integers or all strings.
Pages without a `nav_order` parameter are ordered alphabetically by their `title`,
and appear after the explicitly-ordered pages at each level.
By default, all Capital letters are sorted before all lowercase letters;
adding `nav_sort: case_insensitive` in the configuration file ignores case
when sorting strings (but also sorts numbers lexicographically: `10` comes before `1`).
---
## Excluding pages
@@ -190,9 +197,9 @@ This would create the following navigation structure:
---
## Auxiliary Navigation
## Auxiliary Links
To add a auxiliary navigation item to your site (in the upper right on all pages), add it to the `aux_nav` [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-nav) in your site's `_config.yml` file.
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 }

108
docs/search.md
View File

@@ -15,62 +15,90 @@ nav_order: 7
---
Just the Docs uses [lunr.js](http://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:
Just the Docs uses [lunr.js](http://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
## Set up search
### Generate search index
Before you can use search, you must initialize the feature by running this `rake` command that comes with `just-the-docs`:
```bash
$ bundle exec just-the-docs rake search:init
```
This command creates the `search-data.json` file that Jekyll uses to create your search index. Alternatively, you can create the file manually in the `assets/js/` directory of your Jekyll site with this content:
```liquid
{% raw %}---
---
{
{% assign comma = false %}
{% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
"title": "{{ page.title | replace: '&amp;', '&' }}",
"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 }}"
}{% assign comma = true %}
{% endif %}{% endfor %}
}{% endraw %}
```
_Note: If you don't run this rake command or create this file manually, search will not work (or it will use the search index data from this docs site, not your site's content)._
### Enable search in configuration
## 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
search_tokenizer_separator: /[\s/]+/
# 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
```
## 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:
Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
#### Example
{: .no_toc }
@@ -83,3 +111,17 @@ 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/master/assets/js/zzzz-search-data.json).

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

@@ -22,9 +22,14 @@ 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.
```
---

1
docs/utilities/color.md
View File

@@ -2,7 +2,6 @@
layout: default
title: Color
parent: Utilities
nav_order: 3
---
# Color Utilities

17
docs/utilities/layout.md
View File

@@ -2,7 +2,6 @@
layout: default
title: Layout
parent: Utilities
nav_order: 2
---
# Layout Utilities
@@ -52,6 +51,9 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes
| `6` | 2rem | 32px |
| `7` | 2.5rem | 40px |
| `8` | 3rem | 48px |
| `auto` | auto | auto |
Use `mx-auto` to horizontally center elements.
#### Examples
{: .no_toc }
@@ -66,6 +68,19 @@ This paragraph will have 2rem/32px of padding on the right and left at all scree
{: .px-6 }
```
## Horizontal Alignment
| Classname | What it does |
|:------------------------|:---------------------------------|
| `.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
| Classname | What it does |

1
docs/utilities/responsive-modifiers.md
View File

@@ -2,7 +2,6 @@
layout: default
title: Responsive Modifiers
parent: Utilities
nav_order: 1
---
# Responsive modifiers

11
docs/utilities/typography.md
View File

@@ -2,7 +2,6 @@
layout: default
title: Typography
parent: Utilities
nav_order: 4
---
# Typography Utilities
@@ -145,3 +144,13 @@ 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` |