From 5b19a26556cc7a533b0e2559e5f1740b892a2f53 Mon Sep 17 00:00:00 2001 From: Anthony Fok Date: Wed, 5 Aug 2015 16:24:03 -0600 Subject: [PATCH] docs: Extend documentation on Blackfriday options Especially to spell out how the `latexDashes` flag changes the behavior of smart dashes --- docs/content/overview/configuration.md | 34 ++++++++++++++++---------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md index a8100634d..afdcc4a37 100644 --- a/docs/content/overview/configuration.md +++ b/docs/content/overview/configuration.md @@ -32,7 +32,8 @@ The following is an example of a typical yaml config file: baseurl: "http://yoursite.example.com/" ... -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: +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: contentdir = "content" layoutdir = "layouts" @@ -49,7 +50,7 @@ The following is an example of a toml config file with some of the default value description = "Tesla's Awesome Hugo Site" 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: --- baseurl: "http://yoursite.example.com/" @@ -172,7 +173,8 @@ But Hugo does expose some options---as listed in the table below, matched with t Purpose: -Enable enable smart punctuation substitutions. +Enable/Disable smart punctuation substitutions such as smart quotes, smart dashes, etc. +May be fine-tuned with the angledQuotes, fractions and latexDashes flags below. @@ -182,7 +184,8 @@ But Hugo does expose some options---as listed in the table below, matched with t Purpose: -Enable smart angled double quotes (e.g. "Hugo" renders to «Hugo» instead of “Hugo”) +Enable/Disable smart angled double quotes.
+Example: "Hugo" renders to «Hugo» instead of “Hugo”. @@ -192,8 +195,8 @@ But Hugo does expose some options---as listed in the table below, matched with t Purpose: -Enable smart fractions -(e.g. 5/12 renders to 5⁄12 (<sup>5</sup>&frasl;<sub>12</sub>))
+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, @@ -207,10 +210,12 @@ but only these three. Purpose: -Disable LaTeX style dashes. +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. - + hrefTargetBlank @@ -219,7 +224,7 @@ but only these three. Purpose: -Open external links in a new window/tab. +Open external links in a new window/tab. @@ -229,10 +234,11 @@ but only these three. Purpose: -If true, then header and footnote IDs are generated without the document ID (e.g. #my-header instead of #my-header:bec3ed8ba720b9073ab75abcf3ba5d97) +If true, then header and footnote IDs are generated without the document ID.
+Example: #my-header instead of #my-header:bec3ed8ba720b9073ab75abcf3ba5d97. - + extensions @@ -241,7 +247,8 @@ but only these three. Purpose: -Use non-default additional extensions (e.g. Add "hardLineBreak" to use EXTENSION_HARD_LINE_BREAK) +Use non-default additional extensions.
+Example: Add "hardLineBreak" to use EXTENSION_HARD_LINE_BREAK. @@ -251,7 +258,8 @@ but only these three. Purpose: -Extensions in this option won't be loaded. (e.g. Add "autoHeaderIds" to disable EXTENSION_AUTO_HEADER_IDS) +Extensions in this option won't be loaded.
+Example: Add "autoHeaderIds" to disable EXTENSION_AUTO_HEADER_IDS.