diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md index b6014f7d6..fc12ea094 100644 --- a/content/content-management/cross-references.md +++ b/content/content-management/cross-references.md @@ -16,7 +16,7 @@ toc: true --- - The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively. + The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively. ## Using `ref` and `relref` @@ -55,18 +55,16 @@ If you have the same filename used across multiple sections, you should only use └── my-birthday.md ``` -The potential for conflicting `documentname` is more likely in larger sites. Using the example of multiple `my-birthday.md` files, the following shows how these cross references may or may not render when called from within `content/meta/my-article.md`: +To be sure to get the correct reference in this case, use the full path: {{% code file="content/meta/my-article.md" copy="false" %}} ```md -{{}} => /events/my-birthday/ (maybe) -{{}} => /posts/my-birthday/ (maybe) -{{}} => /galleries/my-birthday/ (maybe) {{}} => /events/my-birthday/ -{{}} => /galleries/my-birthday/ ``` {{% /code %}} +{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}} + A relative document name must *not* begin with a slash (`/`). ```md {{}} => "" @@ -100,12 +98,12 @@ More information about document unique identifiers and headings can be found [be ### Examples -* `{{}} => http://yoursite.com/blog/post/` -* `{{}} => http://yoursite.com/blog/post/#tldr:caffebad` -* `{{}} => /blog/post/` -* `{{}} => /blog/post/#tldr:caffebad` -* `{{}} => #tldr:badcaffe` -* `{{}} => #tldr:badcaffe` +* `{{}}` => `http://yoursite.com/blog/post/` +* `{{}}` => `http://yoursite.com/blog/post/#tldr:caffebad` +* `{{}}` => `/blog/post/` +* `{{}}` => `/blog/post/#tldr:caffebad` +* `{{}}` => `#tldr:badcaffe` +* `{{}}` => `#tldr:badcaffe` ## Hugo Heading Anchors @@ -120,93 +118,6 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 ``` -What follows is a deeper discussion of *why* and *how* Hugo generates heading anchors. It is not necessary to know this to use `ref` and `relref`, but it may be useful in understanding how some anchors may not match your expectations. - -### How to Generate a Heading Anchor - -Convert the text of the heading to lowercase. - -``` -Hugo: A Fast & Modern Static Web Engine -=> hugo: a fast & modern static web engine -``` - -Replace anything that isn't an ASCII letter (`a-z`) or number (`0-9`) with a dash (`-`). - -``` -hugo: a fast & modern static web engine -=> hugo--a-fast---modern-static-web-engine -``` - -Get rid of extra dashes. - -``` -hugo--a-fast---modern-static-web-engine -=> hugo-a-fast-modern-static-web-engine -``` - -You have just converting the text of a heading to a suitable anchor. If your document has unique heading text, all of the anchors will be unique, too. - -#### Specifying Heading Anchors - -You can also tell Hugo to use a particular heading anchor. - -```md -# Hugo: A Fast & Modern Static Web Engine {#hugo-main} -``` - -Hugo will use `hugo-main` as the heading anchor. - -### What About Duplicate Heading Anchors? - -The technique outlined above works well enough, but some documents have headings with identical text, like the [shortcodes][] page—there are three headings with the text "Example". You can specify heading anchors manually: - -``` -### Example {#example-1} -### Example {#example-2} -### Example {#example-3} -``` - -It’s easy to forget to do that all the time, and Hugo is smart enough to do it for you. It just adds `-x` to the end of each heading it has already seen. - -* `### Example` => `example` -* `### Example` => `example-1` -* `### Example` => `example-2` - -Sometimes it's a little harder, but Hugo can recover from those, too, by adding more suffixes: - -* `# Heading` → `heading` -* `# Heading 1` → `heading-1` -* `# Heading` → `heading-1-1` -* `# Heading` → `heading-1-2` -* `# Heading 1` → `heading-2` - -This can even affect specified heading anchors that come after a generated heading anchor. - -* `# My Heading` → `my-heading` -* `# My Heading {#my-heading}` → `my-heading-1` - -{{% note %}} -This particular collision and override both unfortunate and unavoidable because Hugo processes each heading for collision detection as it sees it during conversion. -{{% /note %}} - -This technique works well for documents rendered on individual pages (e.g., blog posts), but what about [Hugo list pages][lists]? - -### Unique Heading Anchors in Lists - -Hugo converts each document from Markdown independently. It doesn’t know that `blog/post.md` has an "Example" heading that will collide with the "Example" heading in `blog/post2.md`. Even if it did know this, the addition of `blog/post3.md` should not cause the anchors for the headings in the other blog posts to change. - -Enter the document’s unique identifier. To prevent this sort of collision on list pages, Hugo always appends the document's to a generated heading anchor. So, the "Example" heading in `blog/post.md` actually turns into `#example:81df004…`, and the "Example" heading in `blog/post2.md` actually turns into `#example:8cf1599…`. All you have to know is the heading anchor that was generated, not the document identifier; `ref` and `relref` take care of the rest for you. - -```html -Post Example -Post Example -``` - -``` -[Post Two Example]({{}}) -Post Two Example -``` [built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes [lists]: /templates/lists/ diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md index 8c71ce780..058912ddb 100644 --- a/content/content-management/front-matter.md +++ b/content/content-management/front-matter.md @@ -27,7 +27,7 @@ TOML : identified by opening and closing `+++`. YAML -: identified by opening and closing `---` *or* opening `---` and closing `...` +: identified by opening and closing `---`. JSON : a single JSON object surrounded by '`{`' and '`}`', followed by a new line. @@ -98,7 +98,7 @@ There are a few predefined variables that Hugo is aware of. See [Page Variables] `draft` : if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. -`expirydate` +`expiryDate` : the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. `isCJKLanguage` @@ -113,7 +113,7 @@ There are a few predefined variables that Hugo is aware of. See [Page Variables] `lastmod` : the datetime at which the content was last modified. -`linktitle` +`linkTitle` : used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. `markup` @@ -122,7 +122,7 @@ There are a few predefined variables that Hugo is aware of. See [Page Variables] `outputs` : allows you to specify output formats specific to the content. See [output formats][outputs]. -`publishdate` +`publishDate` : if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. `slug` @@ -161,15 +161,12 @@ show_comments: false These two user-defined fields can then be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][variables] section provides more information on using Hugo's page- and site-level variables in your templates. -{{% note %}} -Field names are always normalized to lowercase; e.g., `camelCase: true` is available as `.Params.camelcase`. -{{% /note %}} ## Ordering Content Through Front Matter You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. -## Overriding Global Blackfriday Configuration +## Overriding Global Markdown Configuration It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config]. diff --git a/content/content-management/menus.md b/content/content-management/menus.md index d0e17811f..97663fe73 100644 --- a/content/content-management/menus.md +++ b/content/content-management/menus.md @@ -102,9 +102,8 @@ menu: ["main", "footer"] --- ``` -### Advanced +#### Advanced -Take the advanced approach if more control is required. All of the menu entry properties listed above are available. ```yaml --- diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md index 38013da27..86013a86a 100644 --- a/content/content-management/multilingual.md +++ b/content/content-management/multilingual.md @@ -1,7 +1,7 @@ --- title: Multilingual Mode linktitle: Multilingual and i18n -description: As of v0.17, Hugo supports the creation of websites with multiple languages side by side. +description: Hugo supports the creation of websites with multiple languages side by side. date: 2017-01-10 publishdate: 2017-01-10 lastmod: 2017-01-10 @@ -17,9 +17,9 @@ aliases: [/content/multilingual/,/content-management/multilingual/] toc: true --- -Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). You should Define the available languages in a `Languages` section in your site configuration. +You should define the available languages in a `Languages` section in your site configuration. -## Configuring Multilingual Mode +## Configure Languages The following is an example of a TOML site configuration for a multilingual Hugo project: @@ -99,12 +99,12 @@ Translated articles are identified by the name of the content file. 1. `/content/about.en.md` 2. `/content/about.fr.md` -You can also have the following, in which case the config variable `defaultContentLanguage` will be used to affect the default language `about.md`. This way, you can slowly start to translate your current content without having to rename everything: +In this eample, the `about.md` will be assigned the configured `defaultContentLanguage`. 1. `/content/about.md` 2. `/content/about.fr.md` -If left unspecified, the default value for `defaultContentLanguage` is `en`. +This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. By having the same *base filename*, the content pieces are linked together as translated pieces. @@ -117,6 +117,12 @@ slug: "a-propos" At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages. +{{%note %}} +Hugo currently uses the base filename as the translation key, which can be an issue with identical filenames in different sections. +We will fix this in https://github.com/gohugoio/hugo/issues/2699 +{{% /note %}} +{{< todo >}}Rewrite/remove the above one issue is fixed.{{< /todo >}} + ## Link to Translated Content To create a list of links to translated content, use a template similar to the following: @@ -264,7 +270,7 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. -While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`EnableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. {{% note %}} Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. diff --git a/layouts/shortcodes/todo.html b/layouts/shortcodes/todo.html new file mode 100644 index 000000000..50a099267 --- /dev/null +++ b/layouts/shortcodes/todo.html @@ -0,0 +1 @@ +{{ if .Inner }}{{ end }} \ No newline at end of file