Merge pull request barryclark#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"><strong><a href="https://pmarsceill.github.io/just-the-docs">See it in action!</a></strong></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>
     <br><br><br>
 </p>
 
-
 ![jtd](https://user-images.githubusercontent.com/896475/47384541-89053c80-d6d5-11e8-98dc-dba16e192de9.gif)
 
 ## Installation
@@ -60,7 +59,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/pmarsc
 
 To set up your environment to develop this theme, run `bundle install`.
 
-Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
+Your theme is set up just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
 
 When the theme is released, only the files in `_layouts`, `_includes`, and `_sass` tracked with Git will be released.
 

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

bin/just-the-docs

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 gem_dir = File.expand_path("..",File.dirname(__FILE__))
-$LOAD_PATH.unshift gem_dir# Look in gem directory for resources first.
+$LOAD_PATH.unshift gem_dir # Look in gem directory for resources first.
 exec_type = ARGV[0]
 
 if exec_type == 'rake' then

docs/configuration.md

@@ -39,12 +39,12 @@ 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)
-}
+  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.
+See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.

docs/customization.md

@@ -5,7 +5,7 @@ nav_order: 6
 ---
 
 # Customization
-{:.no_toc}
+{: .no_toc }
 
 ## Table of contents
 {: .no_toc .text-delta }
@@ -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:
--  `has_children: true` (tells us that this a parent page)
--  `permalink:` set this to the site directories that the contains the pages
+On the parent pages, add 2 YAML front matter parameters:
+-  `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 }
+
 ```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,12 +144,10 @@ 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 }
 
-Child pages can also have children (grand children). This is achieved by using a similar pattern on the child and grand child pages.
+Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
 
 1. Add the `has_children` attribute to the child
 1. Add the `parent` and `grand_parent` attribute to the grandchild
@@ -170,7 +175,7 @@ nav_order: 1
 ---
 ```
 
-Would create the following navigation structure:
+This would create the following navigation structure:
 
 ```
 +-- ..
@@ -198,15 +203,15 @@ To add a auxiliary navigation item to your site (in the upper right on all pages
 ```yml
 # Aux links for the upper right navigation
 aux_links:
-"Just the Docs on GitHub":
+  "Just the Docs on GitHub":
     - "//github.com/pmarsceill/just-the-docs"
 ```
 
 ---
 
 ## 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

@@ -5,7 +5,7 @@ nav_order: 7
 ---
 
 # Search
-{:.no_toc}
+{: .no_toc }
 
 ## Table of contents
 {: .no_toc .text-delta }
@@ -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
-rake command that comes with the `just-the-docs`
+Before you can use search, you must initialize the feature by running this `rake` command that comes with `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
-your search index. Alternatively, you can create the file manually in the
-`assets/js/` of your Jekyll site with this content:
+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:
 
 ```{% 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

@@ -6,7 +6,7 @@ nav_order: 2
 ---
 
 # Buttons
-{:.no_toc}
+{: .no_toc }
 
 ## Table of contents
 {: .no_toc .text-delta }
@@ -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,19 +56,16 @@ 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]({{
-site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
+Wrap the button in a container that uses the [font-size utility classes]({{ 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>
 
 <span class="fs-3">
 [Tiny ass button](http://example.com/){: .btn }
 </span>
-
 </div>
 ```markdown
 <span class="fs-8">
@@ -86,20 +79,19 @@ 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 }
 
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2}
-[Button ](http://example.com/){: .btn .btn-blue .mr-2}
-
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4}
+[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
 [Button ](http://example.com/){: .btn .btn-blue }
 </div>
 ```markdown
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2}
+[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
 [Button ](http://example.com/){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4}
+[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
 [Button ](http://example.com/){: .btn .btn-blue }
 ```