Skip to content
Snippets Groups Projects
Commit 301a4ab6 authored by Silvio Giebl's avatar Silvio Giebl
Browse files

Merge branch 'improvement/navigation-merged' into improvement/search-button-merged 

# Conflicts:
#	_layouts/default.html
parents bc1cbc1a fd911409
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 173 additions and 67 deletions
README.md
+ 1
− 1
View file @ 301a4ab6
......@@ -4,7 +4,7 @@
<br><br>
<p align="center">
<h1 align="center">Just the Docs</h1>
<p align="center">A modern, high customizable, responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
<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>
<br><br><br>
</p>
......
_config.yml
+ 7
− 1
View file @ 301a4ab6
......@@ -21,9 +21,15 @@ url: "https://pmarsceill.github.io" # the base hostname & protocol for your site
permalink: pretty
exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
# Set a path/url to a logo that will be displayed instead of the title
#logo: "/assets/images/just-the-docs.png"
# Enable or disable the site search
search_enabled: true
# Set the search token separator for hyphenated-word search:
search_tokenizer_separator: /[\s/]+/
# Enable or disable heading anchors
heading_anchors: true
......@@ -50,5 +56,5 @@ compress_html:
comments: all
endings: all
startings: []
blank_lines: false
blanklines: false
profile: false
_includes/title.html
+ 5
− 1
View file @ 301a4ab6
{{ site.title }}
\ No newline at end of file
{% if site.logo %}
<div class="site-logo"></div>
{% else %}
{{ site.title }}
{% endif %}
_layouts/default.html
+ 6
− 2
View file @ 301a4ab6
......@@ -8,6 +8,10 @@ layout: table_wrappers
{% include head.html %}
<body>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="link" viewBox="0 0 16 16">
<title>Link</title>
<path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
</symbol>
<symbol id="search" viewBox="0 0 24 24">
<title>Menu</title>
<path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/><path d="M0 0h24v24H0z" fill="none"/>
......@@ -77,7 +81,7 @@ layout: table_wrappers
{% endunless %}
<div id="main-content" class="main-content" role="main">
{% if site.heading_anchors != false %}
{% include vendor/anchor_headings.html html=content beforeHeading = "true" anchorBody="<svg class=\"d-inline-block v-align-middle\" viewBox=\"0 0 16 16\" version=\"1.1\" width=\"18\" height=\"18\" aria-hidden=\"true\"><path fill-rule=\"evenodd\" d=\"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z\"></path></svg>" anchorClass="anchor-heading" %}
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#link\"></use></svg>" anchorClass="anchor-heading" %}
{% else %}
{{ content }}
{% endif %}
......@@ -90,7 +94,7 @@ layout: table_wrappers
{% for child in children_list %}
{% if child.parent == page.title and child.title != page.title %}
<li>
<a href="{{ child.url | absolute_url }}">{{ child.title }}</a>
<a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
</li>
{% endif %}
{% endfor %}
......
_sass/base.scss
+ 2
− 1
View file @ 301a4ab6
......@@ -88,7 +88,8 @@ code {
line-height: $body-line-height;
}
figure {
figure,
pre {
margin: 0;
}
......
_sass/content.scss
+ 15
− 4
View file @ 301a4ab6
......@@ -116,26 +116,37 @@
.anchor-heading {
position: absolute;
right: -$sp-3;
right: -$sp-4;
width: $sp-5;
height: 100%;
padding-right: $sp-1;
padding-left: $sp-1;
overflow: visible;
fill: $link-color;
visibility: hidden;
@include mq(md) {
right: auto;
left: -$sp-5;
}
svg {
display: inline-block;
width: 100%;
height: 100%;
fill: $link-color;
visibility: hidden;
}
}
.anchor-heading:hover,
h1:hover > .anchor-heading,
h2:hover > .anchor-heading,
h3:hover > .anchor-heading,
h4:hover > .anchor-heading,
h5:hover > .anchor-heading,
h6:hover > .anchor-heading {
visibility: visible;
svg {
visibility: visible;
}
}
h1,
......
_sass/layout.scss
+ 19
− 3
View file @ 301a4ab6
......@@ -123,12 +123,12 @@
.site-header {
display: flex;
min-height: $header-height;
align-items: center;
@include mq(md) {
z-index: 101;
height: $header-height;
min-height: $header-height;
max-height: $header-height;
border-bottom: $border $border-color;
}
......@@ -140,10 +140,26 @@
display: flex;
height: 100%;
align-items: center;
padding-top: $gutter-spacing-sm;
padding-bottom: $gutter-spacing-sm;
padding-top: $sp-3;
padding-bottom: $sp-3;
color: $body-heading-color;
@include fs-6;
@include mq(md) {
padding-top: $sp-2;
padding-bottom: $sp-2;
}
}
@if variable-exists(logo) {
.site-logo {
width: 100%;
height: 100%;
background-image: url($logo);
background-repeat: no-repeat;
background-position: left center;
background-size: contain;
}
}
.site-button {
......
_sass/overrides.scss 0 → 100644
+ 3
− 0
View file @ 301a4ab6
//
// Custom overrides from a user.
//
_sass/utilities/_lists.scss
+ 7
− 1
View file @ 301a4ab6
......@@ -2,10 +2,16 @@
// Utility classes for lists
//
// stylelint-disable primer/selector-no-utility, primer/no-override
// stylelint-disable primer/selector-no-utility, primer/no-override, selector-max-type
.list-style-none {
padding: 0 !important;
margin: 0 !important;
list-style: none !important;
li {
&::before {
display: none !important;
}
}
}
assets/css/dark-mode-preview.scss
+ 4
− 0
View file @ 301a4ab6
......@@ -3,6 +3,10 @@
# only Main files contain this front matter, not partials.
---
{% if site.logo %}
$logo: "{{ site.logo | absolute_url }}";
{% endif %}
//
// Import external dependencies
//
......
assets/css/just-the-docs.scss
+ 5
− 0
View file @ 301a4ab6
......@@ -3,6 +3,10 @@
# only Main files contain this front matter, not partials.
---
{% if site.logo %}
$logo: "{{ site.logo | absolute_url }}";
{% endif %}
//
// Import external dependencies
//
......@@ -42,3 +46,4 @@
@import "./tables";
@import "./code";
@import "./utilities/utilities";
@import "./overrides";
assets/js/dark-mode-preview.js 0 → 100644
+ 23
− 0
View file @ 301a4ab6
document.addEventListener("DOMContentLoaded", function(){
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')
const buttonCopy = ['Return to the light side', 'Preview dark color scheme']
const updateButtonText = function(toggleDarkMode) {
toggleDarkMode.textContent === buttonCopy[0] ?
toggleDarkMode.textContent = buttonCopy[1] :
toggleDarkMode.textContent = buttonCopy[0]
}
jtd.addEvent(toggleDarkMode, 'click', function(){
if (cssFile.getAttribute('href') === originalCssRef) {
cssFile.setAttribute('href', darkModeCssRef)
updateButtonText(toggleDarkMode)
} else {
cssFile.setAttribute('href', originalCssRef)
updateButtonText(toggleDarkMode)
}
})
})
assets/js/just-the-docs.js
+ 6
− 1
View file @ 301a4ab6
......@@ -75,8 +75,13 @@ function initSearch() {
if (request.status >= 200 && request.status < 400) {
// Success!
var data = JSON.parse(request.responseText);
{% if site.search_tokenizer_separator != nil %}
lunr.tokenizer.separator = {{ site.search_tokenizer_separator }}
{% else %}
lunr.tokenizer.separator = /[\s\-/]+/
{% endif %}
var index = lunr(function () {
this.ref('id');
this.field('title', { boost: 200 });
......
assets/js/search-data.json
+ 4
− 3
View file @ 301a4ab6
---
---
{
{% for page in site.html_pages %}{% if page.search_exclude != true %}"{{ 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: '&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 }}"
}{% unless forloop.last %},{% endunless %}
}{% assign comma = true %}
{% endif %}{% endfor %}
}
}
\ No newline at end of file
docs/configuration.md
+ 19
− 22
View file @ 301a4ab6
......@@ -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
```
......@@ -65,20 +75,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.
......
docs/customization.md
+ 18
− 14
View file @ 301a4ab6
......@@ -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;}
}
```
docs/navigation-structure.md
+ 3
− 6
View file @ 301a4ab6
......@@ -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
---
```
......
docs/search.md
+ 13
− 4
View file @ 301a4ab6
......@@ -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: '&amp;', '&' }}",
"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:
......
index.md
+ 11
− 1
View file @ 301a4ab6
......@@ -20,7 +20,7 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
### Dependencies
Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [quick start guide](https://jekyllrb.com/docs/) for more information. Just the Docs requires no special Jekyll plugins and can run on GitHub Pages' standard Jekyll compiler.
Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [quick start guide](https://jekyllrb.com/docs/) for more information. Just the Docs requires no special plugins and can run on GitHub Pages' standard Jekyll compiler. The [Jekyll SEO Tag plugin](https://github.com/jekyll/jekyll-seo-tag) is included by default (no need to run any special installation) to inject SEO and open graph metadata on docs pages. For information on how to configure SEO and open graph metadata visit the [Jekyll SEO Tag usage guide](https://jekyll.github.io/jekyll-seo-tag/usage/).
### Quick start: Use as a GitHub Pages remote theme
......@@ -79,6 +79,16 @@ Just the Docs is distributed by an [MIT license](https://github.com/pmarsceill/j
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).
#### Thank you to the contributors of Just the Docs!
<ul class="list-style-none">
{% for contributor in site.github.contributors %}
<li class="d-inline-block mr-1">
<a href="{{ contributor.html_url }}"><img src="{{ contributor.avatar_url }}" width="32" height="32" alt="{{ contributor.login }}"/></a>
</li>
{% endfor %}
</ul>
### Code of Conduct
Just the Docs is committed to fostering a welcoming community.
......
just-the-docs.gemspec
+ 2
− 2
View file @ 301a4ab6
......@@ -2,11 +2,11 @@
Gem::Specification.new do |spec|
spec.name = "just-the-docs"
spec.version = "0.2.6"
spec.version = "0.2.7"
spec.authors = ["Patrick Marsceill"]
spec.email = ["patrick.marsceill@gmail.com"]
spec.summary = %q{A modern, high customizable, responsive Jekyll theme for documention with built-in search.}
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.license = "MIT"
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment