Update doc contrib, baseof temps

2026-08-25 15:58:53 +00:00 · 2017-03-09 13:27:11 -06:00
parent 0c45e6383a
commit ad6367bf82
115 changed files with 96 additions and 78 deletions
@@ -61,7 +61,7 @@ watch = true
  # Add GA Tracking Code Here. This leverages a built-in (ie, "internal") partial from HUGO: https://gohugo.io/extras/analytics#configuring-google-analytics
  googleanalyticstrackingcode = ""
  ## Critical Render Path. If true, site style will be embedded in a <style> tag in each html <head> as part of Gulp Build. False puts a typical <link> to the stylesheet in <head>>
-  usecrp = true
+  usecrp = false
  ## Include jQuery 2.2.4 in your site head. (see /static/assets/js)
  includejq = false
  ## Date the Site is Published, use YYYY-MM-DD
@@ -12,15 +12,15 @@ aliases: []
 toc: false
 ---

-The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
+The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.

 Creating the page dynamically requires the HTTP server to have enough memory and CPU to effectively run the generator nonstop. If not, your end user will wait in a queue for the page to be generated.

-Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page that is temporarily stored on a server for. Sending a cached copy of a web page is faster than generating a new page at the time of request because the majority of the work is already done.
+Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page that is temporarily stored on a server. Sending a cached copy of a web page is faster than generating a new page at the time of request because the majority of the work is already done.

 Hugo is in a family of generators that take caching a step further. All HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.

-Not running a website generator on your HTTP server has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
+Not running a website generator on your HTTP server has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a ~~dynamic site~~.

 ## More on Static Site Generators

@@ -11,14 +11,13 @@ weight: 20
 draft: false
 aliases: [/contribute/docs/]
 toc: true
-wip: true
 ---

-Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.19, but there is always room for improvement.
+Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.20, but there is always room for improvement.

 ## Create Your Fork

-It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of Hugo on GitHub and cloned the repository locally on your computer. For more information, you can use the [GitHub docs for "forking"][ghforking] or see [Hugo's extensive development contribution guide][hugodev].
+It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of Hugo on GitHub and cloned the repository locally on your machine. For more information, you can use the [GitHub docs for "forking"][ghforking] or see [Hugo's extensive development contribution guide][hugodev].

 You can then create a separate branch for your additions. Note that you can choose a different descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:

@@ -28,16 +27,16 @@ git checkout -b jon-doe-showcase-addition

 ## Adding New Content

-The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetypes][] feature to easily scaffold new instances of content types. All content sections in Hugo documentation have an assigned archetype ([see the Hugo docs archetype source][archsource]).
+The Hugo docs make heavy use of Hugo's [archetypes][] feature to easily scaffold new instances of content types. All content sections in Hugo documentation have an assigned archetype. You can [see the Hugo docs archetype source][archsource] for more clarity.

-Adding new content follows the same pattern, regardless of the content section:
+Adding new content to the Hugo docs follows the same pattern, regardless of the content section:

 ```
-hugo new <docssection>/<newcontent-all-lowercase.md>
+hugo new <DOCS-SECTION>/<new-content-lowercase>.md
 ```

 {{% note "`title:`, `date:`, and Field Order" %}}
-`title` and `date` fields are added automatically when using archetypes via `hugo new`. Do not be worried if the order of the new file's front matter fields on your local machine is different than that of the following examples. This is a [known issue (#452)](https://github.com/spf13/hugo/issues/452).
+`title` and `date` fields are added automatically when using archetypes via `hugo new`. Do not be worried if the order of the new file's front matter fields on your local machine is different than that of the examples provided in the Hugo docs. This is a known issue [(#452)](https://github.com/spf13/hugo/issues/452).
 {{% /note %}}

 ### Adding a New Function
@@ -56,36 +55,39 @@ The archetype for the `functions` content type is as follows:
 ```
 {{% /code %}}

-#### Function Required Fields
+#### New Function Required Fields

-Let's review some of the fields automatically generated for you using `hugo new functions/*`:
+Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:

 ***`title`***
-: This should be generated in all lowercase when you use `hugo new`.
+: this will be auto-populated in all lowercase when you use `hugo new` generator.

 ***`linktitle`***
-: Use the function's actual casing (e.g., `replaceRE` rather than `replacere`).
+: the function's actual casing (e.g., `replaceRE` rather than `replacere`).

 ***`description`***
-: Keep this really short. This is what's used to populate the [Functions Quick Reference](/functions/).
+: a brief description used to populate the [Functions Quick Reference](/functions/).

 `categories`
-: This is populated with 'functions` for future-proofing and portability reasons only. Skip this field.'
+: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.

 `tags`
-: Only if you think it will help end users find other related functions
+: only if you think it will help end users find other related functions

 `signature`
-: This is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`)
+: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).

 `workson`
-: Acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`
+: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.

 `hugoversion`
-: The version of Hugo that will ship with this new function
+: the version of Hugo that will ship with this new function.

 `relatedfuncs`
-: If you can, list some functions you think are related to your new function to help fellow Hugo users.
+: other [templating functions][] you feel are related to your new function to help fellow Hugo users.
+
+`{{.Content}}`
+: an extended description of the new function; examples are not only welcomed but encouraged.

 In the body of you function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [code shortcodes](#adding-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.

@@ -108,16 +110,16 @@ The archetype for the `showcase` content type is as follows:
 #### Showcase Required Fields

 `sitelink`
-: the *full* URL to your website
+: the *full* URL to your website.

 `title`
-: the `<title>` of your website
+: the `<title>` of your website.

 `description`
 : a general description of your website, preferably < 180 characters.

 `image`
-: the image (filename only) you want to associate with your website on the Showcase page. The image should be 600px x 400px.
+: the image (filename only) you want to associate with your website on the Showcase page. The image should be 450px &times; 300px.

 We also appreciate the addition of the remaining fields, specially `sourcelink` and `license` if you are willing to share your hard work with the open-source community. `tags` is optional, but we recommend adding at least 2 to 3 tags to improve discoverability.

@@ -388,12 +390,12 @@ needsexamples: true

 ## Places to Start

-The preceding `needsexamples` is used to generate the following list of pages flagged for needing example. Links will take you directly to the edit URL for the file within the GitHub GUI:
+The preceding `needsexamples` field is used to generate the following list of flagged content. Links will take you directly to the edit URL for the file within the GitHub GUI in the event that you are not comfortable cloning and editing the repository locally.

 {{< needsexamples >}}

 {{% note "Pull Requests and Branches" %}}
-Similar to [contributing to Hugo development](/contribute/contribute-to-hugo-development), the Hugo team expects you to create a separate branch/fork when you make your generous contributions to the Hugo docs.
+Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your generous contributions to the Hugo docs.
 {{% /note %}}

 [abe]: https://en.wikipedia.org/wiki/K%C5%8Db%C5%8D_Abe
@@ -404,4 +406,5 @@ Similar to [contributing to Hugo development](/contribute/contribute-to-hugo-dev
 [ghforking]: https://help.github.com/articles/fork-a-repo/
 [hugodev]: /contribute/development/
 [shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
-[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+[templating function]: /functions/
@@ -13,7 +13,7 @@ aliases: [/overview/introduction/]
 toc: false
 ---

-The Hugo docs were completely reworked for the release of Hugo v0.19. If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][].
+The Hugo docs were completely reworked for the release of Hugo v0.20. If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][].

 [installed]: /getting-started/installing/
 [quick start]: /getting-started/quick-start/
@@ -19,27 +19,41 @@ Go 1.6 includes a powerful new keyword, `block`. This construct allows you to de

 ## Base Template Lookup Order

-This is the order Hugo searches for your base template:
+The [lookup order][lookup] for base templates is as follows:

-1. `/layouts/<CURRENTPATH>/<TEMPLATENAME>-baseof.html`
-2. `/layouts/<CURRENTPATH>/baseof.html`
-3. `/layouts/_default/<TEMPLATENAME>-baseof.html`
-4. `/layouts/_default/baseof.html`
+1. `/layouts/section/<TYPE>-baseof.html`
+2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
+3. `/layouts/<TYPE>/baseof.html`
+4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/<THEME>/layouts/section/baseof.html`
+7. `/layouts/_default/post-baseof.html`
+8. `/themes/<THEME>/layouts/_default/post-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/<THEME>/layouts/_default/baseof.html`

-As an example, let's assume your site is using the theme when rendering the section list for the section `post`. Hugo picks the `section/post.html` as the template and this template has a `define` section that indicates it needs a base template. This is then the lookup order:
+Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
+
+### Example Base Template Lookup Order
+
+As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
+
+Here is the lookup order for the `post` base template:

 1. `/layouts/section/post-baseof.html`
-2. `/themes/<THEME>/layouts/section/post-baseof.html`
-3. `/layouts/section/baseof.html`
-4. `/themes/<THEME>/layouts/section/baseof.html`
-5. `/layouts/_default/post-baseof.html`
-6. `/themes/<THEME>/layouts/_default/post-baseof.html`
-7. `/layouts/_default/baseof.html`
-8. `/themes/<THEME>/layouts/_default/baseof.html`
+2. `/themes/mytheme/layouts/section/post-baseof.html`
+3. `/layouts/post/baseof.html`
+4. `/themes/mytheme/layouts/post/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/mytheme/layouts/section/baseof.html`
+7. `/layouts/_default/post-baseof.html`
+8. `/themes/mytheme/layouts/_default/post-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/mytheme/layouts/_default/baseof.html`

 ## Defining the Base Template

-The following defines a simple base template at `_default/baseof.html`). As a default template, it is the shell from which all our pages will start unless a more specific `*baseof.html` is defined.
+The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will start unless you specify another `*baseof.html` closer to the beginning of the lookup order..

 {{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
 ```html
@@ -118,4 +132,6 @@ The following shows how you can override both the `"main"` and `"title"` block a
 {{% /code %}}

 [hugolists]: /templates/lists
+[lookup]: /templates/lookup-order/
+[rendering the section]: /templates/section-templates/
 [singletemplate]: /templates/single-page-templates/
@@ -11,7 +11,7 @@ tags: [lookup,fundamentals]
 weight: 15
 draft: false
 aliases: [/templates/lookup/]
-wip: true
+toc: true
 ---

 Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
@@ -20,7 +20,7 @@ Hugo uses a prioritized list called the **lookup order** as it traverses your `l

 The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the control mechanism of a [switch statement (i.e. without fallthrough)][switch] seen in many programming languages.

-The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][].
+The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][].

 {{% note %}}
 Most Hugo websites will only need the default template files at the end of the lookup order (i.e. `_default/*.html`).
@@ -63,11 +63,11 @@ The lookup order is best illustrated by example. The following shows you the pro

 Now we can look at the front matter for the three single-page content (i.e.`.md`) files.

-{{% note "Three Content Pages but *Four* Markdown Files?" %}}
-`_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to list pages and therefore do not submit themselves to the *single* page template lookup. Instead, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
+{{% note  %}}
+You may notice there are four markdown files but we are only going to review three for the *single* page lookup order. `_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to list pages. `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
 {{% /note %}}

-### `my-first-post.md`
+### Example: `my-first-post.md`

 {{% code file="content/posts/my-first-post.md" copy="false" %}}
 ```yaml
@@ -81,9 +81,9 @@ description: This is my first post.

 When it comes time for Hugo to render the content to the page, it will go through the single page template lookup order until it finds what it needs for `my-first-post.md`:

-1. <span class="no">`/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
-2. <span class="no">`/layouts/posts/UNSPECIFIED.html`</span>
-3. <span class="no">`/layouts/UNSPECIFIED/single.html`</span>
+1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
+2. ~~`/layouts/posts/UNSPECIFIED.html`~~
+3. ~~`/layouts/UNSPECIFIED/single.html`~~
 4. <span class="yes">`/layouts/posts/single.html`</span>
  <br><span class="break">BREAK</span>
 5. <span class="na">`/layouts/_default/single.html`</span>
@@ -97,7 +97,7 @@ Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo th

 `my-first-post.md` also does not specify a `layout` in its front matter. Therefore, Hugo assumes that `my-first-post.md`, which is of type `page` and a *single* piece of content, should default to the next occurrence of a `single.html` template in the lookup (#4).

-### `my-second-post.md`
+### Example: `my-second-post.md`

 {{% code file="content/posts/my-second-post.md" copy="false" %}}
 ```yaml
@@ -131,7 +131,7 @@ The front matter in `my-second-post.md` specifies the content `type` (i.e. `revi
 Notice that the directory for the template for `my-second-post.md` is `review` and not `reviews`. This is because *type is always singular when defined in front matter*.
 {{% /note%}}

-### `my-first-event.md`
+### Example: `my-first-event.md`

 {{% code file="content/events/my-first-event.md" copy="false" %}}
 ```yaml
@@ -145,10 +145,10 @@ description: This is an upcoming event..

 Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:

-1. <span class="no">`/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
-2. <span class="no">`/layouts/events/UNSPECIFIED.html`</span>
-3. <span class="no">`/layouts/UNSPECIFIED/single.html`</span>
-4. <span class="no">`/layouts/events/single.html`</span>
+1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
+2. ~~`/layouts/events/UNSPECIFIED.html`~~
+3. ~~`/layouts/UNSPECIFIED/single.html`~~
+4. ~~`/layouts/events/single.html`~~
 5. <span class="yes">`/layouts/_default/single.html`</span>
 <br><span class="break">BREAK</span>
 6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
@@ -21,7 +21,7 @@ To effectively leverage section page templates, you should first understand Hugo

 ## Section Template Lookup Order

-The [lookup order][lookup] for section pages is as follows:
+The [lookup order][lookup] for section templates is as follows:

 1. `/layouts/section/<SECTION>.html`
 2. `/layouts/<SECTION>/list.html`
@@ -22,12 +22,12 @@ You can specify `type` (i.e., [content type][]) and `layout` in a single content
 Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.

 1. `/layouts/<TYPE>/<LAYOUT>.html`
-2. `/layouts/<SECTION>/<LAYOUT>.html`
+2. `/layouts/<SECTION>>/<LAYOUT>.html`
 3. `/layouts/<TYPE>/single.html`
 4. `/layouts/<SECTION>/single.html`
 5. `/layouts/_default/single.html`
 6. `/themes/<THEME>/layouts/<TYPE>/<LAYOUT.html`
-7. `/themes/<THEME>/layouts/<SECTION/LAYOUT.html`
+7. `/themes/<THEME>/layouts/<SECTION>/LAYOUT.html`
 8. `/themes/<THEME>/layouts/<TYPE>/single.html`
 9. `/themes/<THEME>/layouts/<SECTION>/single.html`
 10. `/themes/<THEME>/layouts/_default/single.html`
@@ -5,8 +5,7 @@ svg.svg-icon {
 //for template lookup yes/no/na (e.g., in single-page template [/templates/single-page-template/])
 span.yes {
  code {
-    color: $hugo-white;
-    background-color: $hugo-green;
+    color: $hugo-green;
  }
 }

@@ -128,20 +128,20 @@ aside {
  }
 }

-//For example, used in the "Pages Needing Code Examples" section of "Contribute to the Hugo docs"
-// .body-copy {
-//   .utils-list {
-//     list-style: none;
-//     margin-left: 0px;
-//     padding-left: 0px;
-//     li {
-//       list-style: none;
-//       display: inline;
-//       margin-left: 0px;
-//       padding-left: 0px;
-//     }
-//   }
-// }
+.body-copy {
+  ol > li > del {
+    color: $hugo-pink;
+    &:after {
+      display: inline-block;
+      @include size(1em);
+      font-family: 'fontello';
+      content: '\e810';
+      margin-left: .5em;
+      font-size: 1.2em;
+      color: $hugo-pink;
+    }
+  }
+}

 //for Hugo's native support of Github-flavored task list synax
 .body-copy {
--- a/Show More
+++ b/Show More