mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-25 20:42:22 -06:00
Merge branch 'main' into dependabot/add-v2-config-file
This commit is contained in:
Matt Wang
GitHub
commit
577b9c5862
2
.github/ISSUE_TEMPLATE/config.yml
vendored
2
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -1,5 +1,5 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Ask a question
|
||||
url: https://github.com/pmarsceill/just-the-docs/discussions
|
||||
url: https://github.com/just-the-docs/just-the-docs/discussions
|
||||
about: Ask questions and discuss with other community members
|
||||
|
||||
36
.github/release-drafter.yml
vendored
36
.github/release-drafter.yml
vendored
@ -1,33 +1,33 @@
|
||||
references:
|
||||
- v+
|
||||
- master
|
||||
name-template: 'v$RESOLVED_VERSION 🌈'
|
||||
tag-template: 'v$RESOLVED_VERSION'
|
||||
- main
|
||||
name-template: "v$RESOLVED_VERSION 🌈"
|
||||
tag-template: "v$RESOLVED_VERSION"
|
||||
categories:
|
||||
- title: '🚀 Features'
|
||||
- title: "🚀 Features"
|
||||
labels:
|
||||
- 'feature'
|
||||
- 'enhancement'
|
||||
- title: '🐛 Bug Fixes'
|
||||
- "feature"
|
||||
- "enhancement"
|
||||
- title: "🐛 Bug Fixes"
|
||||
labels:
|
||||
- 'fix'
|
||||
- 'bugfix'
|
||||
- 'bug'
|
||||
- title: '🧰 Maintenance'
|
||||
label:
|
||||
- 'chore'
|
||||
- 'dependencies'
|
||||
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
|
||||
- "fix"
|
||||
- "bugfix"
|
||||
- "bug"
|
||||
- title: "🧰 Maintenance"
|
||||
label:
|
||||
- "chore"
|
||||
- "dependencies"
|
||||
change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
|
||||
version-resolver:
|
||||
major:
|
||||
labels:
|
||||
- 'next-major-release'
|
||||
- "next-major-release"
|
||||
minor:
|
||||
labels:
|
||||
- 'next-minor-release'
|
||||
- "next-minor-release"
|
||||
patch:
|
||||
labels:
|
||||
- 'patch'
|
||||
- "patch"
|
||||
default: minor
|
||||
template: |
|
||||
## Changes
|
||||
|
||||
47
.github/workflows/ci-master.yml
vendored
47
.github/workflows/ci-master.yml
vendored
@ -1,45 +1,42 @@
|
||||
on:
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- main
|
||||
|
||||
name: Master branch CI
|
||||
name: main branch CI
|
||||
|
||||
jobs:
|
||||
|
||||
jekyll-latest:
|
||||
name: Build Jekyll site (latest)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@main
|
||||
|
||||
- uses: actions/checkout@master
|
||||
|
||||
- name: Build the site in the jekyll/builder container
|
||||
run: |
|
||||
docker run --rm \
|
||||
--volume="${{ github.workspace }}:/srv/jekyll" \
|
||||
jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
|
||||
- name: Build the site in the jekyll/builder container
|
||||
run: |
|
||||
docker run --rm \
|
||||
--volume="${{ github.workspace }}:/srv/jekyll" \
|
||||
jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
|
||||
jekyll-3-8-5:
|
||||
name: Build Jekyll site (v3.8.5)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@main
|
||||
|
||||
- uses: actions/checkout@master
|
||||
|
||||
- name: Build the site in the jekyll/builder container
|
||||
run: |
|
||||
docker run --rm \
|
||||
--volume="${{ github.workspace }}:/srv/jekyll" \
|
||||
jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
|
||||
- name: Build the site in the jekyll/builder container
|
||||
run: |
|
||||
docker run --rm \
|
||||
--volume="${{ github.workspace }}:/srv/jekyll" \
|
||||
jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
|
||||
assets:
|
||||
name: Format and test CSS and JS
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Use Node.js 12.x
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: '12.x'
|
||||
- run: npm install
|
||||
- run: npm test
|
||||
- uses: actions/checkout@v2
|
||||
- name: Use Node.js 12.x
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: "12.x"
|
||||
- run: npm install
|
||||
- run: npm test
|
||||
|
||||
@ -7,3 +7,4 @@ assets/css/just-the-docs-dark.scss
|
||||
assets/js/vendor/lunr.min.js
|
||||
assets/js/search-data.json
|
||||
assets/js/just-the-docs.js
|
||||
*.md
|
||||
|
||||
@ -4,5 +4,4 @@
|
||||
"singleQuote": false,
|
||||
"tabWidth": 2,
|
||||
"trailingComma": "es5"
|
||||
}
|
||||
|
||||
}
|
||||
21
README.md
21
README.md
@ -1,11 +1,11 @@
|
||||
<p align="right">
|
||||
<a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/pmarsceill/just-the-docs/actions?query=workflow%3A%22Master+branch+CI%22"><img src="https://github.com/pmarsceill/just-the-docs/workflows/Master%20branch%20CI/badge.svg" alt="Build status"></a>
|
||||
<a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/just-the-docs/just-the-docs/actions?query=workflow%3A%22main+branch+CI%22"><img src="https://github.com/just-the-docs/just-the-docs/workflows/main%20branch%20CI/badge.svg" alt="Build status"></a>
|
||||
</p>
|
||||
<br><br>
|
||||
<p align="center">
|
||||
<h1 align="center">Just the Docs</h1>
|
||||
<p align="center">A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
|
||||
<p align="center"><strong><a href="https://pmarsceill.github.io/just-the-docs/">See it in action!</a></strong></p>
|
||||
<p align="center"><strong><a href="https://just-the-docs.github.io/just-the-docs/">See it in action!</a></strong></p>
|
||||
<br><br><br>
|
||||
</p>
|
||||
|
||||
@ -13,6 +13,17 @@
|
||||
|
||||
## Installation
|
||||
|
||||
### via GitHub Pages remote theme
|
||||
|
||||
The quickiest way to use Just The Docs is to use GitHub pages [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/) feature in your `config.yml` file:
|
||||
|
||||
```yaml
|
||||
remote_theme: just-the-docs/just-the-docs
|
||||
```
|
||||
### via RubyGems:
|
||||
|
||||
Alternatively you can install it as a Ruby Gem.
|
||||
|
||||
Add this line to your Jekyll site's Gemfile:
|
||||
|
||||
```ruby
|
||||
@ -39,15 +50,15 @@ Alternatively, you can run it inside Docker while developing your site
|
||||
|
||||
## Usage
|
||||
|
||||
[View the documentation](https://pmarsceill.github.io/just-the-docs/) for usage information.
|
||||
[View the documentation](https://just-the-docs.github.io/just-the-docs/) for usage information.
|
||||
|
||||
## Contributing
|
||||
|
||||
Bug reports and pull requests are welcome on GitHub at https://github.com/pmarsceill/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
||||
Bug reports and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
||||
|
||||
### Submitting code changes:
|
||||
|
||||
- Open a [Pull Request](https://github.com/pmarsceill/just-the-docs/pulls)
|
||||
- Open a [Pull Request](https://github.com/just-the-docs/just-the-docs/pulls)
|
||||
- Ensure all CI tests pass
|
||||
- Await code review
|
||||
- Bump the version number in `just-the-docs.gemspec` and `package.json` according to [semantic versioning](https://semver.org/).
|
||||
|
||||
10
_config.yml
10
_config.yml
@ -16,7 +16,7 @@
|
||||
title: Just the Docs
|
||||
description: A Jekyll theme for documentation
|
||||
baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
|
||||
url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
|
||||
permalink: pretty
|
||||
exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"
|
||||
@ -65,7 +65,7 @@ heading_anchors: true
|
||||
# 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
|
||||
@ -81,7 +81,7 @@ nav_sort: case_sensitive # Capital letters sorted before lowercase
|
||||
back_to_top: true
|
||||
back_to_top_text: "Back to top"
|
||||
|
||||
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/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
|
||||
@ -92,8 +92,8 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
|
||||
# Footer "Edit this page on GitHub" link text
|
||||
gh_edit_link: true # show or hide edit this page link
|
||||
gh_edit_link_text: "Edit this page on GitHub"
|
||||
gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
|
||||
gh_edit_branch: "master" # the branch that your docs is served from
|
||||
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
|
||||
gh_edit_branch: "main" # the branch that your docs is served from
|
||||
# gh_edit_source: docs # the source that your files originate from
|
||||
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
|
||||
|
||||
|
||||
@ -66,7 +66,7 @@ layout: table_wrappers
|
||||
{% endif %}
|
||||
</nav>
|
||||
<footer class="site-footer">
|
||||
This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
|
||||
This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
|
||||
</footer>
|
||||
</div>
|
||||
<div class="main" id="top">
|
||||
|
||||
BIN
assets/images/large-image.jpg
Normal file
BIN
assets/images/large-image.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 532 KiB |
BIN
assets/images/small-image.jpg
Normal file
BIN
assets/images/small-image.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
@ -7,8 +7,7 @@ nav_order: 2
|
||||
# Configuration
|
||||
{: .no_toc }
|
||||
|
||||
|
||||
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's _config.yml file.
|
||||
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
## Table of contents
|
||||
@ -19,9 +18,7 @@ Just the Docs has some specific configuration parameters that can be defined in
|
||||
|
||||
---
|
||||
|
||||
|
||||
View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
|
||||
|
||||
View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example.
|
||||
|
||||
## Site logo
|
||||
|
||||
@ -68,7 +65,7 @@ search:
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"Just the Docs on GitHub":
|
||||
- "//github.com/pmarsceill/just-the-docs"
|
||||
- "//github.com/just-the-docs/just-the-docs"
|
||||
|
||||
# Makes Aux links open in a new tab. Default is false
|
||||
aux_links_new_tab: false
|
||||
@ -91,7 +88,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/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
|
||||
@ -100,8 +97,8 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
|
||||
# Footer "Edit this page on GitHub" link text
|
||||
gh_edit_link: true # show or hide edit this page link
|
||||
gh_edit_link_text: "Edit this page on GitHub."
|
||||
gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
|
||||
gh_edit_branch: "master" # the branch that your docs is served from
|
||||
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
|
||||
gh_edit_branch: "main" # the branch that your docs is served from
|
||||
# gh_edit_source: docs # the source that your files originate from
|
||||
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
|
||||
```
|
||||
@ -111,7 +108,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie
|
||||
- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format
|
||||
- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
|
||||
- `gh_edit_repository` is the URL of the project's GitHub repository
|
||||
- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master`
|
||||
- `gh_edit_branch` is the branch that the docs site is served from; defaults to `main`
|
||||
- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
|
||||
- `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode
|
||||
|
||||
@ -121,6 +118,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 +152,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 +178,7 @@ just_the_docs:
|
||||
|
||||
You can reference multiple collections.
|
||||
This creates categories in the navigation with the configured names.
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
docs:
|
||||
@ -195,4 +195,3 @@ just_the_docs:
|
||||
tutorials:
|
||||
name: Tutorials
|
||||
```
|
||||
|
||||
|
||||
@ -16,6 +16,7 @@ nav_order: 6
|
||||
---
|
||||
|
||||
## Color schemes
|
||||
|
||||
{: .d-inline-block }
|
||||
|
||||
New
|
||||
@ -32,6 +33,7 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf
|
||||
# Color scheme supports "light" (default) and "dark"
|
||||
color_scheme: dark
|
||||
```
|
||||
|
||||
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
|
||||
|
||||
<script>
|
||||
@ -53,10 +55,10 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
|
||||
### Define a custom scheme
|
||||
|
||||
You can add custom schemes.
|
||||
If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
|
||||
If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
|
||||
where you override theme variables to change colors, fonts, spacing, etc.
|
||||
|
||||
Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_variables.scss) file.
|
||||
Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file.
|
||||
|
||||
For example, to change the link color from the purple default to blue, include the following inside your scheme file:
|
||||
|
||||
@ -73,6 +75,7 @@ Please use scheme files.
|
||||
### Use a custom scheme
|
||||
|
||||
To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file:
|
||||
|
||||
```yaml
|
||||
color_scheme: foo
|
||||
```
|
||||
@ -80,7 +83,7 @@ color_scheme: foo
|
||||
### Switchable custom scheme
|
||||
|
||||
If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name)
|
||||
with the following content:`
|
||||
with the following content:
|
||||
|
||||
{% raw %}
|
||||
---
|
||||
@ -91,7 +94,7 @@ with the following content:`
|
||||
This allows you to switch the scheme via the following javascript.
|
||||
|
||||
```js
|
||||
jtd.setTheme('foo');
|
||||
jtd.setTheme("foo")
|
||||
```
|
||||
|
||||
## Override and completely custom styles
|
||||
@ -109,7 +112,13 @@ For example, if you'd like to add your own styles for printing a page, you could
|
||||
```scss
|
||||
// Print-only styles.
|
||||
@media print {
|
||||
.side-bar, .page-header { display: none; }
|
||||
.main-content { max-width: auto; margin: 1em;}
|
||||
.side-bar,
|
||||
.page-header {
|
||||
display: none;
|
||||
}
|
||||
.main-content {
|
||||
max-width: auto;
|
||||
margin: 1em;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@ -120,12 +120,13 @@ end
|
||||
|
||||
### 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).
|
||||
|
||||
### Definition lists can be used with HTML syntax.
|
||||
|
||||
@ -168,7 +169,7 @@ Term2
|
||||
|
||||
: Second description of Term1 and Term2,
|
||||
possibly more than one line
|
||||
|
||||
|
||||
### More code
|
||||
|
||||
```
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -5,13 +5,15 @@ nav_order: 7
|
||||
---
|
||||
|
||||
# Search
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
## Table of contents
|
||||
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
@ -76,7 +78,7 @@ To allow search for hyphenated words:
|
||||
search.tokenizer_separator: /[\s/]+/
|
||||
```
|
||||
|
||||
### Display URL in search results
|
||||
### Display URL in search results
|
||||
|
||||
```yaml
|
||||
# Display the relative url in search results
|
||||
@ -94,13 +96,13 @@ The search button displays in the bottom right corner of the screen and triggers
|
||||
search.button: true
|
||||
```
|
||||
|
||||
|
||||
## Hiding pages from search
|
||||
|
||||
Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
|
||||
To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
|
||||
|
||||
#### Example
|
||||
|
||||
{: .no_toc }
|
||||
|
||||
```yaml
|
||||
@ -110,8 +112,8 @@ title: Page not found
|
||||
nav_exclude: true
|
||||
search_exclude: true
|
||||
---
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
## Generate search index when used as a gem
|
||||
|
||||
@ -124,4 +126,4 @@ $ bundle exec just-the-docs rake search:init
|
||||
```
|
||||
|
||||
This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index.
|
||||
Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/master/assets/js/zzzz-search-data.json).
|
||||
Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).
|
||||
|
||||
58
index.md
58
index.md
@ -6,13 +6,13 @@ description: "Just the Docs is a responsive Jekyll theme with built-in search th
|
||||
permalink: /
|
||||
---
|
||||
|
||||
# Focus on writing good documentation
|
||||
# Focus on writing good documentation.
|
||||
{: .fs-9 }
|
||||
|
||||
Just the Docs gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable and hosted on GitHub Pages.
|
||||
{: .fs-6 .fw-300 }
|
||||
|
||||
[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
|
||||
[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/just-the-docs/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
|
||||
|
||||
---
|
||||
|
||||
@ -25,37 +25,43 @@ Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generat
|
||||
### Quick start: Use as a GitHub Pages remote theme
|
||||
|
||||
1. Add Just the Docs to your Jekyll site's `_config.yml` as a [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/)
|
||||
|
||||
```yaml
|
||||
remote_theme: pmarsceill/just-the-docs
|
||||
remote_theme: just-the-docs/just-the-docs
|
||||
```
|
||||
|
||||
<small>You must have GitHub Pages enabled on your repo, one or more Markdown files, and a `_config.yml` file. [See an example repository](https://github.com/pmarsceill/jtd-remote)</small>
|
||||
|
||||
### Local installation: Use the gem-based theme
|
||||
|
||||
1. Install the Ruby Gem
|
||||
```bash
|
||||
$ gem install just-the-docs
|
||||
```
|
||||
```yaml
|
||||
# .. or add it to your your Jekyll site’s Gemfile
|
||||
gem "just-the-docs"
|
||||
```
|
||||
```bash
|
||||
$ gem install just-the-docs
|
||||
```
|
||||
```yaml
|
||||
# .. or add it to your your Jekyll site’s Gemfile
|
||||
gem "just-the-docs"
|
||||
```
|
||||
|
||||
2. Add Just the Docs to your Jekyll site’s `_config.yml`
|
||||
```yaml
|
||||
theme: "just-the-docs"
|
||||
```
|
||||
```yaml
|
||||
theme: "just-the-docs"
|
||||
```
|
||||
|
||||
3. _Optional:_ Initialize search data (creates `search-data.json`)
|
||||
```bash
|
||||
$ bundle exec just-the-docs rake search:init
|
||||
```
|
||||
```bash
|
||||
$ bundle exec just-the-docs rake search:init
|
||||
```
|
||||
|
||||
3. Run you local Jekyll server
|
||||
```bash
|
||||
$ jekyll serve
|
||||
```
|
||||
```bash
|
||||
# .. or if you're using a Gemfile (bundler)
|
||||
$ bundle exec jekyll serve
|
||||
```
|
||||
```bash
|
||||
$ jekyll serve
|
||||
```
|
||||
```bash
|
||||
# .. or if you're using a Gemfile (bundler)
|
||||
$ bundle exec jekyll serve
|
||||
```
|
||||
|
||||
4. Point your web browser to [http://localhost:4000](http://localhost:4000)
|
||||
|
||||
If you're hosting your site on GitHub Pages, [set up GitHub Pages and Jekyll locally](https://help.github.com/en/articles/setting-up-your-github-pages-site-locally-with-jekyll) so that you can more easily work in your development environment.
|
||||
@ -72,12 +78,12 @@ Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](htt
|
||||
|
||||
### License
|
||||
|
||||
Just the Docs is distributed by an [MIT license](https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt).
|
||||
Just the Docs is distributed by an [MIT license](https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt).
|
||||
|
||||
### Contributing
|
||||
|
||||
When contributing to this repository, please first discuss the change you wish to make via issue,
|
||||
email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in [our GitHub repo](https://github.com/pmarsceill/just-the-docs#contributing).
|
||||
email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in [our GitHub repo](https://github.com/just-the-docs/just-the-docs#contributing).
|
||||
|
||||
#### Thank you to the contributors of Just the Docs!
|
||||
|
||||
@ -93,4 +99,4 @@ email, or any other method with the owners of this repository before making a ch
|
||||
|
||||
Just the Docs is committed to fostering a welcoming community.
|
||||
|
||||
[View our Code of Conduct](https://github.com/pmarsceill/just-the-docs/tree/master/CODE_OF_CONDUCT.md) on our GitHub repository.
|
||||
[View our Code of Conduct](https://github.com/just-the-docs/just-the-docs/tree/main/CODE_OF_CONDUCT.md) on our GitHub repository.
|
||||
|
||||
@ -7,13 +7,13 @@ Gem::Specification.new do |spec|
|
||||
spec.email = ["patrick.marsceill@gmail.com"]
|
||||
|
||||
spec.summary = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.}
|
||||
spec.homepage = "https://github.com/pmarsceill/just-the-docs"
|
||||
spec.homepage = "https://github.com/just-the-docs/just-the-docs"
|
||||
spec.license = "MIT"
|
||||
|
||||
spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) }
|
||||
spec.executables << 'just-the-docs'
|
||||
|
||||
spec.add_development_dependency "bundler", "~> 2.1.4"
|
||||
spec.add_development_dependency "bundler", "~> 2.3.5"
|
||||
spec.add_runtime_dependency "jekyll", ">= 3.8.5"
|
||||
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0"
|
||||
spec.add_runtime_dependency "rake", ">= 12.3.1", "< 13.1.0"
|
||||
|
||||
14
package-lock.json
generated
14
package-lock.json
generated
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "just-the-docs",
|
||||
"version": "0.3.2",
|
||||
"version": "0.3.3",
|
||||
"lockfileVersion": 1,
|
||||
"requires": true,
|
||||
"dependencies": {
|
||||
@ -5938,9 +5938,9 @@
|
||||
}
|
||||
},
|
||||
"y18n": {
|
||||
"version": "3.2.1",
|
||||
"resolved": "https://registry.npmjs.org/y18n/-/y18n-3.2.1.tgz",
|
||||
"integrity": "sha1-bRX7qITAhnnA136I53WegR4H+kE=",
|
||||
"version": "3.2.2",
|
||||
"resolved": "https://registry.npmjs.org/y18n/-/y18n-3.2.2.tgz",
|
||||
"integrity": "sha512-uGZHXkHnhF0XeeAPgnKfPv1bgKAYyVvmNL1xlKsPYZPaIHxGti2hHqvOCQv71XMsLxu1QjergkqogUnms5D3YQ==",
|
||||
"dev": true
|
||||
},
|
||||
"yargs": {
|
||||
@ -6517,9 +6517,9 @@
|
||||
"dev": true
|
||||
},
|
||||
"y18n": {
|
||||
"version": "4.0.0",
|
||||
"resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.0.tgz",
|
||||
"integrity": "sha512-r9S/ZyXu/Xu9q1tYlpsLIsa3EeLXXk0VwlxqTcFRfg9EhMW+17kbt9G0NrgCmhGb5vT2hyhJZLfDGx+7+5Uj/w==",
|
||||
"version": "4.0.1",
|
||||
"resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.1.tgz",
|
||||
"integrity": "sha512-wNcy4NvjMYL8gogWWYAO7ZFWFfHcbdbE57tZO8e4cbpj8tfUcwrwqSl3ad8HxpYWCdXcJUCeKKZS62Av1affwQ==",
|
||||
"dev": true
|
||||
},
|
||||
"yaml": {
|
||||
|
||||
@ -2,9 +2,9 @@
|
||||
"name": "just-the-docs",
|
||||
"version": "0.3.3",
|
||||
"description": "A modern Jekyll theme for documentation",
|
||||
"repository": "pmarsceill/just-the-docs",
|
||||
"repository": "just-the-docs/just-the-docs",
|
||||
"license": "MIT",
|
||||
"bugs": "https://github.com/pmarsceill/just-the-docs/issues",
|
||||
"bugs": "https://github.com/just-the-docs/just-the-docs/issues",
|
||||
"devDependencies": {
|
||||
"stylelint": "^13.7.2",
|
||||
"@primer/css": "^15.2.0",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user