TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-09 18:34:54 -04:00
Code Issues Packages Projects Releases Wiki Activity

Some more copy edits

Browse Source
This commit is contained in:
Bjørn Erik Pedersen 2017-07-15 10:05:48 +02:00
parent 2a657165f7
commit 29ba55bfe6
5 changed files with 29 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
content/content-management/cross-references.md
View File

@ -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
{{</* relref "my-birthday.md" */>}} => /events/my-birthday/ (maybe)
{{</* relref "my-birthday.md" */>}} => /posts/my-birthday/ (maybe)
{{</* relref "my-birthday.md" */>}} => /galleries/my-birthday/ (maybe)
{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
{{</* relref "galleries/my-birthday.md" */>}} => /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
{{</* relref "/events/my-birthday.md" */>}} => ""
@ -100,12 +98,12 @@ More information about document unique identifiers and headings can be found [be
### Examples
* `{{</* ref "blog/post.md" */>}} => http://yoursite.com/blog/post/`
* `{{</* ref "post.md#tldr" */>}} => http://yoursite.com/blog/post/#tldr:caffebad`
* `{{</* relref "post.md" */>}} => /blog/post/`
* `{{</* relref "blog/post.md#tldr" */>}} => /blog/post/#tldr:caffebad`
* `{{</* ref "#tldr" */>}} => #tldr:badcaffe`
* `{{</* relref "#tldr" */>}} => #tldr:badcaffe`
* `{{</* ref "blog/post.md" */>}}` => `http://yoursite.com/blog/post/`
* `{{</* ref "post.md#tldr" */>}}` => `http://yoursite.com/blog/post/#tldr:caffebad`
* `{{</* relref "post.md" */>}}` => `/blog/post/`
* `{{</* relref "blog/post.md#tldr" */>}}` => `/blog/post/#tldr:caffebad`
* `{{</* ref "#tldr" */>}}` => `#tldr:badcaffe`
* `{{</* relref "#tldr" */>}}` => `#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` &rarr; `heading`
* `# Heading 1` &rarr; `heading-1`
* `# Heading` &rarr; `heading-1-1`
* `# Heading` &rarr; `heading-1-2`
* `# Heading 1` &rarr; `heading-2`
This can even affect specified heading anchors that come after a generated heading anchor.
* `# My Heading` &rarr; `my-heading`
* `# My Heading {#my-heading}` &rarr; `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
<a href='{{</* relref "blog/post.md#example" */>}}'>Post Example</a>
<a href='/blog/post.md#81df004…'>Post Example</a>
```
```
[Post Two Example]({{</* relref "blog/post2.md#example" */>}})
<a href='/blog/post2.md#8cf1599…'>Post Two Example</a>
```
[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
[lists]: /templates/lists/

13
content/content-management/front-matter.md
View File

@ -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 [`<TAXONOMY>_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].

3
content/content-management/menus.md
View File

@ -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
---

18
content/content-management/multilingual.md
View File

@ -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.

1
layouts/shortcodes/todo.html Normal file
View File

@ -0,0 +1 @@
{{ if .Inner }}{{ end }}