From 8ae3aadd73df296fba2a3d3f3e7b8f415423455b Mon Sep 17 00:00:00 2001 From: Regis Philibert Date: Fri, 6 Apr 2018 15:41:50 -0400 Subject: [PATCH] =?UTF-8?q?use=20code-toggle=20shortcode=20when=20relevant?= =?UTF-8?q?=20Content=20Management=20=E2=9C=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/content-management/comments.md | 10 +-- content/content-management/front-matter.md | 38 +--------- content/content-management/menus.md | 22 +----- content/content-management/multilingual.md | 14 ++-- content/content-management/page-resources.md | 44 ++--------- content/content-management/static-files.md | 6 +- content/content-management/taxonomies.md | 78 +++----------------- content/content-management/urls.md | 13 +--- content/getting-started/configuration.md | 63 ++-------------- 9 files changed, 43 insertions(+), 245 deletions(-) diff --git a/content/content-management/comments.md b/content/content-management/comments.md index 355bf0042..20932a825 100644 --- a/content/content-management/comments.md +++ b/content/content-management/comments.md @@ -27,15 +27,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before ### Configure Disqus -Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively: +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: -``` +{{< code-toggle copy="false" >}} disqusShortname = "yourdiscussshortname" -``` - -``` -disqusShortname: "yourdiscussshortname" -``` +{{}} For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md index a6a3f2403..2fc18ee31 100644 --- a/content/content-management/front-matter.md +++ b/content/content-management/front-matter.md @@ -34,9 +34,9 @@ YAML JSON : a single JSON object surrounded by '`{`' and '`}`', followed by a new line. -### TOML Example +### Example -``` +{{< code-toggle >}} +++ title = "spf13-vim 3.0 release and new website" description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." @@ -48,39 +48,7 @@ categories = [ ] slug = "spf13-vim-3-0-release-and-new-website" +++ -``` - -### YAML Example - -``` ---- -title: "spf13-vim 3.0 release and new website" -description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." -tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] -lastmod: 2015-12-23 -date: "2012-04-06" -categories: - - "Development" - - "VIM" -slug: "spf13-vim-3-0-release-and-new-website" ---- -``` - -### JSON Example - -``` -{ - "title": "spf13-vim 3.0 release and new website", - "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", - "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], - "date": "2012-04-06", - "categories": [ - "Development", - "VIM" - ], - "slug": "spf13-vim-3-0-release-and-new-website" -} -``` +{{}} ## Front Matter Variables diff --git a/content/content-management/menus.md b/content/content-management/menus.md index 1353ce0e2..c2eadf50f 100644 --- a/content/content-management/menus.md +++ b/content/content-management/menus.md @@ -118,9 +118,9 @@ menu: You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. -Here’s an example snippet pulled from a `config.toml`: +Here’s an example snippet pulled from a configuration file: -{{< code file="config.toml" >}} +{{< code-toggle file="config.toml" >}} [[menu.main]] name = "about hugo" pre = "" @@ -132,23 +132,7 @@ Here’s an example snippet pulled from a `config.toml`: pre = "" weight = -100 url = "/getting-started/" -{{< /code >}} - -Here's the equivalent snippet in a `config.yaml`: - -{{< code file="config.yml" >}} -menu: - main: - - name: "about hugo" - pre: "" - weight: -110 - identifier: "about" - url: "/about/" - - name: "getting started" - pre: "" - weight: -100 - url: "/getting-started/" -{{< /code >}} +{{< /code-toggle >}} {{% note %}} The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md index d27195a9a..28a6e4fec 100644 --- a/content/content-management/multilingual.md +++ b/content/content-management/multilingual.md @@ -21,9 +21,9 @@ You should define the available languages in a `languages` section in your site ## Configure Languages -The following is an example of a TOML site configuration for a multilingual Hugo project: +The following is an example of a site configuration for a multilingual Hugo project: -{{< code file="config.toml" download="config.toml" >}} +{{< code-toggle file="config" >}} DefaultContentLanguage = "en" copyright = "Everything is mine" @@ -45,7 +45,7 @@ weight = 2 linkedin = "lien-francais" [languages.fr.params.navigation] help = "Aide" -{{< /code >}} +{{< /code-toggle >}} Anything not defined in a `[languages]` block will fall back to the global value for that key (e.g., `copyright` for the English [`en`] language). @@ -92,7 +92,7 @@ This means that you can now configure a `baseURL` per `language`: Example: -```bash +{{< code-toggle file="config" >}} [languages] [languages.no] baseURL = "https://example.no" @@ -105,7 +105,7 @@ baseURL = "https://example.com" languageName = "English" weight = 2 title = "In English" -``` +{{}} With the above, the two sites will be generated into `public` with their own root: @@ -132,7 +132,7 @@ Live reload and `--navigateToChanged` between the servers work as expected. Taxonomies and [Blackfriday configuration][config] can also be set per language: -{{< code file="bf-config.toml" >}} +{{< code-toggle file="config" >}} [Taxonomies] tag = "tags" @@ -152,7 +152,7 @@ weight = 2 title = "Français" [languages.fr.Taxonomies] plaque = "plaques" -{{< /code >}} +{{}} ## Translate Your Content diff --git a/content/content-management/page-resources.md b/content/content-management/page-resources.md index f3b12d8c4..cefb1cd47 100644 --- a/content/content-management/page-resources.md +++ b/content/content-management/page-resources.md @@ -83,9 +83,9 @@ params : A map of custom key/values. -### Resources metadata: YAML Example +### Resources metadata example -~~~yaml +{{< code-toggle copy="false">}} title: Application date : 2018-01-25 resources : @@ -108,41 +108,7 @@ resources : - src : "**.docx" params : icon : "word" -~~~ - -### Resources metadata: TOML Example - -~~~toml -title = Application -date : 2018-01-25 -[[resources]] - src = "images/sunset.jpg" - name = "header" -[[resources]] - src = "documents/photo_specs.pdf" - title = "Photo Specifications" - [resources.params] - icon = "photo" -[[resources]] - src = "documents/guide.pdf" - title = "Instruction Guide" -[[resources]] - src = "documents/checklist.pdf" - title = "Document Checklist" -[[resources]] - src = "documents/payment.docx" - title = "Proof of Payment" -[[resources]] - src = "**.pdf" - name = "pdf-file-:counter" - [resources.params] - icon = "pdf" -[[resources]] - src = "**.docx" - [resources.params] - icon = "word" -~~~ - +{{}} From the example above: @@ -165,14 +131,14 @@ The counter starts at 1 the first time they are used in either `name` or `title` For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: -~~~toml +{{< code-toggle copy="false">}} [[resources]] src = "*specs.pdf" title = "Specification #:counter" [[resources]] src = "**.pdf" name = "pdf-file-:counter" -~~~ +{{}} the `Name` and `Title` will be assigned to the resource files as follows: diff --git a/content/content-management/static-files.md b/content/content-management/static-files.md index 12d27ccf2..fe5ea77e0 100644 --- a/content/content-management/static-files.md +++ b/content/content-management/static-files.md @@ -15,11 +15,11 @@ toc: true The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc. -You can set the name of the static folder to use in your configuration file, for example `config.toml`. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem. +You can set the name of the static folder to use in your configuration file. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem. Example: -```toml +{{< code-toggle copy="false" file="config" >}} staticDir = ["static1", "static2"] [languages] [languages.no] @@ -35,7 +35,7 @@ baseURL = "https://example.com" languageName = "English" weight = 2 title = "In English" -``` +{{}} In the above, with no theme used: diff --git a/content/content-management/taxonomies.md b/content/content-management/taxonomies.md index 1a59ebe3e..287c6f899 100644 --- a/content/content-management/taxonomies.md +++ b/content/content-management/taxonomies.md @@ -103,23 +103,14 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. -### Example: TOML Taxonomy Configuration +### Example: Taxonomy Configuration -``` +{{< code-toggle copy="false" >}} [taxonomies] tag = "tags" category = "categories" series = "series" -``` - -### Example: YAML Taxonomy Configuration - -``` -taxonomies: - tag: "tags" - category: "categories" - series: "series" -``` +{{}} ### Preserve Taxonomy Values @@ -145,53 +136,16 @@ Assigning content to a taxonomy is done in the [front matter][]. Simply create a If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/). {{% /note %}} -### Example: TOML Front Matter with Taxonomies +### Example: Front Matter with Taxonomies -``` -+++ +{{< code-toggle copy="false">}} title = "Hugo: A fast and flexible static site generator" tags = [ "Development", "Go", "fast", "Blogging" ] categories = [ "Development" ] series = [ "Go Web Dev" ] slug = "hugo" project_url = "https://github.com/gohugoio/hugo" -+++ -``` - -### Example: YAML Front Matter with Taxonomies - -``` ---- -title: "Hugo: A fast and flexible static site generator" -tags: ["Development", "Go", "fast", "Blogging"] -categories: ["Development"] -series: ["Go Web Dev"] -slug: "hugo" -project_url: "https://github.com/gohugoio/hugo" ---- -``` - -### Example: JSON Front Matter with Taxonomies - -``` -{ - "title": "Hugo: A fast and flexible static site generator", - "tags": [ - "Development", - "Go", - "fast", - "Blogging" - ], - "categories" : [ - "Development" - ], - "series" : [ - "Go Web Dev" - ], - "slug": "hugo", - "project_url": "https://github.com/gohugoio/hugo" -} -``` +{{}} ## Order Taxonomies @@ -199,29 +153,15 @@ A content file can assign weight for each of its associate taxonomies. Taxonomic The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page. -### Example: TOML Taxonomic `weight` +### Example: Taxonomic `weight` -``` -+++ +{{< code-toggle copy="false" >}} title = "foo" tags = [ "a", "b", "c" ] tags_weight = 22 categories = ["d"] categories_weight = 44 -+++ -``` - -### Example: YAML Taxonomic `weight` - -``` ---- -title: foo -tags: [ "a", "b", "c" ] -tags_weight: 22 -categories: ["d"] -categories_weight: 44 ---- -``` +{{}} By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies. diff --git a/content/content-management/urls.md b/content/content-management/urls.md index dd91fbced..d33725b72 100644 --- a/content/content-management/urls.md +++ b/content/content-management/urls.md @@ -29,19 +29,12 @@ These examples use the default values for `publishDir` and `contentDir`; i.e., ` For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. -### YAML Permalinks Configuration Example +### Permalinks Configuration Example -{{< code file="config.yml" copy="false" >}} +{{< code-toggle file="config" copy="false" >}} permalinks: post: /:year/:month/:title/ -{{< /code >}} - -### TOML Permalinks Configuration Example - -{{< code file="config.toml" copy="false" >}} -[permalinks] - post = "/:year/:month/:title/" -{{< /code >}} +{{< /code-toggle >}} Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. diff --git a/content/getting-started/configuration.md b/content/getting-started/configuration.md index ba2c87e82..8da25fd58 100644 --- a/content/getting-started/configuration.md +++ b/content/getting-started/configuration.md @@ -250,9 +250,11 @@ Similar to the template [lookup order][], Hugo has a default set of rules for se In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. -## YAML Configuration +## Example Configuration -{{< code file="config.yml">}} +The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: + +{{< code-toggle file="config">}} baseURL: "https://yoursite.example.com/" title: "My Hugo Site" footnoteReturnLinkContents: "↩" @@ -266,49 +268,7 @@ params: - "foo1" - "foo2" SidebarRecentLimit: 5 -{{< /code >}} - -The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: - -{{< code file="config.yml">}} -baseURL: "https://yoursite.example.com/" -title: "My Hugo Site" -footnoteReturnLinkContents: "↩" -permalinks: - post: /:year/:month/:title/ -params: - Subtitle: "Hugo is Absurdly Fast!" - AuthorName: "Jon Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 -{{< /code >}} - -## TOML Configuration - -The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]: - -{{< code file="config.toml">}} -contentDir = "content" -layoutDir = "layouts" -publishDir = "public" -buildDrafts = false -baseURL = "https://yoursite.example.com/" -canonifyURLs = true -title = "My Hugo Site" - -[taxonomies] - category = "categories" - tag = "tags" - -[params] - subtitle = "Hugo is Absurdly Fast!" - author = "John Doe" -{{< /code >}} - - +{{< /code-toggle >}} ## Configure with Environment Variables @@ -416,22 +376,13 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some 2. Blackfriday 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 its respective site setting. {{% /note %}} -{{< code file="bf-config.toml" >}} +{{< code-toggle file="config" >}} [blackfriday] angledQuotes = true fractions = false plainIDAnchors = true extensions = ["hardLineBreak"] -{{< /code >}} - -{{< code file="bf-config.yml" >}} -blackfriday: - angledQuotes: true - fractions: false - plainIDAnchors: true - extensions: - - hardLineBreak -{{< /code >}} +{{< /code-toggle >}} ## Configure Additional Output Formats