diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md
index 21a73b861..9570a8fa4 100644
--- a/content/en/content-management/cross-references.md
+++ b/content/en/content-management/cross-references.md
@@ -15,31 +15,39 @@ aliases: [/extras/crossreferences/]
 toc: true
 ---
 
-
-The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
+The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
 
 ## Use `ref` and `relref`
 
 ```go-html-template
+{{</* ref "document" */>}}
+{{</* ref "document#anchor" */>}}
 {{</* ref "document.md" */>}}
-{{</* ref "#anchor" */>}}
 {{</* ref "document.md#anchor" */>}}
+{{</* ref "#anchor" */>}}
 {{</* ref "/blog/my-post" */>}}
 {{</* ref "/blog/my-post.md" */>}}
+{{</* relref "document" */>}}
 {{</* relref "document.md" */>}}
 {{</* relref "#anchor" */>}}
-{{</* relref "document.md#anchor" */>}}
+{{</* relref "/blog/my-post.md" */>}}
 ```
 
-The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
+To generate a hyperlink using `ref` or `relref` in markdown:
 
-**Paths without a leading `/` will first  be tried resolved relative to the current page.**
+```md
+[About]({{</* ref "/page/about" */>}} "About Us")
+```
 
-You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.
+The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
+
+**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
+
+Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
 
 ### Link to another language version
 
-Link to another language version of a document, you need to use this syntax:
+To link to another language version of a document, use this syntax:
 
 ```go-html-template
 {{</* relref path="document.md" lang="ja" */>}}
@@ -47,45 +55,66 @@ Link to another language version of a document, you need to use this syntax:
 
 ### Get another Output Format
 
-To link to a given Output Format of a document, you can use this syntax:
+To link to another Output Format of a document, use this syntax:
 
 ```go-html-template
 {{</* relref path="document.md" outputFormat="rss" */>}}
 ```
 
-### Anchors
+### Heading IDs
 
-When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
+When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
 
-```go-html-template
-{{</* relref "#anchors" */>}} => #anchors:9decaf7
+```md
+## Reference
 ```
 
-The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
+produces this HTML:
 
-```go-html-template
-{{</* relref "#who" */>}} => #who:9decaf7
-{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
+```html
+<h2 id="reference">Reference</h2>
 ```
 
-More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
-
-## Hugo Heading Anchors
-
-When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
-
-Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`.
-
-`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
+Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
 
+```md
+{{</* ref "document.md#reference */>}}
+{{</* relref "document.md#reference */>}}
 ```
-{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
-/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
+
+Generate a custom heading ID by including an attribute. For example:
+
+```md
+## Reference A {#foo}
+## Reference B {id="bar"}
+```
+
+produces this HTML:
+
+```html
+<h2 id="foo">Reference A</h2>
+<h2 id="bar">Reference B</h2>
+```
+
+Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
+
+```md
+## Reference
+## Reference
+## Reference
+```
+
+produces this HTML:
+
+```html
+<h2 id="reference">Reference</h2>
+<h2 id="reference-1">Reference</h2>
+<h2 id="reference-2">Reference</h2>
 ```
 
 ## Ref and RelRef Configuration
 
-The behaviour can, since Hugo 0.45, be configured in `config.toml`:
+The behavior can, since Hugo 0.45, be configured in `config.toml`:
 
 refLinksErrorLevel ("ERROR") 
 : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).