1
0
mirror of https://github.com/thangisme/notes.git synced 2024-10-31 16:47:33 -04:00

Merge pull request #23 from pmarsceill/v0.2.0

v0.2.0 release
This commit is contained in:
Patrick Marsceill 2018-11-19 16:34:46 -05:00 committed by GitHub
commit 21990474d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 392 additions and 95 deletions

View File

@ -1,6 +1,7 @@
{ {
"ignoreFiles" : [ "ignoreFiles" : [
"assets/css/just-the-docs.scss", "assets/css/just-the-docs.scss",
"assets/css/dark-mode-preview.scss",
"_sass/vendor/**/*.scss" "_sass/vendor/**/*.scss"
], ],
"extends": [ "extends": [

View File

@ -6,6 +6,7 @@ env:
install: install:
- npm install - npm install
- gem install bundler --version '>=1.17.1'
- bundle install - bundle install
script: script:

View File

@ -28,3 +28,6 @@ search_enabled: true
aux_links: aux_links:
"Just the Docs on GitHub": "Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs" - "//github.com/pmarsceill/just-the-docs"
# Color scheme currently only supports "dark" or nil (default)
color_scheme: nil

View File

@ -1,24 +1,44 @@
<nav> <nav>
<ul class="navigation-list"> <ul class="navigation-list">
{% assign pages_list = site.html_pages | sort:"nav_order" %} {% assign pages_list = site.html_pages | sort:"nav_order" %}
{% for node in pages_list %} {% for node in pages_list %}
<li class="navigation-list-item{% if page.url == node.url %} active{% endif %} js-side-nav-item"> {% unless node.nav_exclude %}
{% if node.parent == nil or node.has_children == true %} {% if node.parent == nil %}
<a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url or (page.parent != nil and page.parent == node.parent) %} active{% endif %}">{{ node.title }}</a> <li class="navigation-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
{% if (node.has_children == true and node.parent == page.parent) %} {% if page.parent == node.title or page.grand_parent == node.title %}
{% assign children_list = site.html_pages | sort:"nav_order" %} {% assign first_level_url = node.url | absolute_url %}
<ul class="navigation-list-child-list"> {% endif %}
{% for child in children_list %} <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
{% if child.parent == node.parent and child.title != node.title %} {% if node.has_children %}
<li class="navigation-list-item {% if page.url == child.url %} active{% endif %}"> {% assign children_list = site.html_pages | sort:"nav_order" %}
<a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a> <ul class="navigation-list-child-list ">
</li> {% for child in children_list %}
{% endif %} {% if child.parent == node.title %}
{% endfor %} <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
</ul> {% if page.url == child.url or page.parent == child.title %}
{% endif %} {% assign second_level_url = child.url | absolute_url %}
{% endif %}
<a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
{% if child.has_children %}
{% assign grand_children_list = site.html_pages | sort:"nav_order" %}
<ul class="navigation-list-child-list">
{% for grand_child in grand_children_list %}
{% if grand_child.parent == child.title %}
<li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
<a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
</li>
{% endif %}
{% endfor %}
</ul>
{% endif %}
</li>
{% endif %}
{% endfor %}
</ul>
{% endif %}
</li>
{% endif %} {% endif %}
</li> {% endunless %}
{% endfor %} {% endfor %}
</ul> </ul>
</nav> </nav>

View File

@ -5,7 +5,7 @@
<div class="page-wrap"> <div class="page-wrap">
<div class="side-bar"> <div class="side-bar">
<a href="{{ site.url }}{{ site.baseurl }}" class="site-title fs-6 text-grey-dk-300 lh-tight">{{ site.title }}</a> <a href="{{ site.url }}{{ site.baseurl }}" class="site-title fs-6 lh-tight">{{ site.title }}</a>
<span class="fs-3"><button class="js-main-nav-trigger navigation-list-toggle btn btn-outline" type="button" data-text-toggle="Hide">Menu</button></span> <span class="fs-3"><button class="js-main-nav-trigger navigation-list-toggle btn btn-outline" type="button" data-text-toggle="Hide">Menu</button></span>
<div class="navigation main-nav js-main-nav"> <div class="navigation main-nav js-main-nav">
{% include nav.html %} {% include nav.html %}
@ -37,10 +37,15 @@
</div> </div>
<div class="main-content"> <div class="main-content">
{% unless page.url == "/" %} {% unless page.url == "/" %}
{% if page.parent != nil and page.parent != page.title %} {% if page.parent %}
<nav class="breadcrumb-nav"> <nav class="breadcrumb-nav">
<ol class="breadcrumb-nav-list"> <ol class="breadcrumb-nav-list">
<li class="breadcrumb-nav-list-item"><a href="{{ site.url }}{{ site.baseurl }}/{{ page.parent | slugify }}">{{ page.parent }}</a></li> {% if page.grand_parent %}
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
{% else %}
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
{% endif %}
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li> <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
</ol> </ol>
</nav> </nav>

View File

@ -7,6 +7,11 @@
box-sizing: border-box; box-sizing: border-box;
} }
::selection {
color: $white;
background: $link-color;
}
html { html {
@include fs-4; @include fs-4;
} }
@ -16,6 +21,7 @@ body {
font-size: inherit; font-size: inherit;
line-height: $body-line-height; line-height: $body-line-height;
color: $body-text-color; color: $body-text-color;
background-color: $body-background-color;
} }
p, p,
@ -64,7 +70,7 @@ a {
a:not([class]) { a:not([class]) {
text-decoration: none; text-decoration: none;
background-image: linear-gradient($grey-lt-100 0%, $grey-lt-100 100%); background-image: linear-gradient($border-color 0%, $border-color 100%);
background-repeat: repeat-x; background-repeat: repeat-x;
background-position: 0 100%; background-position: 0 100%;
background-size: 1px 1px; background-size: 1px 1px;
@ -99,6 +105,6 @@ hr {
height: 1px; height: 1px;
padding: 0; padding: 0;
margin: $sp-6 0; margin: $sp-6 0;
background-color: $grey-lt-100; background-color: $border-color;
border: 0; border: 0;
} }

View File

@ -15,11 +15,11 @@
font-size: inherit; font-size: inherit;
font-weight: 500; font-weight: 500;
line-height: 1.5; line-height: 1.5;
color: $purple-200; color: $link-color;
text-decoration: none; text-decoration: none;
vertical-align: baseline; vertical-align: baseline;
cursor: pointer; cursor: pointer;
background-color: #f7f7f7; background-color: $base-button-color;
border-width: 0; border-width: 0;
border-radius: 3px; border-radius: 3px;
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
@ -38,7 +38,7 @@
&:hover, &:hover,
&.zeroclipboard-is-hover { &.zeroclipboard-is-hover {
color: $purple-300; color: darken($link-color, 2%);
} }
&:hover, &:hover,
@ -46,13 +46,13 @@
&.zeroclipboard-is-hover, &.zeroclipboard-is-hover,
&.zeroclipboard-is-active { &.zeroclipboard-is-active {
text-decoration: none; text-decoration: none;
background-color: #f4f4f4; background-color: darken($base-button-color, 1%);
} }
&:active, &:active,
&.selected, &.selected,
&.zeroclipboard-is-active { &.zeroclipboard-is-active {
background-color: #ededed; background-color: darken($base-button-color, 3%);
background-image: none; background-image: none;
box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.15); box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.15);
} }
@ -75,7 +75,7 @@
} }
.btn-outline { .btn-outline {
color: $blue-100; color: $link-color;
background: transparent; background: transparent;
box-shadow: inset 0 0 0 2px $grey-lt-300; box-shadow: inset 0 0 0 2px $grey-lt-300;
@ -83,7 +83,7 @@
&:active, &:active,
&.zeroclipboard-is-hover, &.zeroclipboard-is-hover,
&.zeroclipboard-is-active { &.zeroclipboard-is-active {
color: $grey-dk-100; color: darken($link-color, 4%);
text-decoration: none; text-decoration: none;
background-color: transparent; background-color: transparent;
box-shadow: inset 0 0 0 3px $grey-lt-300; box-shadow: inset 0 0 0 3px $grey-lt-300;
@ -101,6 +101,10 @@
} }
} }
.btn-primary {
@include btn-color($white, $btn-primary-color);
}
.btn-purple { .btn-purple {
@include btn-color($white, $purple-100); @include btn-color($white, $purple-100);
} }

View File

@ -6,15 +6,15 @@
code { code {
padding: 0.2em 0.15em; padding: 0.2em 0.15em;
font-weight: 400; font-weight: 400;
background-color: $grey-lt-000; background-color: $code-background-color;
border: $border $border-color; border: $border $border-color;
border-radius: $border-radius; border-radius: $border-radius;
} }
.highlight { pre.highlight {
padding: $sp-3; padding: $sp-3;
margin-bottom: 0; margin-bottom: 0;
background-color: $grey-lt-000; background-color: $code-background-color;
code { code {
padding: 0; padding: 0;

View File

@ -0,0 +1,14 @@
$body-background-color: $grey-dk-300;
$sidebar-color: $grey-dk-300;
$border-color: $grey-dk-200;
$body-text-color: $grey-lt-300;
$body-heading-color: $grey-lt-000;
$nav-child-link-color: $grey-dk-000;
$link-color: $blue-000;
$btn-primary-color: $blue-200;
$base-button-color: $grey-dk-250;
$code-background-color: $grey-dk-250;

View File

@ -4,6 +4,12 @@
// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type
.page-content { .page-content {
a {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
ul, ul,
ol { ol {
padding-left: 1.5em; padding-left: 1.5em;

View File

@ -17,6 +17,7 @@
// $grey-dk-000: #959396; // $grey-dk-000: #959396;
// $grey-dk-100: #5c5962; // $grey-dk-100: #5c5962;
// $grey-dk-200: #44434d; // $grey-dk-200: #44434d;
// $grey-dk-250: #302d36 !default;
// $grey-dk-300: #27262b; // $grey-dk-300: #27262b;
// //
// $grey-lt-000: #f5f6fa; // $grey-lt-000: #f5f6fa;
@ -39,9 +40,16 @@
// $green-200: #009c7b; // $green-200: #009c7b;
// $green-300: #026e57; // $green-300: #026e57;
// //
// $body-text-color: $grey-dk-100; // $body-background-color: $white !default;
// $body-heading-color: $grey-dk-300; // $sidebar-color: $grey-lt-000 !default;
// $link-color: $purple-000; // $code-background-color: $grey-lt-000 !default;
// $body-text-color: $grey-dk-100 !default;
// $body-heading-color: $grey-dk-300 !default;
// $nav-child-link-color: $grey-dk-100 !default;
// $link-color: $purple-000 !default;
// $btn-primary-color: $purple-100 !default;
// $base-button-color: #f7f7f7 !default;
// //
// // // //
// // Media queries in pixels // // Media queries in pixels

View File

@ -21,7 +21,7 @@
flex-wrap: wrap; flex-wrap: wrap;
padding-top: $gutter-spacing-sm; padding-top: $gutter-spacing-sm;
padding-bottom: $gutter-spacing-sm; padding-bottom: $gutter-spacing-sm;
background-color: $grey-lt-000; background-color: $sidebar-color;
@include mq(md) { @include mq(md) {
flex-wrap: nowrap; flex-wrap: nowrap;
@ -75,10 +75,10 @@
} }
.page-header { .page-header {
background-color: $grey-lt-000; background-color: $sidebar-color;
@include mq(md) { @include mq(md) {
background-color: $white; background-color: $body-background-color;
} }
.main-content { .main-content {
@ -138,6 +138,6 @@ body {
position: static; position: static;
align-self: flex-end; align-self: flex-end;
justify-self: end; justify-self: end;
background-color: $grey-lt-000; background-color: $sidebar-color;
} }
} }

View File

@ -5,7 +5,8 @@
.site-title { .site-title {
display: block; display: block;
flex: 1 1 auto; flex: 1 1 auto;
background-color: $grey-lt-000; color: $body-heading-color;
background-color: $sidebar-color;
@include mq(md) { @include mq(md) {
position: absolute; position: absolute;
@ -34,7 +35,7 @@
list-style: none; list-style: none;
.navigation-list-link { .navigation-list-link {
color: $grey-dk-100; color: $nav-child-link-color;
} }
.navigation-list-item { .navigation-list-item {
@ -44,13 +45,13 @@
position: absolute; position: absolute;
margin-top: 0.3em; margin-top: 0.3em;
margin-left: -0.8em; margin-left: -0.8em;
color: $grey-dk-000; color: rgba($body-text-color, 0.3);
content: "- "; content: "- ";
} }
&.active { &.active {
&::before { &::before {
color: $grey-dk-100; color: $body-text-color;
} }
} }
} }
@ -63,6 +64,16 @@
@include mq(md) { @include mq(md) {
@include fs-3; @include fs-3;
} }
.navigation-list-child-list {
display: none;
}
&.active {
.navigation-list-child-list {
display: block;
}
}
} }
.navigation-list-link { .navigation-list-link {
@ -72,7 +83,7 @@
&.active { &.active {
font-weight: 600; font-weight: 600;
color: $grey-dk-200; color: $body-heading-color;
text-decoration: none; text-decoration: none;
} }
} }
@ -101,6 +112,11 @@
} }
// Breadcrumb nav // Breadcrumb nav
.breadcrumb-nav {
@include mq(md) {
margin-top: -$sp-4;
}
}
.breadcrumb-nav-list { .breadcrumb-nav-list {
padding-left: 0; padding-left: 0;

View File

@ -39,20 +39,21 @@
display: block; display: block;
width: 300px; width: 300px;
margin-top: $gutter-spacing; margin-top: $gutter-spacing;
background: $white; background: lighten($body-background-color, 1%);
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.07), 0 4px 14px rgba(0, 0, 0, 0.05); box-shadow: 0 1px 3px rgba(0, 0, 0, 0.07), 0 4px 14px rgba(0, 0, 0, 0.05);
} }
} }
.search-input-wrap { .search-input-wrap {
display: flex; display: flex;
background-color: $white; background-color: $body-background-color;
} }
.search-input { .search-input {
width: 100%; width: 100%;
padding-top: $sp-1; padding-top: $sp-1;
padding-bottom: $sp-1; padding-bottom: $sp-1;
background-color: $body-background-color;
border-top: 0; border-top: 0;
border-right: 0; border-right: 0;
border-bottom: 0; border-bottom: 0;
@ -64,7 +65,7 @@
box-shadow: none; box-shadow: none;
+ .search-icon { + .search-icon {
fill: $purple-000; fill: $link-color;
} }
} }
@ -107,6 +108,7 @@
padding-left: $sp-3; padding-left: $sp-3;
&:hover { &:hover {
background-color: $grey-lt-000; color: $body-heading-color;
background-color: darken($body-background-color, 2%);
} }
} }

View File

@ -17,6 +17,7 @@ $white: #fff !default;
$grey-dk-000: #959396 !default; $grey-dk-000: #959396 !default;
$grey-dk-100: #5c5962 !default; $grey-dk-100: #5c5962 !default;
$grey-dk-200: #44434d !default; $grey-dk-200: #44434d !default;
$grey-dk-250: #302d36 !default;
$grey-dk-300: #27262b !default; $grey-dk-300: #27262b !default;
$grey-lt-000: #f5f6fa !default; $grey-lt-000: #f5f6fa !default;
@ -49,9 +50,16 @@ $red-100: #f96e65 !default;
$red-200: #e94c4c !default; $red-200: #e94c4c !default;
$red-300: #dd2e2e !default; $red-300: #dd2e2e !default;
$body-background-color: $white !default;
$sidebar-color: $grey-lt-000 !default;
$code-background-color: $grey-lt-000 !default;
$body-text-color: $grey-dk-100 !default; $body-text-color: $grey-dk-100 !default;
$body-heading-color: $grey-dk-300 !default; $body-heading-color: $grey-dk-300 !default;
$nav-child-link-color: $grey-dk-100 !default;
$link-color: $purple-000 !default; $link-color: $purple-000 !default;
$btn-primary-color: $purple-100 !default;
$base-button-color: #f7f7f7 !default;
// //
// Media queries in pixels // Media queries in pixels

View File

@ -25,7 +25,8 @@ td {
padding-right: $sp-3; padding-right: $sp-3;
padding-bottom: $sp-2; padding-bottom: $sp-2;
padding-left: $sp-3; padding-left: $sp-3;
border-bottom: $border $grey-lt-000; background-color: lighten($body-background-color, 2%);
border-bottom: $border rgba($border-color, 0.5);
border-left: $border $border-color; border-left: $border $border-color;
&:first-of-type { &:first-of-type {

View File

@ -16,6 +16,10 @@
color: $grey-dk-200 !important; color: $grey-dk-200 !important;
} }
.text-grey-dk-250 {
color: $grey-dk-250 !important;
}
.text-grey-dk-300 { .text-grey-dk-300 {
color: $grey-dk-300 !important; color: $grey-dk-300 !important;
} }
@ -130,6 +134,10 @@
background-color: $grey-dk-200 !important; background-color: $grey-dk-200 !important;
} }
.bg-grey-dk-250 {
background-color: $grey-dk-250 !important;
}
.bg-grey-dk-300 { .bg-grey-dk-300 {
background-color: $grey-dk-300 !important; background-color: $grey-dk-300 !important;
} }

View File

@ -0,0 +1,41 @@
---
# this ensures Jekyll reads the file to be transformed into CSS later
# only Main files contain this front matter, not partials.
---
//
// Import external dependencies
//
@import "./vendor/normalize.scss/normalize.scss";
//
// Import Just the docs scss
//
// Support
@import "./support/support";
//
// Import custom color scheme scss
//
@import "./color_schemes/dark.scss";
// Modules
@import "./base";
@import "./layout";
@import "./content";
@import "./navigation";
@import "./typography";
@import "./labels";
@import "./buttons";
@import "./search";
@import "./tables";
@import "./code";
@import "./utilities/utilities";
//
// Import custom overrides
//
@import "./custom/custom";

View File

@ -4,7 +4,7 @@
--- ---
// //
// Import dependancies // Import external dependencies
// //
@import "./vendor/normalize.scss/normalize.scss"; @import "./vendor/normalize.scss/normalize.scss";
@ -16,8 +16,13 @@
// Support // Support
@import "./support/support"; @import "./support/support";
// Custom overrides //
@import "./custom/custom"; // Import custom color scheme scss
//
{% if site.color_scheme == "dark" %}
@import "./color_schemes/dark.scss";
{% endif %}
// Modules // Modules
@import "./base"; @import "./base";
@ -31,3 +36,8 @@
@import "./tables"; @import "./tables";
@import "./code"; @import "./code";
@import "./utilities/utilities"; @import "./utilities/utilities";
//
// Import custom overrides
//
@import "./custom/custom";

View File

@ -6,7 +6,7 @@ nav_order: 2
# Configuration # Configuration
Just the Docs has some specific configuration parameters that can be definied in your Jekyll site's `config.yml` file. Just the Docs has some specific configuration parameters that can be definied in your Jekyll site's `_config.yml` file.
## Search enabled ## Search enabled
@ -23,3 +23,28 @@ aux_links:
"Just the Docs on GitHub": "Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs" - "//github.com/pmarsceill/just-the-docs"
``` ```
## Color scheme
```yml
# Color scheme currently only supports "dark" or nil (default)
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')
addEvent(toggleDarkMode, 'click', function(){
if (cssFile.getAttribute('href') === originalCssRef) {
cssFile.setAttribute('href', darkModeCssRef)
} else {
cssFile.setAttribute('href', originalCssRef)
}
})
</script>
See [Customization]({{site.baseurl }}{% link docs/customization.md %}) for more information.

View File

@ -15,11 +15,49 @@ nav_order: 6
--- ---
## Visual customization ## Color schemes
{: .d-inline-block :}
New
{: .label .label-green :}
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 }
```yml
# Color scheme currently only supports "dark" or nil (default)
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')
addEvent(toggleDarkMode, 'click', function(){
if (cssFile.getAttribute('href') === originalCssRef) {
cssFile.setAttribute('href', darkModeCssRef)
} else {
cssFile.setAttribute('href', originalCssRef)
}
})
</script>
## Specific visual customization
To customize your sites 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 out its line and change its value. To customize your sites 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 out its line and change its value.
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 `44`. Uncomment it out, and change it's value to our `$blue-000` variable, or another shade of your choosing. 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 out, and change it's value to our `$blue-000` variable, or another shade of your choosing.
#### Example
{: no_toc }
```scss ```scss
// ... // ...
@ -35,10 +73,3 @@ _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not
--- ---
## Themes
{: .d-inline-block :}
Coming soon
{: .label .label-yellow :}
Hard at work on a dark theme, and more.

View File

@ -17,16 +17,18 @@ nav_order: 5
## Main navigation ## Main navigation
The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (parent pages with children). The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
### Top level pages By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
By default, all pages will appear as top level pages in the main nav. ---
### Ordering pages ## Ordering pages
To specify a page order, use the `nav_order` variable in your pages' YAML front matter. To specify a page order, use the `nav_order` variable in your pages' YAML front matter.
#### Example
{: .no_toc }
```yaml ```yaml
--- ---
layout: default layout: default
@ -35,9 +37,27 @@ nav_order: 4
--- ---
``` ```
### Pages with children ---
Sometimes you will want to create a page with many children (a section). To accomplish this you need to a few things. First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the `./docs` directory and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives is an organization like: ## Excluding pages
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
---
layout: default
title: 404
nav_exclude: true
---
```
---
## Pages with children
Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the `./docs` directory and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives is an organization like:
``` ```
+-- .. +-- ..
@ -53,7 +73,7 @@ Sometimes you will want to create a page with many children (a section). To acco
| | +-- typography.md | | +-- typography.md
| | | |
| |-- utilities | |-- utilities
| | |-- utilities.md (parent page) | | |-- utilities.md (parent page)
| | |-- color.md | | |-- color.md
| | |-- layout.md | | |-- layout.md
| | |-- responsive-modifiers.md | | |-- responsive-modifiers.md
@ -66,45 +86,105 @@ Sometimes you will want to create a page with many children (a section). To acco
+-- .. +-- ..
``` ```
On the parent pages, add 3 YAML front matter variables: On the parent pages, add 2 YAML front matter variables:
- `has_children: true` (tells us that this a parent page) - `has_children: true` (tells us that this a parent page)
- `parent: ` set this to the title of the parent page (in this case, it's this page's title) - `permalink:` set this to the site directories that the contains the pages
- `permalink: ` set this to the directory that the contains the pages
#### Example #### Example
{: .no_toc } {: .no_toc }
```yaml ```yaml
---
layout: default layout: default
title: UI Components title: UI Components
nav_order: 2 nav_order: 2
has_children: true has_children: true
parent: UI Components permalink: /docs/ui-components
permalink: /ui-components ---
``` ```
Here we're setting up the UI Components landing page that is available at `/ui-components`, has children and is ordered second in the main nav. Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, it has children and is ordered second in the main nav.
### Child pages ### 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). 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 #### Example
{: .no_toc } {: .no_toc }
```yaml ```yaml
---
layout: default layout: default
title: Buttons title: Buttons
parent: UI Components parent: UI Components
nav_order: 2 nav_order: 2
---
``` ```
The Buttons page appears a child of UI Components and appears second in the UI Components section. The Buttons page appears a child of UI Components and appears second in the UI Components section.
### Children with children
{: .text-gamma }
Child pages can also have children (grand children). This is achieved by using a similar pattern on the child and grand child pages.
1. Add the `has_children` attribute to the child
1. Add the `parent` and `grand_parent` attribute to the grandchild
#### Example
{: .no_toc }
```yaml
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
has_children: true
---
```
```yaml
---
layout: default
title: Buttons Child Page
parent: Buttons
grand_parent: UI Components
nav_order: 1
---
```
Would create the following navigation structure:
```
+-- ..
|
|-- UI Components
| |-- ..
| |
| |-- Buttons
| | |-- Button Child Page
| |
| |-- ..
|
+-- ..
```
--- ---
## Breadcrumbs ## Auxiliary Navigation
Breadcrumbs are auto generated based on the parent/child structure and the directory structure for the site. In order for breadcrumbs to work correctly for pages children, the URL structure must be the slugified version of the parent page's title. For example, the page UI Components, must use the `/ui-components` directory to house its descendant pages. 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.
#### Example
{: .no_toc }
```yml
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs"
```
--- ---

View File

@ -21,7 +21,6 @@ nav_order: 2
### Links that look like buttons ### Links that look like buttons
<div class="code-example" markdown="1"> <div class="code-example" markdown="1">
[Link button](http://example.com/){: .btn } [Link button](http://example.com/){: .btn }
[Link button](http://example.com/){: .btn .btn-purple } [Link button](http://example.com/){: .btn .btn-purple }
@ -32,7 +31,6 @@ nav_order: 2
</div> </div>
```markdown ```markdown
[Link button](http://example.com/){: .btn } [Link button](http://example.com/){: .btn }
[Link button](http://example.com/){: .btn .btn-purple } [Link button](http://example.com/){: .btn .btn-purple }

View File

@ -31,7 +31,6 @@ Deprecated
</div> </div>
```markdown ```markdown
Default label Default label
{: .label } {: .label }
@ -49,5 +48,4 @@ Coming soon
Deprecated Deprecated
{: .label .label-red} {: .label .label-red}
``` ```

View File

@ -3,8 +3,7 @@ layout: default
title: UI Components title: UI Components
nav_order: 3 nav_order: 3
has_children: true has_children: true
parent: UI Components permalink: /docs/ui-components
permalink: /ui-components
--- ---
# UI Components # UI Components

View File

@ -34,6 +34,7 @@ All the colors used in Just the Docs have been systemsized into a series of vari
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-000"></span> `grey-dk-000` | `.text-grey-dk-000` | `.bg-grey-dk-000` | | <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-000"></span> `grey-dk-000` | `.text-grey-dk-000` | `.bg-grey-dk-000` |
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-100"></span> `grey-dk-100` | `.text-grey-dk-100` | `.bg-grey-dk-100` | | <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-100"></span> `grey-dk-100` | `.text-grey-dk-100` | `.bg-grey-dk-100` |
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-200"></span> `grey-dk-200` | `.text-grey-dk-200` | `.bg-grey-dk-200` | | <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-200"></span> `grey-dk-200` | `.text-grey-dk-200` | `.bg-grey-dk-200` |
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-250"></span> `grey-dk-250` | `.text-grey-dk-250` | `.bg-grey-dk-250` |
| <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-300"></span> `grey-dk-300` | `.text-grey-dk-300` | `.bg-grey-dk-300` | | <span class="d-inline-block p-2 mr-1 v-align-middle bg-grey-dk-300"></span> `grey-dk-300` | `.text-grey-dk-300` | `.bg-grey-dk-300` |
## Purples ## Purples

View File

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

View File

@ -2,9 +2,8 @@
layout: default layout: default
title: Utilities title: Utilities
nav_order: 4 nav_order: 4
parent: Utilities
has_children: true has_children: true
permalink: /utilities permalink: docs/utilities
--- ---
# Utilities # Utilities

View File

@ -12,7 +12,7 @@ permalink: /
Just the Docs gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable and hosted on GitHub pages. 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 } {: .fs-6 .fw-300 }
[Get started now](#getting-started){: .btn .btn-purple .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 } [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 }
--- ---
@ -20,7 +20,14 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
### Dependencies ### Dependencies
Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [quick start guide](https://jekyllrb.com/docs/quickstart/) 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/quickstart/) for more information. Just the Docs requires no special Jekyll plugins and can run on GitHub Pages standard Jekyll compiler.
### Installation ### 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
```
<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 1. Install the Ruby Gem
```bash ```bash
$ gem install just-the-docs $ gem install just-the-docs
@ -29,7 +36,7 @@ $ gem install just-the-docs
# .. or add it to your your Jekyll sites Gemfile # .. or add it to your your Jekyll sites Gemfile
gem "just-the-docs" gem "just-the-docs"
``` ```
2. Add Just the Docs to your Jekyll sites `config.yml` 2. Add Just the Docs to your Jekyll sites `_config.yml`
```yaml ```yaml
theme: "just-the-docs" theme: "just-the-docs"
``` ```
@ -47,6 +54,10 @@ $ bundle exec jekyll serve
``` ```
4. Point your web browser to [http://localhost:4000](http://localhost:4000) 4. Point your web browser to [http://localhost:4000](http://localhost:4000)
### Configure Just the Docs
- [See configuration options]({{ site.baseurl }}{% link docs/configuration.md %})
--- ---
## About the project ## About the project

View File

@ -2,7 +2,7 @@
Gem::Specification.new do |spec| Gem::Specification.new do |spec|
spec.name = "just-the-docs" spec.name = "just-the-docs"
spec.version = "0.1.6" spec.version = "0.2.0"
spec.authors = ["Patrick Marsceill"] spec.authors = ["Patrick Marsceill"]
spec.email = ["patrick.marsceill@gmail.com"] spec.email = ["patrick.marsceill@gmail.com"]
@ -13,8 +13,8 @@ Gem::Specification.new do |spec|
spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } 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.executables << 'just-the-docs'
spec.add_runtime_dependency "jekyll", "~> 3.3" spec.add_runtime_dependency "jekyll", "~> 3.8.5"
spec.add_runtime_dependency "rake", "~> 10.0" spec.add_runtime_dependency "rake", "~> 12.3.1"
spec.add_development_dependency "bundler", "~> 1.12" spec.add_development_dependency "bundler", "~> 1.17.1"
end end

View File

@ -1,6 +1,6 @@
{ {
"name": "just-the-docs", "name": "just-the-docs",
"version": "0.1.6", "version": "0.2.0",
"description": "A Jekyll theme for documentation", "description": "A Jekyll theme for documentation",
"repository": "pmarsceill/just-the-docs", "repository": "pmarsceill/just-the-docs",
"license": "MIT", "license": "MIT",