Merge pull request docker#1842 from mstanleyjones/allow_h1_in_toc

Allow h1 in in-page toc

Author: Misty Stanley-Jones

README.md

@@ -136,23 +136,23 @@ You have three options:
     docker-compose down
     ```
 
-2.  Use Jekyll directly. 
+2.  Use Jekyll directly.
 
     a. Clone this repo by running:
 
        ```bash
        git clone https://github.com/docker/docker.github.io.git
        ```
- 
+
     b. Install Ruby 2.3 or later as described in [Installing Ruby]
     (https://www.ruby-lang.org/en/documentation/installation/).
-    
+
     c. Install Bundler:
 
        ```bash
        gem install bundler
        ```
-       
+
     d. If you use Ubuntu, install packages required for the Nokogiri HTML
        parser:
 
@@ -165,7 +165,7 @@ You have three options:
        ```bash
        bundle install
        ```
-    
+
        >**Note**: You may have to install some packages manually.   
 
     f. Change the directory to `docker.github.io`.
@@ -203,12 +203,43 @@ guidance about grammar, syntax, formatting, styling, language, or tone. If
 something isn't clear in the guide, please submit an issue to let us know or
 submit a pull request to help us improve it.
 
-### Generate the man pages
-
-For information on generating man pages (short for manual page), see the README.md
-document in [the man page directory](https://github.com/docker/docker/tree/master/man)
-in this project.
+### Per-page front-matter
+
+The front-matter of a given page is in a section at the top of the Markdown
+file that starts and ends with three hyphens. It includes YAML content. The
+following keys are supported. The title, description, and keywords are required.
+
+| Key                    | Required  | Description                             |
+|------------------------|-----------|-----------------------------------------|
+| title                  | yes       | The page title. This is added to the HTML output as a `<h1>` level header. |
+| description            | yes       | A sentence that describes the page contents. This is added to the HTML metadata. |
+| keywords               | yes       | A comma-separated list of keywords. These are added to the HTML metadata. |
+| redirect_from          | no        | A YAML list of pages which should redirect to THIS page. At build time, each page listed here is created as a HTML stub containing a 302 redirect to this page. |
+| notoc                  | no        | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings.|
+| toc_min                | no        | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `<h2>` headings as the minimum. |
+| toc_max                | no        | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `<h3>` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. |
+| tree                   | no        | Either `true` or `false`. Set to `false` to disable the left-hand site-wide navigation for this page. Appropriate for some pages like the search page or the 404 page. |
+| no_ratings             | no        | Either `true` or `false`. Set to `true` to disable the page-ratings applet for this page. Defaults to `false`. |
+
+The following is an example of valid (but contrived) page metadata. The order of
+the metadata elements in the front-matter is not important.
+
+```liquid
+---
+description: Instructions for installing Docker on Ubuntu
+keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
+redirect_from:
+- /engine/installation/ubuntulinux/
+- /installation/ubuntulinux/
+- /engine/installation/linux/ubuntulinux/
+title: Get Docker for Ubuntu
+toc_min: 1
+toc_max: 6
+tree: false
+no_ratings: true
+---
+```
 
 ## Copyright and license
 
-Code and documentation copyright 2016 Docker, inc, released under the Apache 2.0 license.
+Code and documentation copyright 2017 Docker, inc, released under the Apache 2.0 license.

_includes/toc_pure_liquid.html

@@ -45,7 +45,7 @@
         {% assign html_id = _idWorkspace[1] %}
 
         {% capture _hAttrToStrip %}{{ headerLevel }} id="{{ html_id }}">{% endcapture %}
-        {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+        {% assign header = _workspace[0] | replace: _hAttrToStrip, '' | remove_first: "1>" %}
 
         {% assign space = '' %}
         {% for i in (1..indentAmount) %}

_layouts/docs.html

@@ -289,8 +289,19 @@
 								{% assign my_min = page.toc_min | default: site.toc_min | default: 2 %}
 								{% assign my_max = page.toc_max | default: site.toc_max | default: 3 %}
 								{% assign my_name = page.url | default: "unnamed" %}
-								<div id="side-toc"><div id="side-toc-title">On this page:</div><div id="side-toc-contents">{% include toc_pure_liquid.html html=content sanitize=true class="inline_toc" id="my_toc" toc_min=my_min toc_max=my_max page_name=my_name %}</div></div>
+								{% if my_min < 2 %}
+									{% comment %}
+										the 'content' variable doesn't include the <h1> by default
+										so if we request the h1 heading to be in the in-page TOC,
+										append it to the content before we pass it to the TOC generator
+									{% endcomment %}
+									{% assign my_content = "<h1>" | append: page.title | append: "</h1>" | append: content %}
+								{% else %}
+									{% assign my_content = content %}
+								{% endif %}
+								<div id="side-toc"><div id="side-toc-title">On this page:</div><div id="side-toc-contents">{% include toc_pure_liquid.html html=my_content sanitize=true class="inline_toc" id="my_toc" toc_min=my_min toc_max=my_max page_name=my_name %}</div></div>
 								{% endunless %}
+								<div>{{content}}</div>
                 </section>
             </div>
           </div>