phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-05 08:42:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

[Docs] Use <dl> for definition lists of variables

Browse source 
Hopefully making them more semantic and easier to read,
though it is raw HTML so it is slightly more work to maintain.

Also made minor revisions to some of the variable descriptions
to be more informative, e.g. `:monthname` in permalinks use
full English names ("January" etc.)
This commit is contained in:
Anthony Fok 2015-01-19 01:30:38 -07:00
parent 9712d06b36
commit 5d6dfe81b8
6 changed files with 170 additions and 125 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
docs/content/content/front-matter.md
View file

@ -80,23 +80,25 @@ Field names are always normalized to lowercase (e.g. `camelCase: true` is availa
### Required variables ### Required variables
* **title** The title for the content <dl>
* **description** The description for the content <dt><code>title</code></dt><dd>The title for the content</dd>
* **date** The date the content will be sorted by <dt><code>description</code></dt><dd>The description for the content</dd>
* **taxonomies** These will use the field name of the plural form of the index (see tags and categories above) <dt><code>date</code></dt><dd>The date the content will be sorted by</dd>
<dt><code>taxonomies</code></dt><dd>These will use the field name of the plural form of the index (see tags and categories above)</dd>
</dl>
### Optional variables ### Optional variables
* **redirect** Mark the post as a redirect post <dl>
* **draft** If true, the content will not be rendered unless `hugo` is called with `--buildDrafts` <dt><code>redirect</code></dt><dd>Mark the post as a redirect post</dd>
* **publishdate** If in the future, content will not be rendered unless `hugo` is called with `--buildFuture` <dt><code>draft</code></dt><dd>If true, the content will not be rendered unless <code>hugo</code> is called with <code>--buildDrafts</code></dd>
* **type** The type of the content (will be derived from the directory automatically if unset) <dt><code>publishdate</code></dt><dd>If in the future, content will not be rendered unless <code>hugo</code> is called with <code>--buildFuture</code></dd>
* **weight** Used for sorting <dt><code>type</code></dt><dd>The type of the content (will be derived from the directory automatically if unset)</dd>
* **markup** *(Experimental)* Specify `"rst"` for reStructuredText (requires <dt><code>weight</code></dt><dd>Used for sorting</dd>
`rst2html`) or `"md"` (default) for Markdown <dt><code>markup</code></dt><dd><em>(Experimental)</em> Specify <code>"rst"</code> for reStructuredText (requires <code>rst2html</code>) or <code>"md"</code> (default) for Markdown</dd>
* **slug** The token to appear in the tail of the URL, <dt><code>slug</code></dt><dd>The token to appear in the tail of the URL, <em>or</em></dd>
*or*<br> <dt><code>url</code></dt><dd>The full path to the content from the web root.<br></dd>
* **url** The full path to the content from the web root.<br> </dl>
*If neither `slug` or `url` is present, the filename will be used.* *If neither `slug` or `url` is present, the filename will be used.*

30
docs/content/extras/menus.md
View file

@ -27,24 +27,30 @@ access it via `.Site.Menus.main`.
A menu entry has the following properties: A menu entry has the following properties:
* **Url** string <dl>
* **Name** string <dt><code>Url</code></dt> <dd>string</dd>
* **Menu** string <dt><code>Name</code></dt> <dd>string</dd>
* **Identifier** string <dt><code>Menu</code></dt> <dd>string</dd>
* **Pre** template.HTML <dt><code>Identifier</code></dt> <dd>string</dd>
* **Post** template.HTML <dt><code>Pre</code></dt> <dd>template.HTML</dd>
* **Weight** int <dt><code>Post</code></dt> <dd>template.HTML</dd>
* **Parent** string <dt><code>Weight</code></dt> <dd>int</dd>
* **Children** Menu <dt><code>Parent</code></dt> <dd>string</dd>
<dt><code>Children</code></dt> <dd>Menu</dd>
</dl>
And the following functions: And the following functions:
* **HasChildren** bool <dl>
<dt><code>HasChildren</code></dt> <dd>bool</dd>
</dl>
Additionally, there are some relevant functions available on the page: Additionally, there are some relevant functions available on the page:
* **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool <dl>
* **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool <dt><code>IsMenuCurrent</code></dt> <dd>(menu string, menuEntry *MenuEntry ) bool</dd>
<dt><code>HasMenuCurrent</code></dt> <dd>(menu string, menuEntry *MenuEntry) bool</dd>
</dl>
## Adding content to menus ## Adding content to menus

25
docs/content/extras/permalinks.md
View file

@ -39,15 +39,16 @@ the URL <http://yoursite.example.com/2013/11/sample-entry/>.
The following is a list of values that can be used in a permalink definition. The following is a list of values that can be used in a permalink definition.
All references to time are dependent on the content's date. All references to time are dependent on the content's date.
* **:year** the 4-digit year <dl>
* **:month** the 2-digit month <dt><code>:year</code></dt><dd>the 4-digit year</dd>
* **:monthname** the name of the month <dt><code>:month</code></dt><dd>the 2-digit zero-padded month (01, 02, …, 12)</dd>
* **:day** the 2-digit day <dt><code>:monthname</code></dt><dd>the name of the month in English (“January”, “February”, …)</dd>
* **:weekday** the 1-digit day of the week (Sunday = 0) <dt><code>:day</code></dt><dd>the 2-digit zero-padded day (01, 02, …, 31)</dd>
* **:weekdayname** the name of the day of the week <dt><code>:weekday</code></dt><dd>the 1-digit day of the week (Sunday = 0)</dd>
* **:yearday** the 1- to 3-digit day of the year <dt><code>:weekdayname</code></dt><dd>the name of the day of the week in English (“Sunday”, “Monday”, …)</dd>
* **:section** the content's section <dt><code>:yearday</code></dt><dd>the 1- to 3-digit day of the year, in the range [1,365] or [1,366]</dd>
* **:title** the content's title <dt><code>:section</code></dt><dd>the content’s section</dd>
* **:slug** the content's slug (or title if no slug) <dt><code>:title</code></dt><dd>the content’s title</dd>
* **:filename** the content's filename (without extension) <dt><code>:slug</code></dt><dd>the content’s slug (or title if no slug)</dd>
<dt><code>:filename</code></dt><dd>the content’s filename (without extension)</dd>
</dl>

33
docs/content/taxonomies/methods.md
View file

@ -16,10 +16,12 @@ Hugo makes a set of values and methods available on the various Taxonomy structu
A Taxonomy is a `map[string]WeightedPages`. A Taxonomy is a `map[string]WeightedPages`.
**.Get(term)** Returns the WeightedPages for a term. <br> <dl>
**.Count(term)** The number of pieces of content assigned to this term.<br> <dt><code>.Get(term)</code></dt><dd>Returns the WeightedPages for a term.</dd>
**.Alphabetical** Returns an OrderedTaxonomy (slice) ordered by Term. <br> <dt><code>.Count(term)</code></dt><dd>The number of pieces of content assigned to this term.</dd>
**.ByCount** Returns an OrderedTaxonomy (slice) ordered by number of entries. <br> <dt><code>.Alphabetical</code></dt><dd>Returns an OrderedTaxonomy (slice) ordered by Term.</dd>
<dt><code>.ByCount</code></dt><dd>Returns an OrderedTaxonomy (slice) ordered by number of entries.</dd>
</dl>
## OrderedTaxonomy ## OrderedTaxonomy
@ -32,10 +34,12 @@ Since Maps are unordered, an OrderedTaxonomy is a special structure that has a d
Each element of the slice has: Each element of the slice has:
**.Term** The Term used.<br> <dl>
**.WeightedPages** A slice of Weighted Pages.<br> <dt><code>.Term</code></dt><dd>The Term used.</dd>
**.Count** The number of pieces of content assigned to this term.<br> <dt><code>.WeightedPages</code></dt><dd>A slice of Weighted Pages.</dd>
**.Pages** All Pages assigned to this term. All [list methods](/templates/list/) are available to this.<br> <dt><code>.Count</code></dt><dd>The number of pieces of content assigned to this term.</dd>
<dt><code>.Pages</code></dt><dd>All Pages assigned to this term. All <a href="/templates/list/">list methods</a> are available to this.</dd>
</dl>
## WeightedPages ## WeightedPages
@ -43,12 +47,7 @@ WeightedPages is simply a slice of WeightedPage.
type WeightedPages []WeightedPage type WeightedPages []WeightedPage
**.Count(term)** The number of pieces of content assigned to this term.<br> <dl>
**.Pages** Returns a slice of pages, which then can be ordered using any of the [list methods](/templates/list/). <br> <dt><code>.Count(term)</code></dt><dd>The number of pieces of content assigned to this term.</dd>
<dt><code>.Pages</code></dt><dd>Returns a slice of pages, which then can be ordered using any of the <a href="/templates/list/">list methods</a>.</dd>
</dl>

157
docs/content/templates/variables.md
View file

@ -22,94 +22,111 @@ The following is a list of most of the accessible variables which can be
defined for a piece of content. Many of these will be defined in the front defined for a piece of content. Many of these will be defined in the front
matter, content or derived from file location. matter, content or derived from file location.
**.Title** The title for the content.<br> <dl>
**.Content** The content itself, defined below the front matter.<br> <dt><code>.Title</code></dt><dd> The title for the content.</dd>
**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page.<br> <dt><code>.Content</code></dt><dd>The content itself, defined below the front matter.</dd>
**.Description** The description for the content.<br>
**.Keywords** The meta keywords for this content.<br> <dt><code>.Summary</code></dt>
**.Date** The date the content is associated with.<br> <dd>A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page.</dd>
**.PublishDate** The date the content is published on.<br>
**.Type** The content [type](/content/types/) (e.g. post).<br> <dt><code>.Description</code></dt><dd>The description for the content.</dd>
**.Section** The [section](/content/sections/) this content belongs to.<br> <dt><code>.Keywords</code></dt><dd>The meta keywords for this content.</dd>
**.Permalink** The Permanent link for this page.<br> <dt><code>.Date</code></dt><dd>The date the content is associated with.</dd>
**.RelPermalink** The Relative permanent link for this page.<br> <dt><code>.PublishDate</code></dt><dd>The date the content is published on.</dd>
**.LinkTitle** Access when creating links to this content. Will use linktitle if set in front-matter, else title.<br> <dt><code>.Type</code></dt><dd>The content <a href="/content/types/">type</a> (e.g. post).</dd>
**.Taxonomies** These will use the field name of the plural form of the index (see tags and categories above).<br> <dt><code>.Section</code></dt><dd>The <a href="/content/sections/">section</a> this content belongs to.</dd>
**.RSSLink** Link to the indexes' rss link.<br> <dt><code>.Permalink</code></dt><dd>The Permanent link for this page.</dd>
**.TableOfContents** The rendered table of contents for this content.<br> <dt><code>.RelPermalink</code></dt><dd>The Relative permanent link for this page.</dd>
**.Prev** Pointer to the previous content (based on pub date).<br> <dt><code>.LinkTitle</code></dt><dd>Access when creating links to this content. Will use linktitle if set in front-matter, else title.</dd>
**.Next** Pointer to the following content (based on pub date).<br> <dt><code>.Taxonomies</code></dt><dd>These will use the field name of the plural form of the index (see tags and categories above).</dd>
**.PrevInSection** Pointer to the previous content within the same section (based on pub date)<br> <dt><code>.RSSLink</code></dt><dd>Link to the indexes’ RSS link.</dd>
**.NextInSection** Pointer to the following content within the same section (based on pub date)<br> <dt><code>.TableOfContents</code></dt><dd>The rendered table of contents for this content.</dd>
**.FuzzyWordCount** The approximate number of words in the content.<br> <dt><code>.Prev</code></dt><dd>Pointer to the previous content (based on pub date).</dd>
**.WordCount** The number of words in the content.<br> <dt><code>.Next</code></dt><dd>Pointer to the following content (based on pub date).</dd>
**.ReadingTime** The estimated time it takes to read the content in minutes.<br> <dt><code>.PrevInSection</code></dt><dd>Pointer to the previous content within the same section (based on pub date)</dd>
**.Weight** Assigned weight (in the front matter) to this content, used in sorting.<br> <dt><code>.NextInSection</code></dt><dd>Pointer to the following content within the same section (based on pub date)</dd>
**.IsNode** Always false for pages.<br> <dt><code>.FuzzyWordCount</code></dt><dd>The approximate number of words in the content.</dd>
**.IsPage** Always true for page.<br> <dt><code>.WordCount</code></dt><dd>The number of words in the content.</dd>
**.Site** See site variables below.<br> <dt><code>.ReadingTime</code></dt><dd>The estimated time it takes to read the content in minutes.</dd>
**.Hugo** See Hugo variables below<br> <dt><code>.Weight</code></dt><dd>Assigned weight (in the front matter) to this content, used in sorting.</dd>
<dt><code>.IsNode</code></dt><dd>Always false for pages.</dd>
<dt><code>.IsPage</code></dt><dd>Always true for page.</dd>
<dt><code>.Site</code></dt><dd>See Site Variables below.</dd>
<dt><code>.Hugo</code></dt><dd>See Hugo Variables below</dd>
</dl>
## Page Params ## Page Params
Any other value defined in the front matter, including indexes will be made available under `.Params`. Any other value defined in the front matter, including indexes will be made available under `.Params`.
Take for example I'm using tags and categories as my indexes. The following would be how I would access them: Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
**.Params.tags** <br> * `.Params.tags`
**.Params.categories** <br> * `.Params.categories`
<br>
**All Params are only accessible using all lowercase characters**<br> **All Params are only accessible using all lowercase characters**
## Node Variables ## Node Variables
In Hugo a node is any page not rendered directly by a content file. This In Hugo, a node is any page not rendered directly by a content file. This
includes indexes, lists and the homepage. includes indexes, lists and the homepage.
**.Title** The title for the content.<br> <dl>
**.Date** The date the content is published on.<br> <dt><code>.Title</code></dt><dd> The title for the content.</dd>
**.Permalink** The Permanent link for this node<br> <dt><code>.Date</code></dt><dd>The date the content is published on.</dd>
**.Url** The relative url for this node.<br> <dt><code>.Permalink</code></dt><dd>The Permanent link for this node</dd>
**.Ref(ref)** Returns the permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br> <dt><code>.Url</code></dt><dd>The relative URL for this node.</dd>
**.RelRef(ref)** Returns the relative permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br> <dt><code>.Ref(ref)</code></dt>
**.RSSLink** Link to the indexes' rss link <br> <dd>Returns the permalink for <code>ref</code>. See <a href="{{% ref "extras/crossreferences.md" %}}">cross-references</a>. Does not handle in-page fragments correctly.</dd>
**.Data** The data specific to this type of node.<br> <dt><code>.RelRef(ref)</code></dt>
**.IsNode** Always true for nodes.<br> <dd>Returns the relative permalink for <code>ref</code>. See <a href="{{% ref "extras/crossreferences.md" %}}">cross-references</a>. Does not handle in-page fragments correctly.</dd>
**.IsPage** Always false for nodes.<br> <dt><code>.RSSLink</code></dt><dd>Link to the indexes’ RSS link</dd>
**.Site** See site variables below<br> <dt><code>.Data</code></dt><dd>The data specific to this type of node.</dd>
**.Hugo** See site variables below<br> <dt><code>.IsNode</code></dt><dd>Always true for nodes.</dd>
<dt><code>.IsPage</code></dt><dd>Always false for nodes.</dd>
<dt><code>.Site</code></dt><dd>See Site Variables below</dd>
<dt><code>.Hugo</code></dt><dd>See Hugo Variables below</dd>
</dl>
## Site Variables ## Site Variables
Also available is `.Site` which has the following: Also available is `.Site` which has the following:
**.Site.BaseUrl** The base URL for the site as defined in the site configuration file.<br> <dl>
**.Site.Taxonomies** The indexes for the entire site.<br> <dt><code>.Site.BaseUrl</code></dt><dd>The base URL for the site as defined in the site configuration file.</dd>
**.Site.LastChange** The date of the last change of the most recent content.<br> <dt><code>.Site.Taxonomies</code></dt><dd>The indexes for the entire site.</dd>
**.Site.Recent** Array of all content ordered by Date, newest first.<br> <dt><code>.Site.LastChange</code></dt><dd>The date of the last change of the most recent content.</dd>
**.Site.Params** A container holding the values from the `params` section of your site configuration file. For example, a TOML config file might look like this: <dt><code>.Site.Recent</code></dt><dd>Array of all content ordered by Date, newest first.</dd>
<dt><code>.Site.Params</code></dt><dd>A container holding the values from the <code>params</code> section of your site configuration file. For example, a TOML config file might look like this:
<pre><code>baseurl = "http://yoursite.example.com/"
baseurl = "http://yoursite.example.com/" [params]
description = "Tesla's Awesome Hugo Site"
[params] author = "Nikola Tesla"
description = "Tesla's Awesome Hugo Site" </code></pre></dd>
author = "Nikola Tesla" <dt><code>.Site.Sections</code></dt><dd>Top level directories of the site.</dd>
**.Site.Sections** Top level directories of the site.<br> <dt><code>.Site.Pages</code></dt><dd>All of the content pages of the site.</dd>
**.Site.Pages** All of the content pages of the site.<br> <dt><code>.Site.Files</code></dt><dd>All of the source files of the site.</dd>
**.Site.Files** All of the source files of the site.<br> <dt><code>.Site.Menus</code></dt><dd>All of the menus in the site.</dd>
**.Site.Menus** All of the menus in the site.<br> <dt><code>.Site.Title</code></dt><dd>A string representing the title of the site.</dd>
**.Site.Title** A string representing the title of the site.<br> <dt><code>.Site.Author</code></dt><dd>A map of the authors as defined in the site configuration.</dd>
**.Site.Author** A map of the authors as defined in the site configuration.<br> <dt><code>.Site.LanguageCode</code></dt><dd>A string representing the language as defined in the site configuration.</dd>
**.Site.LanguageCode** A string representing the language as defined in the site configuration.<br> <dt><code>.Site.DisqusShortname</code></dt><dd>A string representing the shortname of the Disqus shortcode as defined in the site configuration.</dd>
**.Site.DisqusShortname** A string representing the shortname of the Disqus shortcode as defined in the site configuration.<br> <dt><code>.Site.Copyright</code></dt><dd>A string representing the copyright of your web site as defined in the site configuration.</dd>
**.Site.Copyright** A string representing the copyright of your web site as defined in the site configuration.<br> <dt><code>.Site.LastChange</code></dt><dd>A string representing the last time content has been updated.</dd>
**.Site.LastChange** A string representing the last time content has been updated.<br> <dt><code>.Site.Permalinks</code></dt><dd>A string to override the default permalink format. Defined in the site configuration.</dd>
**.Site.Permalinks** A string to override the default permalink format. Defined in the site configuration.<br> <dt><code>.Site.BuildDrafts</code></dt><dd>A boolean (Default: false) to indicate whether to build drafts. Defined in the site configuration.</dd>
**.Site.BuildDrafts** A boolean (Default: false) to indicate whether to build drafts. Defined in the site configuration.<br> </dl>
## Hugo Variables ## Hugo Variables
Also available is `.Hugo` which has the following: Also available is `.Hugo` which has the following:
**.Hugo.Generator** Meta tag for the version of Hugo that generated the site. Highly recommended to be included by default in all theme headers so we can start to track Hugo usage and popularity. e.g. `<meta name="generator" content="Hugo 0.13" />`<br> <dl>
**.Hugo.Version** The current version of the Hugo binary you are using e.g. `0.13-DEV`<br> <dt><code>.Hugo.Generator</code></dt>
**.Hugo.CommitHash** The git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`<br> <dd>Meta tag for the version of Hugo that generated the site. Highly recommended to be included by default in all theme headers so we can start to track Hugo usage and popularity, e.g.&nbsp;<code>&lt;meta name="generator" content="Hugo 0.13" /&gt;</code></dd>
**.Hugo.BuildDate** The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br> <dt><code>.Hugo.Version</code></dt>
<dd>The current version of the Hugo binary you are using, e.g.&nbsp;<code>0.13-DEV</code></dd>
<dt><code>.Hugo.CommitHash</code></dt>
<dd>The git commit hash of the current Hugo binary, e.g.&nbsp;<code>0e8bed9ccffba0df554728b46c5bbf6d78ae5247</code></dd>
<dt><code>.Hugo.BuildDate</code></dt>
<dd>The compile date of the current Hugo binary formatted with RFC 3339, e.g.&nbsp;<code>2002-10-02T10:00:00-05:00</code></dd>
</dl>

20
docs/static/css/style.css vendored
View file

@ -500,3 +500,23 @@ td.purpose-title {
td.purpose-description { td.purpose-description {
border-left: 0; border-left: 0;
} }
/* For definitions of variables */
dl {
margin: 1em;
border-bottom: 1px solid #ccc;
}
dt {
float: left;
clear: left;
width: 9.5em;
margin: 0.125em;
padding: 2px 4px;
}
dd {
padding: 0.2em 0 0.2em 10em;
border-top: 1px solid #ccc;
}