diff --git a/README.md b/README.md index d565b279b7..c538fa1ce5 100644 --- a/README.md +++ b/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 +### Per-page front-matter -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. +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 `

` 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 `

` 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 `

` 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. diff --git a/_includes/toc_pure_liquid.html b/_includes/toc_pure_liquid.html index bf2b4c166d..84bd122d9c 100644 --- a/_includes/toc_pure_liquid.html +++ b/_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) %} diff --git a/_layouts/docs.html b/_layouts/docs.html index 7b13136b57..0c6c0fba4c 100644 --- a/_layouts/docs.html +++ b/_layouts/docs.html @@ -289,8 +289,19 @@ ng\:form { {% 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" %} -
On this page:
{% 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 %}
+ {% if my_min < 2 %} + {% comment %} + the 'content' variable doesn't include the

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 = "

" | append: page.title | append: "

" | append: content %} + {% else %} + {% assign my_content = content %} + {% endif %} +
On this page:
{% 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 %}
{% endunless %} +
{{content}}