hugo/content/en/readfiles/bfconfig.md

193 lines
8.3 KiB
Markdown
Raw Normal View History

## Blackfriday Options
`taskLists`
: default: **`true`**<br>
Blackfriday flag: <br>
Purpose: `false` turns off GitHub-style automatic task/TODO list generation.
`smartypants`
: default: **`true`** <br>
Blackfriday flag: **`HTML_USE_SMARTYPANTS`** <br>
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).
`smartypantsQuotesNBSP`
: default: **`false`** <br>
Blackfriday flag: **`HTML_SMARTYPANTS_QUOTES_NBSP`** <br>
Purpose: `true` enables French style Guillemets with non-breaking space inside the quotes.
`angledQuotes`
: default: **`false`**<br>
Blackfriday flag: **`HTML_SMARTYPANTS_ANGLED_QUOTES`**<br>
Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to «Hugo» instead of “Hugo”.
`fractions`
: default: **`true`**<br>
Blackfriday flag: **`HTML_SMARTYPANTS_FRACTIONS`** <br>
Purpose: <code>false</code> disables smart fractions.<br>
Example: `5/12` renders to <sup>5</sup>&frasl;<sub>12</sub>(<code>&lt;sup&gt;5&lt;/sup&gt;&amp;frasl;&lt;sub&gt;12&lt;/sub&gt;</code>).<br> <strong>Caveat:</strong> Even with <code>fractions = false</code>, Blackfriday still converts `1/2`, `1/4`, and `3/4` respectively to ½ (<code>&amp;frac12;</code>), ¼ (<code>&amp;frac14;</code>) and ¾ (<code>&amp;frac34;</code>), but only these three.</small>
`smartDashes`
: default: **`true`** <br>
Blackfriday flag: **`HTML_SMARTY_DASHES`** <br>
Purpose: `false` disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If `true`, its behavior can be modified with the `latexDashes` flag below.
`latexDashes`
: default: **`true`** <br>
Blackfriday flag: **`HTML_SMARTYPANTS_LATEX_DASHES`** <br>
Purpose: `false` disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming `smartDashes`: <br>
If `true`, `--` is translated into &ndash; (`&ndash;`), whereas `---` is translated into &mdash; (`&mdash;`). <br>
However, *spaced* single hyphen between two words is translated into an en&nbsp;dash&mdash; e.g., "`12 June - 3 July`" becomes `12 June &ndash; 3 July` upon rendering.
`hrefTargetBlank`
: default: **`false`** <br>
Blackfriday flag: **`HTML_HREF_TARGET_BLANK`** <br>
Purpose: `true` opens <s>external links</s> **absolute** links in a new window or tab. While the `target="_blank"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links ([ref](https://discourse.gohugo.io/t/internal-links-in-same-tab-external-links-in-new-tab/11048/8)). One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
Squashed 'docs/' changes from 501c6e233..f59b3ab06 f59b3ab06 Fix typo in template lookup order 1e5536d6c Mutlilingual: Document "content directory per language" system (#509) 849a86048 Update index.md 0c24d229b Polish Hugo Next a4c9b0ee2 Polish bbec2c76e Some more in birthday post fc9681e21 More on contributors 09fe3ea31 Some more on the birthday post 8da357240 Content and images for the 5th birthday blog post fb45bb8dc Add draft for anniversary blog post 4666d0a18 Release 0.42.2 9b74d286a Merge branch 'temp422' 354e7b66b releaser: Add release notes to /docs for release of 0.42.2 57a617f34 releaser: Bump versions for release of 0.42.2 ccc3ac1b8 Update errorf.md 35706c21a Update errorf.md 1c0f35fd1 Update errorf.md b6170774b Add syntax highlighting gallery links for Chroma f91d9da47 Update usage.md c9a8f0190 Improve theme components documentation 3c4e39ddd Release 0.42.1 b45eb453f Merge branch 'temp421' c74682a10 releaser: Prepare repository for 0.43-DEV 321e07fa5 releaser: Add release notes to /docs for release of 0.42.1 7154271e0 releaser: Bump versions for release of 0.42.1 360d8244f Add link to Privacy Config 1f2454247 Fix typo a8f5f994e Fix typo d9f3f078c Update simple variants documentation (#500) f5cfd44e0 Release 0.42 fe604b321 releaser: Prepare repository for 0.43-DEV c3e5b3ca0 releaser: Add release notes to /docs for release of 0.42 3174d1b37 releaser: Bump versions for release of 0.42 48cc2d51f docs: Update theme documentation 1922fb1a6 docs: Remove some files now moved d7e4c453a Merge commit 'b239595af5a9fc1fc9a1ccc666c3ab06ccc32f04' c40964c1b tplimpl: Remove speakerdeck shortcode 081f8a0f9 tpl/strings: strings.RuneCount 828ea5f15 tpl: Add strings.Repeat a6b9f654a Add a BlackFriday option for rel="noreferrer" on external links edb786516 Add a BlackFriday option for rel="nofollow" on external links e4374971f releaser: Prepare repository for 0.42-DEV git-subtree-dir: docs git-subtree-split: f59b3ab06f282c26bce07263c8be6672cf8f7969
2018-07-06 11:52:13 -04:00
`nofollowLinks`
: default: **`false`** <br>
Blackfriday flag: **`HTML_NOFOLLOW_LINKS`** <br>
Purpose: `true` creates <s>external links</s> **absolute** links with `nofollow` being added to their `rel` attribute. Thereby crawlers are advised to not follow the link. While the `rel="nofollow"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
`noreferrerLinks`
: default: **`false`** <br>
Blackfriday flag: **`HTML_NOREFERRER_LINKS`** <br>
Purpose: `true` creates <s>external links</s> **absolute** links with `noreferrer` being added to their `rel` attribute. Thus when following the link no referrer information will be leaked. While the `rel="noreferrer"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
`plainIDAnchors`
: default **`true`** <br>
Blackfriday flag: **`FootnoteAnchorPrefix` and `HeaderIDSuffix`** <br>
Purpose: `true` renders any heading and footnote IDs without the document ID. <br>
Example: renders `#my-heading` instead of `#my-heading:bec3ed8ba720b970`
`extensions`
: default: **`[]`** <br>
Squashed 'docs/' changes from e65df1059..a042b67b5 a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat e99dcb0b5 Document `:sections` placeholder for permalinks f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask) 5cab109c2 Add .Page.File documentation 62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation 60b4414de Add .Page.Dir documentation 22038d1a8 shortcode-templates.md: Update year example 850d5ca41 Add note about theme versions in hosting-on-netlify.md 0509b8055 Update permalink example URL c68d61d3a Mention the available 'width' argument in 'figure' shortcode ed83b483a Update Nanobox deployment tutorial a7422f35d shortcode-templates.md: Remove stray period af2905fe4 Fix order of releases in news section 19d3ea064 Bump to 0.30.2 bbfa10343 Merge branch 'next' 36ed7cbe4 releaser: Prepare repository for 0.31-DEV f689770f6 releaser: Add release notes to /docs for release of 0.30.2 0045e712a releaser: Bump versions for release of 0.30.2 a9efc3bbd Add slug to 0.30.1 relnotes 9cf47a4a1 Release 0.30.1 1fa0bb23d releaser: Prepare repository for 0.31-DEV 5582208b6 releaser: Add release notes to /docs for release of 0.30.1 09693d155 releaser: Bump versions for release of 0.30.1 58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' 4ef5dcb9b releaser: Prepare repository for 0.31-DEV 02938a788 releaser: Add release notes to /docs for release of 0.30.1 7cfd01fc6 releaser: Bump versions for release of 0.30.1 db3a68e24 Fix typo 95a5d8b46 Fix format of summaryLength in TOML example config 2ad649a92 Make terms in taxonomy examples more coherent 1fac1e662 Make a link specifically point to Pygments HTML Formatter docs 11ae6be03 Fix minor typos in v0.30 release notes git-subtree-dir: docs git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 07:46:40 -05:00
Purpose: Enable one or more Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
Squashed 'docs/' changes from 3e663efb2..fc61378a3 fc61378a3 Add Hugo 0.32 related docs 77edf7fd7 commands: Regenerate af9d25458 Fix Blackfriday's Markdown extension name 1223dd63a Remove roadmap b8bcb2fb8 Include note to allow hugo write permissions outside home dir 7dbccb936 Fix typo in roadmap 3a38da6f5 Fix spelling 94ebe50ff Merge branch 'master' of github.com:gohugoio/hugoDocs 89376e21d Clarify Hugo Roadmap 03d191fec Mention Reverse function in taxonomy tpl page. a4ea3402d Fix ref and relref function pages. b36632b31 Remove non-existing source variable a638160dc Update Content Organization to match the world 47eb431ca Correct one link in templates/output-formats.md 8bf933629 Spell fix ce2d48728 Add docs for .AllTranslations de94b4942 Move sponsor data to theme data 41fe75254 Merge commit 'f463ef99ed2862e4042557e28aece7ca858e1d0a' f463ef99e Squashed 'themes/gohugoioTheme/' changes from bc851da9..75da2f6b 532c65f2a Move sponsor logo to theme 899e2defe Add sponsor logos to home page and footer 3ca53db97 Release 0.31.1 bb9876ce2 Merge branch 'temp0311' c7c3ee7e5 releaser: Prepare repository for 0.32-DEV 4ac554792 releaser: Add release notes to /docs for release of 0.31.1 52bfb5c15 releaser: Bump versions for release of 0.31.1 cfdc2e4ea Fix output formats example 5746c10c2 More on output format de2ee0fe0 Improve suffix redefinition example c9997839e Update gitlab CI submodule management 82d74e306 Add Bootstrap styling to breadcrumb example c8c9601a8 Use the code shortcode for the breadcrumb example 16be43e7d Clean up formatting in variable definition lists 149c2c157 Add nested section docs 783c3d636 Sync theme 60a220bbd Squashed 'themes/gohugoioTheme/' changes from 6b632895..bc851da9 4b33a04d0 Fix typo 94cffc43c Fix little typo a5d4f762f Fix typo 36c5a0b43 Add a note about the 2 in staticDir2 087bd9a9f Add KeyCDN to menu 4ac8aae38 Hugo 0.31 Released 8fdd995e7 releaser: Prepare repository for 0.32-DEV eb0f38fbb releaser: Add release notes to /docs for release of 0.31 60efdfff7 releaser: Bump versions for release of 0.31 44dafb10b Merge commit '30c0d485eaff6d70df1be0353911ddca485d52bf' e6b847b95 Merge commit '05e42bc643f1840ed2ad9c2eff82a269d1381683' 15d86a525 Handle Taxonomy permalinks 5c3c18d7f Add support for height argument to figure shortcode git-subtree-dir: docs git-subtree-split: fc61378a3227c14883a2942d67c806014e7bb6cb
2017-12-30 03:15:31 -05:00
Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINE_BREAK`. <br>
Squashed 'docs/' changes from e65df1059..a042b67b5 a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat e99dcb0b5 Document `:sections` placeholder for permalinks f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask) 5cab109c2 Add .Page.File documentation 62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation 60b4414de Add .Page.Dir documentation 22038d1a8 shortcode-templates.md: Update year example 850d5ca41 Add note about theme versions in hosting-on-netlify.md 0509b8055 Update permalink example URL c68d61d3a Mention the available 'width' argument in 'figure' shortcode ed83b483a Update Nanobox deployment tutorial a7422f35d shortcode-templates.md: Remove stray period af2905fe4 Fix order of releases in news section 19d3ea064 Bump to 0.30.2 bbfa10343 Merge branch 'next' 36ed7cbe4 releaser: Prepare repository for 0.31-DEV f689770f6 releaser: Add release notes to /docs for release of 0.30.2 0045e712a releaser: Bump versions for release of 0.30.2 a9efc3bbd Add slug to 0.30.1 relnotes 9cf47a4a1 Release 0.30.1 1fa0bb23d releaser: Prepare repository for 0.31-DEV 5582208b6 releaser: Add release notes to /docs for release of 0.30.1 09693d155 releaser: Bump versions for release of 0.30.1 58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' 4ef5dcb9b releaser: Prepare repository for 0.31-DEV 02938a788 releaser: Add release notes to /docs for release of 0.30.1 7cfd01fc6 releaser: Bump versions for release of 0.30.1 db3a68e24 Fix typo 95a5d8b46 Fix format of summaryLength in TOML example config 2ad649a92 Make terms in taxonomy examples more coherent 1fac1e662 Make a link specifically point to Pygments HTML Formatter docs 11ae6be03 Fix minor typos in v0.30 release notes git-subtree-dir: docs git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 07:46:40 -05:00
*See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
`extensionsmask`
: default: **`[]`** <br>
Squashed 'docs/' changes from e65df1059..a042b67b5 a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat e99dcb0b5 Document `:sections` placeholder for permalinks f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask) 5cab109c2 Add .Page.File documentation 62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation 60b4414de Add .Page.Dir documentation 22038d1a8 shortcode-templates.md: Update year example 850d5ca41 Add note about theme versions in hosting-on-netlify.md 0509b8055 Update permalink example URL c68d61d3a Mention the available 'width' argument in 'figure' shortcode ed83b483a Update Nanobox deployment tutorial a7422f35d shortcode-templates.md: Remove stray period af2905fe4 Fix order of releases in news section 19d3ea064 Bump to 0.30.2 bbfa10343 Merge branch 'next' 36ed7cbe4 releaser: Prepare repository for 0.31-DEV f689770f6 releaser: Add release notes to /docs for release of 0.30.2 0045e712a releaser: Bump versions for release of 0.30.2 a9efc3bbd Add slug to 0.30.1 relnotes 9cf47a4a1 Release 0.30.1 1fa0bb23d releaser: Prepare repository for 0.31-DEV 5582208b6 releaser: Add release notes to /docs for release of 0.30.1 09693d155 releaser: Bump versions for release of 0.30.1 58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' 4ef5dcb9b releaser: Prepare repository for 0.31-DEV 02938a788 releaser: Add release notes to /docs for release of 0.30.1 7cfd01fc6 releaser: Bump versions for release of 0.30.1 db3a68e24 Fix typo 95a5d8b46 Fix format of summaryLength in TOML example config 2ad649a92 Make terms in taxonomy examples more coherent 1fac1e662 Make a link specifically point to Pygments HTML Formatter docs 11ae6be03 Fix minor typos in v0.30 release notes git-subtree-dir: docs git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 07:46:40 -05:00
Purpose: Disable one or more of Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`. <br>
Squashed 'docs/' changes from e65df1059..a042b67b5 a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat e99dcb0b5 Document `:sections` placeholder for permalinks f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask) 5cab109c2 Add .Page.File documentation 62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation 60b4414de Add .Page.Dir documentation 22038d1a8 shortcode-templates.md: Update year example 850d5ca41 Add note about theme versions in hosting-on-netlify.md 0509b8055 Update permalink example URL c68d61d3a Mention the available 'width' argument in 'figure' shortcode ed83b483a Update Nanobox deployment tutorial a7422f35d shortcode-templates.md: Remove stray period af2905fe4 Fix order of releases in news section 19d3ea064 Bump to 0.30.2 bbfa10343 Merge branch 'next' 36ed7cbe4 releaser: Prepare repository for 0.31-DEV f689770f6 releaser: Add release notes to /docs for release of 0.30.2 0045e712a releaser: Bump versions for release of 0.30.2 a9efc3bbd Add slug to 0.30.1 relnotes 9cf47a4a1 Release 0.30.1 1fa0bb23d releaser: Prepare repository for 0.31-DEV 5582208b6 releaser: Add release notes to /docs for release of 0.30.1 09693d155 releaser: Bump versions for release of 0.30.1 58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' 4ef5dcb9b releaser: Prepare repository for 0.31-DEV 02938a788 releaser: Add release notes to /docs for release of 0.30.1 7cfd01fc6 releaser: Bump versions for release of 0.30.1 db3a68e24 Fix typo 95a5d8b46 Fix format of summaryLength in TOML example config 2ad649a92 Make terms in taxonomy examples more coherent 1fac1e662 Make a link specifically point to Pygments HTML Formatter docs 11ae6be03 Fix minor typos in v0.30 release notes git-subtree-dir: docs git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 07:46:40 -05:00
*See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
## Blackfriday extensions
`noIntraEmphasis`
: default: *enabled* <br>
Purpose: The "\_" character is commonly used inside words when discussing
code, so having Markdown interpret it as an emphasis command is usually the
wrong thing. When enabled, Blackfriday lets you treat all emphasis markers
as normal characters when they occur inside a word.
`tables`
: default: *enabled* <br>
Purpose: When enabled, tables can be created by drawing them in the input
using the below syntax:
Example:
Name | Age
--------|------
Bob | 27
Alice | 23
`fencedCode`
: default: *enabled* <br>
Purpose: When enabled, in addition to the normal 4-space indentation to mark
code blocks, you can explicitly mark them and supply a language (to make
syntax highlighting simple).
You can use 3 or more backticks to mark the beginning of the block, and the
same number to mark the end of the block.
Example:
```md
# Heading Level 1
Some test
## Heading Level 2
Some more test
```
`autolink`
: default: *enabled* <br>
Purpose: When enabled, URLs that have not been explicitly marked as links
will be converted into links.
`strikethrough`
: default: *enabled* <br>
Purpose: When enabled, text wrapped with two tildes will be crossed out. <br>
Example: `~~crossed-out~~`
`laxHtmlBlocks`
: default: *disabled* <br>
Purpose: When enabled, loosen up HTML block parsing rules.
`spaceHeaders`
: default: *enabled* <br>
Purpose: When enabled, be strict about prefix header rules.
`hardLineBreak`
: default: *disabled* <br>
Purpose: When enabled, newlines in the input translate into line breaks in
the output.
`tabSizeEight`
: default: *disabled* <br>
Purpose: When enabled, expand tabs to eight spaces instead of four.
`footnotes`
: default: *enabled* <br>
Purpose: When enabled, Pandoc-style footnotes will be supported. The
footnote marker in the text that will become a superscript text; the
footnote definition will be placed in a list of footnotes at the end of the
document. <br>
Example:
This is a footnote.[^1]
[^1]: the footnote text.
`noEmptyLineBeforeBlock`
: default: *disabled* <br>
Purpose: When enabled, no need to insert an empty line to start a (code,
quote, ordered list, unordered list) block.
`headerIds`
: default: *enabled* <br>
Purpose: When enabled, allow specifying header IDs with `{#id}`.
`titleblock`
: default: *disabled* <br>
Purpose: When enabled, support [Pandoc-style title blocks][1].
`autoHeaderIds`
: default: *enabled* <br>
Purpose: When enabled, auto-create the header ID's from the headline text.
`backslashLineBreak`
: default: *enabled* <br>
Purpose: When enabled, translate trailing backslashes into line breaks.
`definitionLists`
: default: *enabled* <br>
Purpose: When enabled, a simple definition list is made of a single-line
term followed by a colon and the definition for that term. <br>
Example:
Cat
: Fluffy animal everyone likes
Internet
: Vector of transmission for pictures of cats
Terms must be separated from the previous definition by a blank line.
`joinLines`
: default: *enabled* <br>
Purpose: When enabled, delete newlines and join the lines.
[1]: http://pandoc.org/MANUAL.html#extension-pandoc_title_block