mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
docs: Improve Overview Configuration manual
This commit is contained in:
Mark D. Blackwell
parent
a7af63037c
commit
83533a8881
4 changed files with 434 additions and 259 deletions
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
aliases:
|
aliases:
|
||||||
- /doc/configuration/
|
- /doc/configuration/
|
||||||
lastmod: 2016-07-22
|
lastmod: 2016-09-17
|
||||||
date: 2013-07-01
|
date: 2013-07-01
|
||||||
linktitle: Configuration
|
linktitle: Configuration
|
||||||
menu:
|
menu:
|
||||||
|
|
@ -13,59 +13,75 @@ prev: /overview/usage
|
||||||
title: Configuring Hugo
|
title: Configuring Hugo
|
||||||
weight: 40
|
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
|
Nevertheless, Hugo does search for a configuration file bearing
|
||||||
configuration for a site. In fact, a config file isn't even needed for many
|
a particular name in the root of your web site's source directory.
|
||||||
websites since the defaults follow commonly used patterns.
|
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
|
In this `config` file for your web site,
|
||||||
will look there first for a `config.toml` file. If none is present, it will
|
you can include precise directions to Hugo regarding
|
||||||
then look for a `config.yaml` file, followed by a `config.json` file.
|
how it should render your site, as well as define its menus,
|
||||||
|
and set various other site-wide parameters.
|
||||||
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_".
|
|
||||||
|
|
||||||
|
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
|
```bash
|
||||||
env HUGO_TITLE="Some Title" hugo
|
$ env HUGO_TITLE="Some Title" hugo
|
||||||
```
|
```
|
||||||
|
(**Note:** all such environment variable names must be prefixed with
|
||||||
|
<code>HUGO_</code>.)
|
||||||
|
|
||||||
## Examples
|
## 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:
|
||||||
|
|
||||||
---
|
```yaml
|
||||||
baseurl: "http://yoursite.example.com/"
|
---
|
||||||
...
|
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.
|
```toml
|
||||||
Values under `[params]` will populate the `.Site.Params` variable for use in templates:
|
contentdir = "content"
|
||||||
|
layoutdir = "layouts"
|
||||||
|
publishdir = "public"
|
||||||
|
builddrafts = false
|
||||||
|
baseurl = "http://yoursite.example.com/"
|
||||||
|
canonifyurls = true
|
||||||
|
|
||||||
contentdir = "content"
|
[taxonomies]
|
||||||
layoutdir = "layouts"
|
|
||||||
publishdir = "public"
|
|
||||||
builddrafts = false
|
|
||||||
baseurl = "http://yoursite.example.com/"
|
|
||||||
canonifyurls = true
|
|
||||||
|
|
||||||
[taxonomies]
|
|
||||||
category = "categories"
|
category = "categories"
|
||||||
tag = "tags"
|
tag = "tags"
|
||||||
|
|
||||||
[params]
|
[params]
|
||||||
description = "Tesla's Awesome Hugo Site"
|
description = "Tesla's Awesome Hugo Site"
|
||||||
author = "Nikola Tesla"
|
author = "Nikola Tesla"
|
||||||
|
```
|
||||||
|
Here is a YAML configuration file which sets a few more options:
|
||||||
|
|
||||||
Here is a yaml configuration file which sets a few more options:
|
```yaml
|
||||||
|
---
|
||||||
---
|
baseurl: "http://yoursite.example.com/"
|
||||||
baseurl: "http://yoursite.example.com/"
|
title: "Yoyodyne Widget Blogging"
|
||||||
title: "Yoyodyne Widget Blogging"
|
footnotereturnlinkcontents: "↩"
|
||||||
footnotereturnlinkcontents: "↩"
|
permalinks:
|
||||||
permalinks:
|
|
||||||
post: /:year/:month/:title/
|
post: /:year/:month/:title/
|
||||||
params:
|
params:
|
||||||
Subtitle: "Spinning the cogs in the widgets"
|
Subtitle: "Spinning the cogs in the widgets"
|
||||||
AuthorName: "John Doe"
|
AuthorName: "John Doe"
|
||||||
GitHubUser: "spf13"
|
GitHubUser: "spf13"
|
||||||
|
|
@ -73,11 +89,12 @@ Here is a yaml configuration file which sets a few more options:
|
||||||
- "foo1"
|
- "foo1"
|
||||||
- "foo2"
|
- "foo2"
|
||||||
SidebarRecentLimit: 5
|
SidebarRecentLimit: 5
|
||||||
...
|
...
|
||||||
|
```
|
||||||
## Configuration variables
|
## 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"
|
archetypedir: "archetype"
|
||||||
|
|
@ -175,212 +192,309 @@ Following is a list of Hugo-defined variables that you can configure and their c
|
||||||
watch: true
|
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$" ]
|
ignoreFiles = [ "\\.foo$", "\\.boo$" ]
|
||||||
```
|
```
|
||||||
|
The above is a list of regular expressions.
|
||||||
The above is a list of Regular Expressions, but note the escaping of the `\` to make TOML happy.
|
Note that the backslash (`\`) character is escaped, to keep TOML happy.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Configure Blackfriday rendering
|
## 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.
|
||||||
|
|
||||||
<table class="table table-bordered">
|
However, if you have unusual needs with respect to Markdown,
|
||||||
<thead>
|
Hugo exposes some of its Blackfriday behavior options for you to alter.
|
||||||
<tr>
|
The following table lists these Hugo options,
|
||||||
<th>Flag</th><th>Default</th><th>Blackfriday flag</th>
|
paired with the corresponding flags from Blackfriday's source code (for the latter, see
|
||||||
</tr>
|
[html.go](https://github.com/russross/blackfriday/blob/master/html.go) and
|
||||||
</thead>
|
[markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)):
|
||||||
|
|
||||||
<tbody>
|
<table class="table table-bordered-configuration">
|
||||||
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
<td><code><strong>taskLists</strong></code></td>
|
<th>Flag</th>
|
||||||
<td><code>true</code></td>
|
<th>Default</th>
|
||||||
<td><code></code></td>
|
<th>Blackfriday flag</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
</thead>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<tbody>
|
||||||
<td class="purpose-description" colspan="2">Turn off GitHub styled automatic task/TODO list generation.
|
<tr>
|
||||||
</td>
|
<td><code><strong>taskLists</strong></code></td>
|
||||||
</tr>
|
<td><code>true</code></td>
|
||||||
|
<td><code></code></td>
|
||||||
<tr>
|
</tr>
|
||||||
<td><code><strong>smartypants</strong></code></td>
|
<tr>
|
||||||
<td><code>true</code></td>
|
<td class="purpose-description" colspan="3">
|
||||||
<td><code>HTML_USE_SMARTYPANTS</code></td>
|
<span class="purpose-title">Purpose:</span>
|
||||||
</tr>
|
<code>false</code> turns off GitHub-style automatic task/TODO
|
||||||
<tr>
|
list generation.
|
||||||
<td class="purpose-title">Purpose:</td>
|
</td>
|
||||||
<td class="purpose-description" colspan="2">Enable/Disable smart punctuation substitutions such as smart quotes, smart dashes, etc.
|
</tr>
|
||||||
May be fine-tuned with the <code>angledQuotes</code>, <code>fractions</code>, <code>smartDashes</code> and <code>latexDashes</code> flags below.</td>
|
<tr>
|
||||||
</tr>
|
<td><code><strong>smartypants</strong></code></td>
|
||||||
|
<td><code>true</code></td>
|
||||||
<tr>
|
<td><code>HTML_USE_SMARTYPANTS</code></td>
|
||||||
<td><code><strong>angledQuotes</strong></code></td>
|
</tr>
|
||||||
<td><code>false</code></td>
|
<tr>
|
||||||
<td><code>HTML_SMARTYPANTS_ANGLED_QUOTES</code></td>
|
<td class="purpose-description" colspan="3">
|
||||||
</tr>
|
<span class="purpose-title">Purpose:</span>
|
||||||
<tr>
|
<code>false</code> disables smart punctuation substitutions
|
||||||
<td class="purpose-title">Purpose:</td>
|
including smart quotes, smart dashes, smart fractions, etc.
|
||||||
<td class="purpose-description" colspan="2">Enable/Disable smart angled double quotes.<br>
|
If <code>true</code>, it may be fine-tuned with the
|
||||||
<small><strong>Example:</strong> <code>"Hugo"</code> renders to «Hugo» instead of “Hugo”.</small></td>
|
<code>angledQuotes</code>,
|
||||||
</tr>
|
<code>fractions</code>,
|
||||||
|
<code>smartDashes</code> and
|
||||||
<tr>
|
<code>latexDashes</code> flags (see below).
|
||||||
<td><code><strong>fractions</strong></code></td>
|
</td>
|
||||||
<td><code>true</code></td>
|
</tr>
|
||||||
<td><code>HTML_SMARTYPANTS_FRACTIONS</code></td>
|
<tr>
|
||||||
</tr>
|
<td><code><strong>angledQuotes</strong></code></td>
|
||||||
<tr>
|
<td><code>false</code></td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<td><code>HTML_SMARTYPANTS_ANGLED_QUOTES</code></td>
|
||||||
<td class="purpose-description" colspan="2">Enable/Disable smart fractions.<br>
|
</tr>
|
||||||
<small><strong>Example:</strong> <code>5/12</code> renders to <sup>5</sup>⁄<sub>12</sub> (<code><sup>5</sup>&frasl;<sub>12</sub></code>)<br>
|
<tr>
|
||||||
<strong>Caveat:</strong> Even with <code>fractions = false</code>,
|
<td class="purpose-description" colspan="3">
|
||||||
Blackfriday would still convert 1/2, 1/4 and 3/4 to ½ (<code>&frac12;</code>),
|
<span class="purpose-title">Purpose:</span>
|
||||||
¼ (<code>&frac14;</code>) and ¾ (<code>&frac34;</code>) respectively,
|
<code>true</code> enables smart, angled double quotes.<br>
|
||||||
but only these three.</small></td>
|
<small>
|
||||||
</tr>
|
<strong>Example:</strong>
|
||||||
|
<code>"Hugo"</code> renders to
|
||||||
<tr>
|
«Hugo» instead of “Hugo”.
|
||||||
<td><code><strong>smartDashes</strong></code></td>
|
</small>
|
||||||
<td><code>true</code></td>
|
</td>
|
||||||
<td><code>HTML_SMARTYPANTS_DASHES</code></td>
|
</tr>
|
||||||
</tr>
|
<tr>
|
||||||
<tr>
|
<td><code><strong>fractions</strong></code></td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<td><code>true</code></td>
|
||||||
<td class="purpose-description" colspan="2">Enable/Disable smart dashes, i.e. turning hyphens into en dash or em dash.<br>
|
<td><code>HTML_SMARTYPANTS_FRACTIONS</code></td>
|
||||||
Its behavior can be modified with the <code>latexDashes</code> flag listed below.</td>
|
</tr>
|
||||||
</tr>
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
<tr>
|
<span class="purpose-title">Purpose:</span>
|
||||||
<td><code><strong>latexDashes</strong></code></td>
|
<code>false</code> disables smart fractions.<br>
|
||||||
<td><code>true</code></td>
|
<small>
|
||||||
<td><code>HTML_SMARTYPANTS_LATEX_DASHES</code></td>
|
<strong>Example:</strong>
|
||||||
</tr>
|
<code>5/12</code> renders to
|
||||||
<tr>
|
<sup>5</sup>⁄<sub>12</sub>
|
||||||
<td class="purpose-title">Purpose:</td>
|
(<code><sup>5</sup>&frasl;<sub>12</sub></code>).<br>
|
||||||
<td class="purpose-description" colspan="2">Choose between LaTeX-style smart dashes and “conventional” smart dashes.<br>
|
<strong>Caveat:</strong>
|
||||||
<strong>If <code>true</code>,</strong> <code>--</code> is translated into “–” (<code>&ndash;</code>), and <code>---</code> is translated into “—” (<code>&mdash;</code>).<br>
|
Even with <code>fractions = false</code>,
|
||||||
<strong>If <code>false</code>,</strong> <code>--</code> is translated into “—” (<code>&mdash;</code>), whereas a <em>spaced</em> single hyphen between two words is turned into an en dash, e.g. <code>12 June - 3 July</code> becomes <code>12 June &ndash; 3 July</code>.</td>
|
Blackfriday still converts
|
||||||
</tr>
|
1/2, 1/4 and 3/4 respectively to
|
||||||
|
½ (<code>&frac12;</code>),
|
||||||
<tr style="height: 0.5em;"></tr>
|
¼ (<code>&frac14;</code>) and
|
||||||
|
¾ (<code>&frac34;</code>),
|
||||||
<tr>
|
but only these three.</small>
|
||||||
<td><code><strong>hrefTargetBlank</strong></code></td>
|
</td>
|
||||||
<td><code>false</code></td>
|
</tr>
|
||||||
<td><code>HTML_HREF_TARGET_BLANK</code></td>
|
<tr>
|
||||||
</tr>
|
<td><code><strong>smartDashes</strong></code></td>
|
||||||
<tr>
|
<td><code>true</code></td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<td><code>HTML_SMARTYPANTS_DASHES</code></td>
|
||||||
<td class="purpose-description" colspan="2">Open external links in a new window/tab.</td>
|
</tr>
|
||||||
</tr>
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
<tr>
|
<span class="purpose-title">Purpose:</span>
|
||||||
<td><code><strong>plainIDAnchors</strong></code></td>
|
<code>false</code> disables smart dashes; i.e., the conversion
|
||||||
<td><code>true</code></td>
|
of multiple hyphens into en dash or em dash.
|
||||||
<td><code>FootnoteAnchorPrefix</code> and <code>HeaderIDSuffix</code></td>
|
If <code>true</code>, its behavior can be modified with the
|
||||||
</tr>
|
<code>latexDashes</code> flag below.
|
||||||
<tr>
|
</td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
</tr>
|
||||||
<td class="purpose-description" colspan="2">If <code>true</code>, then header and footnote IDs are generated without the document ID.<br>
|
<tr>
|
||||||
<small><strong>Example:</strong> <code>#my-header</code> instead of <code>#my-header:bec3ed8ba720b9073ab75abcf3ba5d97</code>.</small></td>
|
<td><code><strong>latexDashes</strong></code></td>
|
||||||
</tr>
|
<td><code>true</code></td>
|
||||||
|
<td><code>HTML_SMARTYPANTS_LATEX_DASHES</code></td>
|
||||||
<tr style="height: 0.5em;"></tr>
|
</tr>
|
||||||
|
<tr>
|
||||||
<tr>
|
<td class="purpose-description" colspan="3">
|
||||||
<td><code><strong>extensions</strong></code></td>
|
<span class="purpose-title">Purpose:</span>
|
||||||
<td><code>[]</code></td>
|
<code>false</code> disables LaTeX-style smart dashes and
|
||||||
<td><code>EXTENSION_*</code></td>
|
selects conventional smart dashes. Assuming
|
||||||
</tr>
|
<code>smartDashes</code> (above), if this is:
|
||||||
<tr>
|
<ul>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<li>
|
||||||
<td class="purpose-description" colspan="2">Use non-default additional extensions.<br>
|
<strong><code>true</code>,</strong> then
|
||||||
<small><strong>Example:</strong> Add <code>"hardLineBreak"</code> to use <code>EXTENSION_HARD_LINE_BREAK</code>.</small></td>
|
<code>--</code> is translated into “–”
|
||||||
</tr>
|
(<code>&ndash;</code>), whereas
|
||||||
|
<code>---</code> is translated into “—”
|
||||||
<tr>
|
(<code>&mdash;</code>).
|
||||||
<td><code><strong>extensionsmask</strong></code></td>
|
</li>
|
||||||
<td><code>[]</code></td>
|
<li>
|
||||||
<td><code>EXTENSION_*</code></td>
|
<strong><code>false</code>,</strong> then
|
||||||
</tr>
|
<code>--</code> is translated into “—”
|
||||||
<tr>
|
(<code>&mdash;</code>), whereas a
|
||||||
<td class="purpose-title">Purpose:</td>
|
<em>spaced</em> single hyphen between two words
|
||||||
<td class="purpose-description" colspan="2">Extensions in this option won't be loaded.<br>
|
is translated into an en dash—e.g.,
|
||||||
<small><strong>Example:</strong> Add <code>"autoHeaderIds"</code> to disable <code>EXTENSION_AUTO_HEADER_IDS</code>.</small></td>
|
<code>12 June - 3 July</code> becomes
|
||||||
</tr>
|
<code>12 June &ndash; 3 July</code>.
|
||||||
|
</li>
|
||||||
<tr>
|
</ul>
|
||||||
<td><code><strong>sourceRelativeLinksEval</strong></code></td>
|
</td>
|
||||||
<td><code>false</code></td>
|
</tr>
|
||||||
<td><code>none</code></td>
|
<tr>
|
||||||
</tr>
|
<td><code><strong>hrefTargetBlank</strong></code></td>
|
||||||
<tr>
|
<td><code>false</code></td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
<td><code>HTML_HREF_TARGET_BLANK</code></td>
|
||||||
<td class="purpose-description" colspan="2">Source file based relative linking (a la Github).<br>
|
</tr>
|
||||||
Relative links to markdown and static files within a page will be evaluated relative to the
|
<tr>
|
||||||
location of that page, and then converted to html links during rendering. For example,
|
<td class="purpose-description" colspan="3">
|
||||||
`[example](../other/page.md)` in `content/total/overview.md` will be linked to
|
<span class="purpose-title">Purpose:</span>
|
||||||
`content/other/overview.md`, and then rendered to `/other/overview/` in the HTML output.
|
<code>true</code> opens external links in a new window or tab.
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
<tr>
|
||||||
<tr>
|
<td><code><strong>plainIDAnchors</strong></code></td>
|
||||||
<td><code><strong>sourceRelativeLinksProjectFolder</strong></code></td>
|
<td><code>true</code></td>
|
||||||
<td><code>"/docs/content"</code></td>
|
<td>
|
||||||
<td><code>none</code></td>
|
<code>FootnoteAnchorPrefix</code> and
|
||||||
</tr>
|
<code>HeaderIDSuffix</code>
|
||||||
<tr>
|
</td>
|
||||||
<td class="purpose-title">Purpose:</td>
|
</tr>
|
||||||
<td class="purpose-description" colspan="2">Source file based relative linking Hugo Project sub-folder.<br>
|
<tr>
|
||||||
When `sourceRelativeLinksEval` is enabled, source level paths may contain an absolute respository path to the
|
<td class="purpose-description" colspan="3">
|
||||||
markdown or static file which needs to be removed before trying to match it with the intended link.
|
<span class="purpose-title">Purpose:</span>
|
||||||
For example, if your documentation is in `/docs/content`, then
|
<code>true</code> renders any header and footnote IDs
|
||||||
`[example](/docs/content/other/page.md)` in `/docs/content/total/overview.md` will be linked to
|
without the document ID.<br>
|
||||||
`/docs/content/other/overview.md`, and then rendered to `/other/overview/` in the HTML output.
|
<small>
|
||||||
</td>
|
<strong>Example:</strong>
|
||||||
</tr>
|
renders <code>#my-header</code> instead of
|
||||||
|
<code>#my-header:bec3ed8ba720b9073ab75abcf3ba5d97</code>.
|
||||||
</tbody>
|
</small>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code><strong>extensions</strong></code></td>
|
||||||
|
<td><code>[]</code></td>
|
||||||
|
<td><code>EXTENSION_*</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
|
<span class="purpose-title">Purpose:</span>
|
||||||
|
Enable one or more of Blackfriday's Markdown extensions
|
||||||
|
(if they aren't Hugo defaults).<br>
|
||||||
|
<small>
|
||||||
|
<strong>Example:</strong>
|
||||||
|
Include <code>"hardLineBreak"</code>
|
||||||
|
in the list to enable Blackfriday's
|
||||||
|
<code>EXTENSION_HARD_LINE_BREAK</code>.
|
||||||
|
</small>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code><strong>extensionsmask</strong></code></td>
|
||||||
|
<td><code>[]</code></td>
|
||||||
|
<td><code>EXTENSION_*</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
|
<span class="purpose-title">Purpose:</span>
|
||||||
|
Disable one or more of Blackfriday's Markdown extensions
|
||||||
|
(if they are Hugo defaults).<br>
|
||||||
|
<small>
|
||||||
|
<strong>Example:</strong>
|
||||||
|
Include <code>"autoHeaderIds"</code>
|
||||||
|
in the list to disable Blackfriday's
|
||||||
|
<code>EXTENSION_AUTO_HEADER_IDS</code>.
|
||||||
|
</small>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code><strong>sourceRelativeLinksEval</strong></code></td>
|
||||||
|
<td><code>false</code></td>
|
||||||
|
<td><code>none</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
|
<span class="purpose-title">Purpose:</span>
|
||||||
|
<code>true</code> 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.<br>
|
||||||
|
<small>
|
||||||
|
<strong>Example:</strong>
|
||||||
|
<code>[some-reference-text](../other/page.md)</code> in
|
||||||
|
<code>./content/total/overview.md</code> will link to
|
||||||
|
<code>./content/other/overview.md</code> and render to
|
||||||
|
<code>/other/overview/</code> in the HTML output.
|
||||||
|
</small>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code><strong>sourceRelativeLinksProjectFolder</strong></code></td>
|
||||||
|
<td><code>/docs/content</code></td>
|
||||||
|
<td><code>none</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td class="purpose-description" colspan="3">
|
||||||
|
<span class="purpose-title">Purpose:</span>
|
||||||
|
Set a sub-folder for source file-based relative linking
|
||||||
|
on a Hugo Project (i.e., a web site). When
|
||||||
|
<code>sourceRelativeLinksEval</code> (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.<br />
|
||||||
|
<small>
|
||||||
|
<strong>Example:</strong>
|
||||||
|
Assuming your documentation resides in
|
||||||
|
<code>./docs/content</code>,
|
||||||
|
then a reference within
|
||||||
|
<code>./docs/content/total/overview.md</code> to
|
||||||
|
<code>[some-reference-text](/docs/content/other/page.md)</code>
|
||||||
|
will link to
|
||||||
|
<code>./docs/content/other/overview.md</code> and render to
|
||||||
|
<code>/other/overview/</code> in the HTML output.
|
||||||
|
</small>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
|
||||||
**Notes**
|
**Notes**
|
||||||
|
|
||||||
1. These flags are **very case-sensitive** (as of Hugo v0.15)!
|
* These flags are **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 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:
|
||||||
|
|
||||||
<table class="table">
|
<table class="table">
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
<th>TOML</th><th>YAML</th>
|
<th>TOML</th>
|
||||||
</tr>
|
<th>YAML</th>
|
||||||
</thead>
|
</tr>
|
||||||
<tbody>
|
</thead>
|
||||||
<tr style="vertical-align: top;">
|
<tbody>
|
||||||
<td style="width: 50%;"><pre><code>[blackfriday]
|
<tr style="vertical-align: top;">
|
||||||
|
<td style="width: 50%;">
|
||||||
|
<pre><code>[blackfriday]
|
||||||
angledQuotes = true
|
angledQuotes = true
|
||||||
fractions = false
|
fractions = false
|
||||||
plainIDAnchors = true
|
plainIDAnchors = true
|
||||||
extensions = ["hardLineBreak"]
|
extensions = ["hardLineBreak"]
|
||||||
</code></pre></td>
|
</code></pre>
|
||||||
<td><pre><code>blackfriday:
|
</td>
|
||||||
|
<td>
|
||||||
|
<pre><code>blackfriday:
|
||||||
angledQuotes: true
|
angledQuotes: true
|
||||||
fractions: false
|
fractions: false
|
||||||
plainIDAnchors: true
|
plainIDAnchors: true
|
||||||
extensions:
|
extensions:
|
||||||
- hardLineBreak
|
- hardLineBreak
|
||||||
</code></pre></td>
|
</code></pre>
|
||||||
</tr>
|
</td>
|
||||||
</tbody>
|
</tr>
|
||||||
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
|
||||||
|
|
@ -14,6 +14,7 @@
|
||||||
<link href="/assets/font-awesome/css/font-awesome.min.css" rel="stylesheet" />
|
<link href="/assets/font-awesome/css/font-awesome.min.css" rel="stylesheet" />
|
||||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css" />
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css" />
|
||||||
<link href="/css/style.css" rel="stylesheet">
|
<link href="/css/style.css" rel="stylesheet">
|
||||||
|
<link rel="stylesheet" type="text/css" href="/css/content-style.css" />
|
||||||
<link href="/css/style-responsive.css" rel="stylesheet" />
|
<link href="/css/style-responsive.css" rel="stylesheet" />
|
||||||
<link href="/css/monokai-sublime.css" rel="stylesheet" />
|
<link href="/css/monokai-sublime.css" rel="stylesheet" />
|
||||||
|
|
||||||
|
|
|
||||||
84
docs/static/css/content-style.css
vendored
Normal file
84
docs/static/css/content-style.css
vendored
Normal file
|
|
@ -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;
|
||||||
|
}
|
||||||
24
docs/static/css/style.css
vendored
24
docs/static/css/style.css
vendored
|
|
@ -498,30 +498,6 @@ kbd {
|
||||||
font-size: 0.85em;
|
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 */
|
/* For definitions of variables */
|
||||||
|
|
||||||
dl {
|
dl {
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue