Merge pull request #67 from EricFromCanada/doc-cleanup

Documentation cleanup

README.md

@@ -4,12 +4,11 @@
 <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, high customizable, 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://pmarsceill.github.io/just-the-docs/">See it in action!</a></strong></p>
     <br><br><br>
 </p>
 
-
 ![jtd](https://user-images.githubusercontent.com/896475/47384541-89053c80-d6d5-11e8-98dc-dba16e192de9.gif)
 
 ## Installation

assets/css/dark-mode-preview.scss

@@ -10,7 +10,7 @@
 @import "./vendor/normalize.scss/normalize.scss";
 
 //
-// Import Just the docs scss
+// Import Just the Docs scss
 //
 
 // Support

assets/css/just-the-docs.scss

@@ -10,7 +10,7 @@
 @import "./vendor/normalize.scss/normalize.scss";
 
 //
-// Import Just the docs scss
+// Import Just the Docs scss
 //
 
 // Support

docs/customization.md

@@ -16,17 +16,17 @@ nav_order: 6
 ---
 
 ## Color schemes
-{: .d-inline-block :}
+{: .d-inline-block }
 
 New
-{: .label .label-green :}
+{: .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 }
+{: .no_toc }
 
 ```yml
 # Color scheme currently only supports "dark" or nil (default)
@@ -49,15 +49,14 @@ addEvent(toggleDarkMode, 'click', function(){
 })
 </script>
 
-
 ## Specific visual customization
 
-To customize your site’s aesthetic, open `_sass/custom/custom.scss` in your editor to see if there is a variable that you can override. Most styles like fonts, colors, spacing, etc.. are derived from these variables. To override a specific variable, uncomment out it’s line and change it’s value.
+To customize your site’s aesthetic, open `_sass/custom/custom.scss` in your editor to see if there is a variable that you can override. Most styles like fonts, colors, spacing, etc. are derived from these variables. To override a specific variable, uncomment its line and change its value.
 
-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.
+For example, to change the link color from the purple default to blue, open `_sass/custom/custom.css` and find the `$link-color` variable on line `50`. Uncomment it, and change its value to our `$blue-000` variable, or another shade of your choosing.
 
 #### Example
-{: no_toc }
+{: .no_toc }
 
 ```scss
 // ...
@@ -72,4 +71,3 @@ $link-color: $blue-000;
 _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependancies to fail.
 
 ---
-

docs/navigation-structure.md

@@ -25,10 +25,11 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 ## 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` parameter in your pages' YAML front matter.
 
 #### Example
 {: .no_toc }
+
 ```yaml
 ---
 layout: default
@@ -41,10 +42,11 @@ nav_order: 4
 
 ## 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.
+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
@@ -57,7 +59,7 @@ 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:
+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 us an organization like:
 
 ```
 +-- ..
@@ -86,12 +88,13 @@ Sometimes you will want to create a page with many children (a section). First,
 +-- ..
 ```
 
-On the parent pages, add 2 YAML front matter variables:
+On the parent pages, add 2 YAML front matter parameters:
--  `has_children: true` (tells us that this a parent page)
+-  `has_children: true` (tells us that this is a parent page)
--  `permalink:` set this to the site directories that the contains the pages
+-  `permalink:` set this to the site directory that contains the child pages
 
 #### Example
 {: .no_toc }
+
 ```yaml
 ---
 layout: default
@@ -102,7 +105,7 @@ permalink: /docs/ui-components
 ---
 ```
 
-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.
+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 }
@@ -111,6 +114,7 @@ On child pages, simply set the `parent:` YAML front matter to whatever the paren
 
 #### Example
 {: .no_toc }
+
 ```yaml
 ---
 layout: default
@@ -120,12 +124,15 @@ nav_order: 2
 ---
 ```
 
+The Buttons page appears as a child of UI Components and appears second in the UI Components section.
+
 ### Auto-generating Table of Contents
 
-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` on the parent page's YAML front matter.
+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
 ---
 layout: default
@@ -137,8 +144,6 @@ permalink: /docs/ui-components
 ---
 ```
 
-The Buttons page appears a child of UI Components and appears second in the UI Components section.
-
 ### Children with children
 {: .text-gamma }
 
@@ -170,7 +175,7 @@ nav_order: 1
 ---
 ```
 
-Would create the following navigation structure:
+This would create the following navigation structure:
 
 ```
 +-- ..
@@ -206,7 +211,7 @@ aux_links:
 
 ## In-page navigation with Table of Contents
 
-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 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, to skip a particular heading use the `{: .no_toc }` CSS class.
+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 }

docs/search.md

@@ -15,7 +15,7 @@ nav_order: 7
 
 ---
 
-Just the docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated html pages are indexed  using the following data points:
+Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated HTML pages are indexed using the following data points:
 
 - Page title
 - Page content
@@ -25,16 +25,13 @@ Just the docs uses [lunr.js](http://lunrjs.com) to add a client-side search inte
 
 ### Generate search index
 
-Before you can use search, you must initialize the feature by running this
+Before you can use search, you must initialize the feature by running this `rake` command that comes with `just-the-docs`:
-rake command that comes with the `just-the-docs`
 
 ```bash
 $ bundle exec just-the-docs rake search:init
 ```
 
-This command creates the `search-data.json` file that Jekyll uses to create
+This command creates the `search-data.json` file that Jekyll uses to create your search index. Alternatively, you can create the file manually in the `assets/js/` directory of your Jekyll site with this content:
-your search index. Alternatively, you can create the file manually in the
-`assets/js/` of your Jekyll site with this content:
 
 ```{% raw %}
 ---
@@ -55,7 +52,7 @@ _Note: If you don't run this rake command or create this file manually, search w
 
 ### Enable search in configuration
 
-In your site's `_config.yml` enable search:
+In your site's `_config.yml`, enable search:
 
 ```yml
 # Enable or disable the site search
@@ -64,10 +61,11 @@ search_enabled: true
 
 ## Hiding pages from search
 
-Sometimes you might have a page that you don't want indexed in the search and you don't want it to show up in search results, e.g, a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
+Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
 #### Example
 {: .no_toc }
+
 ```yaml
 ---
 layout: default

docs/ui-components/buttons.md

@@ -28,7 +28,6 @@ nav_order: 2
 [Link button](http://example.com/){: .btn .btn-green }
 
 [Link button](http://example.com/){: .btn .btn-outline }
-
 </div>
 ```markdown
 [Link button](http://example.com/){: .btn }
@@ -42,13 +41,10 @@ nav_order: 2
 
 ### Button element
 
-GitHub flavored markdown does not support the `button` element, so you'll have to use inline HTML for this:
+GitHub Flavored Markdown does not support the `button` element, so you'll have to use inline HTML for this:
-
 
 <div class="code-example">
-
 <button type="button" name="button" class="btn">Button element</button>
-
 </div>
 ```html
 <button type="button" name="button" class="btn">Button element</button>
@@ -60,11 +56,9 @@ GitHub flavored markdown does not support the `button` element, so you'll have t
 
 ### Button size
 
-Wrap the button in container that uses the [font-size utility classes]({{
+Wrap the button in a container that uses the [font-size utility classes]({{ site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
-site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
 
 <div class="code-example" markdown="1">
-
 <span class="fs-6">
 [Big ass button](http://example.com/){: .btn }
 </span>
@@ -72,7 +66,6 @@ site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
 <span class="fs-3">
 [Tiny ass button](http://example.com/){: .btn }
 </span>
-
 </div>
 ```markdown
 <span class="fs-8">
@@ -86,10 +79,9 @@ site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
 
 ### Spacing between buttons
 
-Use the [margin utility classes]({{ site.baseurl }}{% link docs/utilities/utilities.md %}#spacing) to add spacing between two buttons in the same block.
+Use the [margin utility classes]({{ site.baseurl }}{% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
 
 <div class="code-example" markdown="1">
-
 [Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
 [Button ](http://example.com/){: .btn .btn-blue .mr-2 }
 

docs/ui-components/code.md

@@ -18,12 +18,10 @@ nav_order: 6
 
 ## Inline code
 
-Code can be rendered inline using single ticks by wrapping your code in single back ticks.
+Code can be rendered inline by wrapping it in single back ticks.
 
 <div class="code-example" markdown="1">
-
 Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-
 </div>
 ```markdown
 Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
@@ -33,7 +31,7 @@ Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiu
 
 ## Syntax highlighted code blocks
 
-Use Jekyll's built in syntax highlighting with Rouge for code blocks by using three backticks, followed by the language name:
+Use Jekyll's built-in syntax highlighting with Rouge for code blocks by using three backticks, followed by the language name:
 
 <div class="code-example" markdown="1">
 ```js
@@ -58,7 +56,7 @@ var fun = function lang(l) {
 
 ## Code blocks with rendered examples
 
-To demonstrate front end code, sometimes it useful to show a rendered example of that code. After including the styles from your project that you'll need to show the rendering, you can use a div with the `code-example` class, followed by the code block syntax. If you want to render your output with Markdown instead of HTML, use the `markdown="1"` attribute to tell Jekyll that the code you are rendering will be in Markdown format... This is about to get meta...
+To demonstrate front end code, sometimes it's useful to show a rendered example of that code. After including the styles from your project that you'll need to show the rendering, you can use a `<div>` with the `code-example` class, followed by the code block syntax. If you want to render your output with Markdown instead of HTML, use the `markdown="1"` attribute to tell Jekyll that the code you are rendering will be in Markdown format... This is about to get meta...
 
 <div class="code-example" markdown="1">
 

docs/ui-components/labels.md

@@ -10,7 +10,6 @@ nav_order: 3
 Use labels as a way to add an additional mark to a section of your docs. Labels come in a few colors. By default, labels will be blue.
 
 <div class="code-example" markdown="1">
-
 Default label
 {: .label }
 
@@ -28,7 +27,6 @@ Coming soon
 
 Deprecated
 {: .label .label-red }
-
 </div>
 ```markdown
 Default label

docs/ui-components/lists.md

@@ -16,9 +16,10 @@ nav_order: 5
 
 ---
 
-Most lists can be rendered with pure markdown...
+Most lists can be rendered with pure Markdown.
 
 ## Unordered list
+
 <div class="code-example" markdown="1">
 - Item 1
 - Item 2
@@ -42,8 +43,8 @@ _or_
 * Item 3
 ```
 
-
 ## Ordered list
+
 <div class="code-example" markdown="1">
 1. Item 1
 1. Item 2
@@ -54,6 +55,7 @@ _or_
 1. Item 2
 1. Item 3
 ```
+
 ## Task list
 
 <div class="code-example" markdown="1">
@@ -69,7 +71,7 @@ _or_
 
 ## Definition list
 
-Definition lists require HTML syntax and aren't supported with the GitHub flavored markdown compiler.
+Definition lists require HTML syntax and aren't supported with the GitHub Flavored Markdown compiler.
 
 <div class="code-example" markdown="1">
 <dl>
@@ -95,4 +97,3 @@ Definition lists require HTML syntax and aren't supported with the GitHub flavor
   <dd>Green</dd>
 </dl>
 ```
-

docs/ui-components/typography.md

@@ -28,7 +28,7 @@ ABCDEFGHIJKLMNOPQRSTUVWXYZ
 abcdefghijklmnopqrstuvwxyz
 {: .fs-5 .ls-10 .code-example }
 
-For monospace type, like code snippets or the pre `<pre>` element, Just the Docs uses a native system font stack for monospace fonts:
+For monospace type, like code snippets or the `<pre>` element, Just the Docs uses a native system font stack for monospace fonts:
 
 ```scss
 "SFMono-Regular", Menlo, Consolas, Monospace
@@ -42,7 +42,7 @@ abcdefghijklmnopqrstuvwxyz
 
 ## Responsive type scale
 
-Just the docs uses a responsive type scale that shifts depending on the viewport size. Common elements text elements rendered from markdown use a
+Just the Docs uses a responsive type scale that shifts depending on the viewport size.
 
 | Selector              | Small screen size `font-size`    | Large screen size `font-size` |
 |:----------------------|:---------------------------------|:------------------------------|
@@ -109,6 +109,6 @@ Text can be **bold**, _italic_, or ~~strikethrough~~.
 
 ## Typographic Utilities
 
-There are a number of specific typographic CSS classes that allow you to do override default styling for font size, font-weight, line height, and capitalization.
+There are a number of specific typographic CSS classes that allow you to override default styling for font size, font weight, line height, and capitalization.
 
 [View typography utilities]({{ site.baseurl }}{% link docs/utilities/utilities.md %}#typography){: .btn .btn-outline }

docs/utilities/color.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Color
-nav_order: 3
 parent: Utilities
+nav_order: 3
 ---
 
 # Color Utilities
@@ -16,7 +16,7 @@ parent: Utilities
 
 ---
 
-All the colors used in Just the Docs have been systemsized into a series of variables that have been extended to both font color and background color utility classes.
+All the colors used in Just the Docs have been systematized into a series of variables that have been extended to both font color and background color utility classes.
 
 ## Light Greys
 

docs/utilities/layout.md

@@ -1,9 +1,8 @@
 ---
 layout: default
 title: Layout
-nav_order: 2
 parent: Utilities
-has_children: true
+nav_order: 2
 ---
 
 # Layout Utilities
@@ -57,15 +56,14 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes
 #### Examples
 {: .no_toc }
 
-```markdown
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
+```markdown
 This paragraph will have a margin bottom of 1rem/16px at large screens.
 {: .mb-lg-4 }
 
 This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.
 {: .px-6 }
-
 ```
 
 ## Vertical Alignment
@@ -96,9 +94,9 @@ Use these classes in conjunction with the responsive modifiers.
 #### Examples
 {: .no_toc }
 
-```markdown
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
+```markdown
 This button will be hidden until medium screen sizes:
 
 [ A button ](#url)
@@ -111,5 +109,4 @@ These headings will be `inline-block`:
 
 ### heading 3
 { .d-inline-block }
-
 ```

docs/utilities/responsive-modifiers.md

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

docs/utilities/typography.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Typography
-nav_order: 3
 parent: Utilities
+nav_order: 4
 ---
 
 # Typography Utilities
@@ -117,8 +117,6 @@ Use the `lh-` classes to explicitly apply line height to text.
 | `.lh-tight`   | 1.1                  | Default for headings          |
 | `.lh-default` | 1.4                  | Default for body (paragraphs) |
 
-
-
 <div class="code-example" markdown="1">
 No Line height
 No Line height

docs/utilities/utilities.md

@@ -9,5 +9,5 @@ permalink: docs/utilities
 # Utilities
 {: .no_toc }
 
-CSS utility classes come in handy when you to want to override default styles to give create additional whitespace (margins/padding), unexpected shifts in font-size or weight, add color, or to hide (or show) something a specific screen size.
+CSS utility classes come in handy when you to want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
 {: .fs-6 .fw-300 }

index.md

@@ -2,15 +2,14 @@
 layout: default
 title: Home
 nav_order: 1
-description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub pages."
+description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
 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.
+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 }
@@ -18,17 +17,21 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 ---
 
 ## Getting started
+
 ### 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/) for more information. Just the Docs requires no special Jekyll plugins and can run on GitHub Pages' standard Jekyll compiler.
 
 ### 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>
+<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
@@ -56,8 +59,8 @@ $ bundle exec jekyll serve
 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 %})
 
+- [See configuration options]({{ site.baseurl }}{% link docs/configuration.md %})
 
 ---
 
@@ -74,7 +77,6 @@ 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).
 
-
 ### Code of Conduct
 
 Just the Docs is committed to fostering a welcoming community.