Skip to content
Snippets Groups Projects
Commit 2aa98150 authored by Patrick Marsceill's avatar Patrick Marsceill Committed by GitHub
Browse files

Update to new repo path

parent e8424986
No related branches found
No related tags found
No related merge requests found
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
<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%22Master+branch+CI%22"><img src="https://github.com/just-the-docs/just-the-docs/workflows/Master%20branch%20CI/badge.svg" alt="Build status"></a>
</p>
<br><br>
<p align="center">
......@@ -43,11 +43,11 @@ Alternatively, you can run it inside Docker while developing your site
## 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/).
......
......@@ -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 &copy; 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 &copy; 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
......@@ -92,7 +92,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
......
......@@ -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">
......
......@@ -5,23 +5,22 @@ nav_order: 2
---
# Configuration
{: .no_toc }
{: .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 &copy; 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 &copy; 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
......
......@@ -7,12 +7,13 @@ permalink: /
---
# 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 +26,49 @@ 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"
```
2. Add Just the Docs to your Jekyll site’s `_config.yml`
```yaml
theme: "just-the-docs"
```
3. _Optional:_ Initialize search data (creates `search-data.json`)
```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
```
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 +85,12 @@ Just the Docs is &copy; 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/master/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 +106,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/master/CODE_OF_CONDUCT.md) on our GitHub repository.
......@@ -7,7 +7,7 @@ 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) }
......
{
"name": "just-the-docs",
"version": "0.3.2",
"version": "0.3.3",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
......
......@@ -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",
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment