diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md index 0d07bc947..259d9acfb 100644 --- a/docs/content/overview/configuration.md +++ b/docs/content/overview/configuration.md @@ -1,7 +1,7 @@ --- aliases: - /doc/configuration/ -lastmod: 2016-07-22 +lastmod: 2016-09-17 date: 2013-07-01 linktitle: Configuration menu: @@ -13,71 +13,88 @@ prev: /overview/usage title: Configuring Hugo weight: 40 --- +The directory structure of a Hugo web site—or more precisely, +of the source files containing its content and templates—provide +most of the configuration information that Hugo needs. +Therefore, in essence, +many web sites wouldn't actually need a configuration file. +This is because Hugo is designed to recognize certain typical usage patterns +(and it expects them, by default). -The directory structure and templates provide the majority of the -configuration for a site. In fact, a config file isn't even needed for many -websites since the defaults follow commonly used patterns. +Nevertheless, Hugo does search for a configuration file bearing +a particular name in the root of your web site's source directory. +First, it looks for a `./config.toml` file. +If that's not present, it will seek a `./config.yaml` file, +followed by a `./config.json` file. -Hugo expects to find the config file in the root of the source directory and -will look there first for a `config.toml` file. If none is present, it will -then look for a `config.yaml` file, followed by a `config.json` file. - -The config file is a site-wide config. The config file provides directions to -hugo on how to build the site as well as site-wide parameters and menus. - -Site configuration can also be set as environment variables in your operating system. The command below will work on *nix systems and overrides the site title. Note that all the variable names must be prefixed with "HUGO_". +In this `config` file for your web site, +you can include precise directions to Hugo regarding +how it should render your site, as well as define its menus, +and set various other site-wide parameters. +Another way that web site configuration can be accomplished is through +operating system environment variables. +For instance, the following command will work on Unix-like systems—it +sets a web site's title: ```bash -env HUGO_TITLE="Some Title" hugo +$ env HUGO_TITLE="Some Title" hugo ``` +(**Note:** all such environment variable names must be prefixed with +HUGO_.) ## Examples -The following is an example of a typical yaml config file: +Following is a typical example of a YAML configuration file. +Three periods end the document: - --- - baseurl: "http://yoursite.example.com/" - ... +```yaml +--- +baseurl: "http://yoursite.example.com/" +... +``` +Following is an example TOML configuration file with some default values. +The values under `[params]` will populate the `.Site.Params` variable +for use in templates: -The following is an example of a toml config file with some of the default values. -Values under `[params]` will populate the `.Site.Params` variable for use in templates: +```toml +contentdir = "content" +layoutdir = "layouts" +publishdir = "public" +builddrafts = false +baseurl = "http://yoursite.example.com/" +canonifyurls = true - contentdir = "content" - layoutdir = "layouts" - publishdir = "public" - builddrafts = false - baseurl = "http://yoursite.example.com/" - canonifyurls = true +[taxonomies] + category = "categories" + tag = "tags" - [taxonomies] - category = "categories" - tag = "tags" - - [params] - description = "Tesla's Awesome Hugo Site" - author = "Nikola Tesla" - -Here is a yaml configuration file which sets a few more options: - - --- - baseurl: "http://yoursite.example.com/" - title: "Yoyodyne Widget Blogging" - footnotereturnlinkcontents: "↩" - permalinks: - post: /:year/:month/:title/ - params: - Subtitle: "Spinning the cogs in the widgets" - AuthorName: "John Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 - ... +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +``` +Here is a YAML configuration file which sets a few more options: +```yaml +--- +baseurl: "http://yoursite.example.com/" +title: "Yoyodyne Widget Blogging" +footnotereturnlinkcontents: "↩" +permalinks: + post: /:year/:month/:title/ +params: + Subtitle: "Spinning the cogs in the widgets" + AuthorName: "John Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +... +``` ## Configuration variables -Following is a list of Hugo-defined variables that you can configure and their current default values: +Following is a list of Hugo-defined variables you can configure, +along with their current, default values: --- archetypedir: "archetype" @@ -175,212 +192,309 @@ Following is a list of Hugo-defined variables that you can configure and their c watch: true --- -## Ignore files on build +## Ignore various files when rendering -The following inside `config.toml` will ignore files ending with `.foo` and `.boo` when building with `hugo`: +The following statement inside `./config.toml` will cause Hugo to ignore files +ending with `.foo` and `.boo` when rendering: -``` +```toml ignoreFiles = [ "\\.foo$", "\\.boo$" ] ``` - -The above is a list of Regular Expressions, but note the escaping of the `\` to make TOML happy. - - +The above is a list of regular expressions. +Note that the backslash (`\`) character is escaped, to keep TOML happy. ## Configure Blackfriday rendering -[Blackfriday](https://github.com/russross/blackfriday) is the [Markdown](http://daringfireball.net/projects/markdown/) rendering engine used in Hugo. The Blackfriday configuration in Hugo is mostly a set of sane defaults that should fit most use cases. +[Blackfriday](https://github.com/russross/blackfriday) is Hugo's +[Markdown](http://daringfireball.net/projects/markdown/) +rendering engine. -But Hugo does expose some options---as listed in the table below, matched with the corresponding flag in the Blackfriday source ([html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)): +In the main, Hugo typically configures Blackfriday with a sane set of defaults. +These defaults should fit most use cases, reasonably well. - - - - - - +However, if you have unusual needs with respect to Markdown, +Hugo exposes some of its Blackfriday behavior options for you to alter. +The following table lists these Hugo options, +paired with the corresponding flags from Blackfriday's source code (for the latter, see +[html.go](https://github.com/russross/blackfriday/blob/master/html.go) and +[markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
FlagDefaultBlackfriday flag
taskListstrue
Purpose:Turn off GitHub styled automatic task/TODO list generation. -
smartypantstrueHTML_USE_SMARTYPANTS
Purpose:Enable/Disable smart punctuation substitutions such as smart quotes, smart dashes, etc. -May be fine-tuned with the angledQuotes, fractions, smartDashes and latexDashes flags below.
angledQuotesfalseHTML_SMARTYPANTS_ANGLED_QUOTES
Purpose:Enable/Disable smart angled double quotes.
-Example: "Hugo" renders to «Hugo» instead of “Hugo”.
fractionstrueHTML_SMARTYPANTS_FRACTIONS
Purpose:Enable/Disable smart fractions.
-Example: 5/12 renders to 5⁄12 (<sup>5</sup>&frasl;<sub>12</sub>)
-Caveat: Even with fractions = false, -Blackfriday would still convert 1/2, 1/4 and 3/4 to ½ (&frac12;), -¼ (&frac14;) and ¾ (&frac34;) respectively, -but only these three.
smartDashestrueHTML_SMARTYPANTS_DASHES
Purpose:Enable/Disable smart dashes, i.e. turning hyphens into en dash or em dash.
-Its behavior can be modified with the latexDashes flag listed below.
latexDashestrueHTML_SMARTYPANTS_LATEX_DASHES
Purpose:Choose between LaTeX-style smart dashes and “conventional” smart dashes.
-If true, -- is translated into “–” (&ndash;), and --- is translated into “—” (&mdash;).
-If false, -- is translated into “—” (&mdash;), whereas a spaced single hyphen between two words is turned into an en dash, e.g. 12 June - 3 July becomes 12 June &ndash; 3 July.
hrefTargetBlankfalseHTML_HREF_TARGET_BLANK
Purpose:Open external links in a new window/tab.
plainIDAnchorstrueFootnoteAnchorPrefix and HeaderIDSuffix
Purpose:If true, then header and footnote IDs are generated without the document ID.
-Example: #my-header instead of #my-header:bec3ed8ba720b9073ab75abcf3ba5d97.
extensions[]EXTENSION_*
Purpose:Use non-default additional extensions.
-Example: Add "hardLineBreak" to use EXTENSION_HARD_LINE_BREAK.
extensionsmask[]EXTENSION_*
Purpose:Extensions in this option won't be loaded.
-Example: Add "autoHeaderIds" to disable EXTENSION_AUTO_HEADER_IDS.
sourceRelativeLinksEvalfalsenone
Purpose:Source file based relative linking (a la Github).
-Relative links to markdown and static files within a page will be evaluated relative to the -location of that page, and then converted to html links during rendering. For example, -`[example](../other/page.md)` in `content/total/overview.md` will be linked to -`content/other/overview.md`, and then rendered to `/other/overview/` in the HTML output. -
sourceRelativeLinksProjectFolder"/docs/content"none
Purpose:Source file based relative linking Hugo Project sub-folder.
-When `sourceRelativeLinksEval` is enabled, source level paths may contain an absolute respository path to the -markdown or static file which needs to be removed before trying to match it with the intended link. - For example, if your documentation is in `/docs/content`, then -`[example](/docs/content/other/page.md)` in `/docs/content/total/overview.md` will be linked to -`/docs/content/other/overview.md`, and then rendered to `/other/overview/` in the HTML output. -
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDefaultBlackfriday flag
taskListstrue
+ Purpose: + false turns off GitHub-style automatic task/TODO + list generation. +
smartypantstrueHTML_USE_SMARTYPANTS
+ Purpose: + false disables smart punctuation substitutions + including smart quotes, smart dashes, smart fractions, etc. + If true, it may be fine-tuned with the + angledQuotes, + fractions, + smartDashes and + latexDashes flags (see below). +
angledQuotesfalseHTML_SMARTYPANTS_ANGLED_QUOTES
+ Purpose: + true enables smart, angled double quotes.
+ + Example: + "Hugo" renders to + «Hugo» instead of “Hugo”. + +
fractionstrueHTML_SMARTYPANTS_FRACTIONS
+ Purpose: + false disables smart fractions.
+ + Example: + 5/12 renders to + 5⁄12 + (<sup>5</sup>&frasl;<sub>12</sub>).
+ Caveat: + Even with fractions = false, + Blackfriday still converts + 1/2, 1/4 and 3/4 respectively to + ½ (&frac12;), + ¼ (&frac14;) and + ¾ (&frac34;), + but only these three. +
smartDashestrueHTML_SMARTYPANTS_DASHES
+ Purpose: + false disables smart dashes; i.e., the conversion + of multiple hyphens into en dash or em dash. + If true, its behavior can be modified with the + latexDashes flag below. +
latexDashestrueHTML_SMARTYPANTS_LATEX_DASHES
+ Purpose: + false disables LaTeX-style smart dashes and + selects conventional smart dashes. Assuming + smartDashes (above), if this is: +
    +
  • + true, then + -- is translated into “–” + (&ndash;), whereas + --- is translated into “—” + (&mdash;). +
    • +
  • + false, then + -- is translated into “—” + (&mdash;), whereas a + spaced single hyphen between two words + is translated into an en dash—e.g., + 12 June - 3 July becomes + 12 June &ndash; 3 July. +
    • +
+
hrefTargetBlankfalseHTML_HREF_TARGET_BLANK
+ Purpose: + true opens external links in a new window or tab. +
plainIDAnchorstrue + FootnoteAnchorPrefix and + HeaderIDSuffix +
+ Purpose: + true renders any header and footnote IDs + without the document ID.
+ + Example: + renders #my-header instead of + #my-header:bec3ed8ba720b9073ab75abcf3ba5d97. + +
extensions[]EXTENSION_*
+ Purpose: + Enable one or more of Blackfriday's Markdown extensions + (if they aren't Hugo defaults).
+ + Example:   + Include "hardLineBreak" + in the list to enable Blackfriday's + EXTENSION_HARD_LINE_BREAK. + +
extensionsmask[]EXTENSION_*
+ Purpose: + Disable one or more of Blackfriday's Markdown extensions + (if they are Hugo defaults).
+ + Example:   + Include "autoHeaderIds" + in the list to disable Blackfriday's + EXTENSION_AUTO_HEADER_IDS. + +
sourceRelativeLinksEvalfalsenone
+ Purpose: + true enables source file-based relative linking (à la Github). + Relative links to Markdown and static files within a page + will be evaluated relative to the location of that page, + and then converted to HTML links during rendering.
+ + Example: + [some-reference-text](../other/page.md) in + ./content/total/overview.md will link to + ./content/other/overview.md and render to + /other/overview/ in the HTML output. + +
sourceRelativeLinksProjectFolder/docs/contentnone
+ Purpose: + Set a sub-folder for source file-based relative linking + on a Hugo Project (i.e., a web site). When + sourceRelativeLinksEval (see above) is enabled, + some source level paths may contain absolute respository + paths to Markdown or static files. + The absolute portion of these paths should be removed + before trying to match the intended links.
+ + Example: + Assuming your documentation resides in + ./docs/content, + then a reference within + ./docs/content/total/overview.md to + [some-reference-text](/docs/content/other/page.md) + will link to + ./docs/content/other/overview.md and render to + /other/overview/ in the HTML output. + +
- **Notes** -1. These flags are **very case-sensitive** (as of Hugo v0.15)! -2. These flags must be grouped under the `blackfriday` key and can be set on **both site and page level**. If set on page, it will override the site setting. Example: +* These flags are **case sensitive** (as of Hugo v0.15)! +* These flags must be grouped under the `blackfriday` key +and can be set on **both the site level and the page level**. +Any setting on a page will override the site setting +there. For example: - - - - - - - - + + + + + + + + - + - - + + + +
TOMLYAML
[blackfriday]
+
TOMLYAML
+
[blackfriday]
   angledQuotes = true
   fractions = false
   plainIDAnchors = true
   extensions = ["hardLineBreak"]
-
blackfriday:
+
+ 		+
blackfriday:
   angledQuotes: true
   fractions: false
   plainIDAnchors: true
   extensions:
     - hardLineBreak
-
diff --git a/docs/layouts/partials/header.html b/docs/layouts/partials/header.html index d1f44d7f2..ff386eae4 100644 --- a/docs/layouts/partials/header.html +++ b/docs/layouts/partials/header.html @@ -14,6 +14,7 @@ + diff --git a/docs/static/css/content-style.css b/docs/static/css/content-style.css new file mode 100644 index 000000000..1356b0495 --- /dev/null +++ b/docs/static/css/content-style.css @@ -0,0 +1,84 @@ +/* Styles used by tables at the URLs: + + 1. /overview/configuration/#configure-blackfriday-rendering + 2. /templates/functions/#math + +Their HTML is in the files: + + 1. ./docs/content/overview/configuration.md + 2. ./docs/content/templates/functions.md +*/ + +table.table { + margin: 1em 0; +} +table.table-bordered tr th, +table.table-bordered tr td { + border-width: 2px; + border-color: #dddddd; + border-style: solid; + padding: 0 0.5em; +} +table.table-bordered-configuration { + max-width: 100%; +} +table.table-bordered-configuration, +table.table-bordered-configuration tr, +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td:not(.purpose-description) { + border-width: 2px; +} +table.table-bordered-configuration tr td.purpose-description { + border-width: 1px; +} +table.table-bordered-configuration, +table.table-bordered-configuration tr, +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td { + border-color: #dddddd; +} +table.table-bordered-configuration { + border-right-style: solid; + border-bottom-style: solid; +} +table.table-bordered-configuration tr, +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td:not(.purpose-description) { + border-left-style: solid; +} +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td:not(.purpose-description) { + border-top-style: solid; +} +table.table-bordered-configuration tr td.purpose-description { + border-top-style: dotted; +} +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td { + padding-top: 0; + padding-right: 0.5em; + padding-left: 0.5em; +} +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td:not(.purpose-description) { + padding-bottom: 0; +} +table.table-bordered-configuration tr td.purpose-description { + padding-bottom: 0.5em; +} +table.table-bordered-configuration tr th, +table.table-bordered-configuration tr td:not(.purpose-description) { + text-align: center; +} +table.table-bordered-configuration tr td:not(.purpose-description) code { + padding: 0; + border-radius: 0; + font-size: 14px; + background-color: inherit; + color: darkgreen; +} +table.table-bordered-configuration tr td span.purpose-title { + padding-right: 0.15em; + font-style: italic; + color: chocolate; +} diff --git a/docs/static/css/style.css b/docs/static/css/style.css index 255f1c825..312c247c9 100644 --- a/docs/static/css/style.css +++ b/docs/static/css/style.css @@ -498,30 +498,6 @@ kbd { font-size: 0.85em; } -/* For the table used in overview/configuration */ - -table.table { - margin: 1em 0; -} - -.table-bordered th, -.table-bordered td { - border: 2px solid #ddd; - padding: 0 0.5em; -} - -td.purpose-title { - text-align: right; - vertical-align: top; - border-right: 0; - padding-right: 0.5em; - font-weight: bold; -} - -td.purpose-description { - border-left: 0; -} - /* For definitions of variables */ dl { @@ -705,4 +681,4 @@ i.freebsd-19px:before { .algolia-docsearch-suggestion--category-header, .algolia-docsearch-suggestion--subcategory-column { display: none !important; -} \ No newline at end of file +}