Squashed 'docs/' changes from 54f0e8776..bd0e15bb6

bd0e15bb6 Optimised images with calibre/image-actions 59830ea44 Remove comments from quickstart code samples 348821b5d Remove image-actions 1cbbd26a9 Update index.md bcf3de764 Update index.md fcf17e6ef Release 0.62.1 0956bde21 Merge branch 'temp621' 28d604756 releaser: Add release notes to /docs for release of 0.62.1 c895f12e7 Fix statement about version installed with apt-get (#854) e96928e38 Updated quickstart to split theme download and theme config add into separate blocks (#967) e099c1ad6 changed ".Title" to ".URL" (#972) bea71280d Fix small typing error (#1001) 9c28c422e Correct hyperlink for 'markdownify' function cf3844a06 Corrected small conjugation mistake (#996) 8b9c1d4f2 Added remarks about additional parameters in ref/relref (#995) ca06c9a56 Fix illegal character in render-link.html example 7a85c789b Update RenderString.md 69df3b17e Update configuration-markup.md 43e9222a2 Revert "Add shortcodes to note comparing with `markdownify`" 2bd5bc2d7 Add shortcodes to note comparing with `markdownify` ddfee60b7 Update configuration-markup.md f87c35fe2 docs: Remove extra double quotation 5ca5cc15f Update index.md 6e457f5ec Update configuration-markup.md 12df3c0fc Update configuration-markup.md 91977fd96 Update configuration-markup.md 377b8954a Update configuration-markup.md 99d691b5e Update hosting-on-render.md ccf855b22 Update index.md a945acc42 Update index.md 7d4f308d6 Fix Netlify config f4caa07f5 Release 0.62.0 79d18276f releaser: Add release notes to /docs for release of 0.62.0 9db1a08d1 Merge commit '8a4005cf2b0ef34265ff8051a6b76226685fc226' 79e556223 docs: More on hooks 5088c54df tpl: Do not return any value in errorf 98c8c8638 tpl: Add a warnf template func 4a9d76cea docs: Regen docshelper 626e53b55 Fix incorrect MIME type from image/jpg to image/jpeg f92f77c5d Preserve HTML Text for link render hooks 6db9c52b1 docs: Footnote 16801db3b Add render template hooks for links and images 0facb823c Merge commit '2e711a28c71e8667258e5ab824f9b9a71c261b0a' 79bf8ed4c markup/tableofcontents: Add config option for ordered list git-subtree-dir: docs git-subtree-split: bd0e15bb6063f7ad4f0c47eb33c8c0c23c962d13
gohugoio · Jan 5, 2020 · 26f1458 · 26f1458
1 parent 8a4005c
commit 26f1458
Show file tree

Hide file tree

Showing 65 changed files with 286 additions and 94 deletions.
diff --git a/.github/calibre/image-actions.yml b/.github/calibre/image-actions.yml
diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md
@@ -16,7 +16,7 @@ menu:
 
 ## The Image Page Resource
 
-The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder.
+The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below do not work on images inside your `/static` folder.
 
 To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}):
 
@@ -88,7 +88,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it:
 
 Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image.
 
-Note that this is only suported for JPG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.:
+Note that this is only suported for JPEG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.:
 
 ```go-html-template
 {{ with $img.Exif }}

diff --git a/content/en/content-management/image-processing/sunset.jpg b/content/en/content-management/image-processing/sunset.jpg
diff --git a/content/en/content-management/organization/1-featured-content-bundles.png b/content/en/content-management/organization/1-featured-content-bundles.png
diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md
@@ -17,7 +17,7 @@ menu:
 ## Properties
 
 ResourceType
-: The main type of the resource. For example, a file of MIME type `image/jpg` has the ResourceType `image`.
+: The main type of the resource. For example, a file of MIME type `image/jpeg` has the ResourceType `image`.
 
 Name
 : Default value is the filename (relative to the owning page). Can be set in front matter.
@@ -35,7 +35,7 @@ Content
 : The content of the resource itself. For most resources, this returns a string with the contents of the file. This can be used to inline some resources, such as `<script>{{ (.Resources.GetMatch "myscript.js").Content | safeJS }}</script>` or `<img src="{{ (.Resources.GetMatch "mylogo.png").Content | base64Encode }}">`.
 
 MediaType
-: The MIME type of the resource, such as `image/jpg`.
+: The MIME type of the resource, such as `image/jpeg`.
 
 MediaType.MainType
 : The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`.

diff --git a/content/en/functions/RenderString.md b/content/en/functions/RenderString.md
@@ -0,0 +1,39 @@
+---
+title: .RenderString
+description: "Renders markup to HTML."
+godocref:
+date: 2019-12-18
+categories: [functions]
+menu:
+  docs:
+    parent: "functions"
+keywords: [markdown,goldmark,render]
+signature: [".RenderString MARKUP"]
+---
+
+{{< new-in "0.62.0" >}} 
+
+`.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options).
+
+*Note* that this method does not parse and render shortcodes.
+
+The method takes an optional map argument with these options:
+
+display ("inline")
+: `inline` or `block`. If `inline` (default), surrounding ´<p></p>` on short snippets will be trimmed.
+
+markup (defaults to the Page's markup)
+: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats).
+
+Some examples:
+
+```go-html-template
+{{ $optBlock := dict "display" "block" }}
+{{ $optOrg := dict "markup" "org" }}
+{{ "**Bold Markdown**" | $p.RenderString }}
+{{  "**Bold Block Markdown**" | $p.RenderString  $optBlock }}
+{{  "/italic org mode/" | $p.RenderString  $optOrg }}:REND
+```
+
+
+**Note** that this method is more powerful than the similar [markdownify](/functions/markdownify/) function as it also supports [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks) and it has options to render other markup formats.
diff --git a/content/en/functions/errorf.md b/content/en/functions/errorf.md
@@ -1,7 +1,6 @@
 ---
-title: errorf
-linktitle: errorf
-description: Log ERROR and fail the build from the templates.
+title: errorf and warnf
+description: Log ERROR or WARNING from the templates.
 date: 2017-09-30
 publishdate: 2017-09-30
 lastmod: 2017-09-30
@@ -15,15 +14,21 @@ workson: []
 hugoversion:
 relatedfuncs: [printf]
 deprecated: false
-aliases: []
+aliases: [/functions/errorf]
 ---
 
-`errorf` will evaluate a format string, then output the result to the ERROR log (and only once per error message to avoid flooding the log).
+`errorf` or `warnf` will evaluate a format string, then output the result to the ERROR or WARNING log (and only once per error message to avoid flooding the log).
 
-This will also cause the build to fail (the `hugo` command will `exit -1`).
+Any ERROR will also cause the build to fail (the `hugo` command will `exit -1`).
+
+Both functions return an empty string, so the messages are only printed to the console.
 
 ```
 {{ errorf "Failed to handle page %q" .Path }}
 ```
 
-Note that `errorf` supports all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package.
+```
+{{ warnf "You should update the shortcodes in %q" .Path }}
+```
+
+Note that `errorf` and `warnf` support all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package.
diff --git a/content/en/functions/ref.md b/content/en/functions/ref.md
@@ -5,7 +5,7 @@ description: Looks up a content page by logical name.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
+lastmod: 2019-12-28
 categories: [functions]
 menu:
   docs:
@@ -29,6 +29,12 @@ aliases: []
 `ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
 {{% /note %}}
 
+It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path.
+
+``` 
+{{ ref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} 
+```
+
 These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
 
 For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
diff --git a/content/en/functions/relref.md b/content/en/functions/relref.md
@@ -5,7 +5,7 @@ description: Looks up a content page by relative path.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
+lastmod: 2019-12-28
 categories: [functions]
 menu:
   docs:
@@ -29,6 +29,12 @@ aliases: []
 `relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
 {{% /note %}}
 
+It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. 
+
+``` 
+{{ relref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }}
+```
+
 These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
 
 For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
diff --git a/content/en/functions/safeURL.md b/content/en/functions/safeURL.md
@@ -50,7 +50,7 @@ This partial would produce the following HTML output:
 </ul>
 {{< /output >}}
 
-The odd output can be remedied by adding ` | safeURL` to our `.Title` page variable:
+The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
 
 {{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}}
 <!-- This unordered list may be part of a sidebar menu -->

diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md
@@ -70,4 +70,69 @@ startLevel
 : The heading level, values starting at 1 (`h1`), to start render the table of contents.
 
 endLevel
-: The heading level, inclusive, to stop render the table of contents.
+: The heading level, inclusive, to stop render the table of contents.
+
+ordered
+: Whether or not to generate an ordered list instead of an unordered list.
+
+
+## Markdown Render Hooks
+
+{{< new-in "0.62.0" >}}
+
+Note that this is only supported with the [Goldmark](#goldmark) renderer.
+
+These Render Hooks allow custom templates to render links and images from markdown.
+
+You can do this by creating templates with base names `render-link` and/or `render-image` inside `layouts/_default/_markup`.
+
+You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed.[^hooktemplate] Your `layouts` folder may look like this:
+
+```bash
+layouts
+└── _default
+    └── _markup
+        ├── render-image.html
+        ├── render-image.rss.xml
+        └── render-link.html
+```
+
+Some use cases for the above:
+
+* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
+* Add `target=_blank` to external links.
+* Resolve and [process](/content-management/image-processing/) images.
+
+### Render Hook Templates
+
+Both `render-link` and `render-image` templates will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Destination
+: The URL.
+
+Title
+: The title attribute.
+
+Text
+: The rendered (HTML) link text.
+
+PlainText
+: The plain variant of the above.
+
+A Markdown example for an inline-style link with title:
+
+```md
+[Text](https://www.gohugo.io "Title")
+```
+
+A very simple template example given the above:
+
+{{< code file="layouts/_default/_markup/render-link.html" >}}
+<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank"{{ end }}>{{ .Text }}</a>
+{{< /code >}}
+
+[^hooktemplate]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version.
+
diff --git a/content/en/getting-started/external-learning-resources/hia.jpg b/content/en/getting-started/external-learning-resources/hia.jpg
diff --git a/content/en/getting-started/installing.md b/content/en/getting-started/installing.md
@@ -461,7 +461,7 @@ Hugo installed via Snap can write only inside the user’s `$HOME` directory---a
 
     sudo apt-get install hugo
 
-This installs the "extended" Sass/SCSS version.
+What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support.
 
 This option is not recommended because the Hugo in Linux package managers for Debian and Ubuntu is usually a few versions behind as described [here](https://github.com/gcushen/hugo-academic/issues/703)
 

diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md
@@ -26,8 +26,6 @@ It is recommended to have [Git installed](https://git-scm.com/downloads) to run
 For other approaches learning Hugo like book or a video tutorial refer to the [external learning resources](/getting-started/external-learning-resources/) page.
 {{% /note %}}
 
-
-
 ## Step 1: Install Hugo
 
 {{% note %}}
@@ -44,10 +42,8 @@ To verify your new install:
 hugo version
 ```
 
-
 {{< asciicast ItACREbFgvJ0HjnSNeTknxWy9 >}}
 
-
 ## Step 2: Create a New Site
 
 ```bash
@@ -58,33 +54,32 @@ The above will create a new Hugo site in a folder named `quickstart`.
 
 {{< asciicast 3mf1JGaN0AX0Z7j5kLGl3hSh8 >}}
 
-
 ## Step 3: Add a Theme
 
 See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/).
 
+First, download the theme from Github and add it to your site's `theme` directory:
+
 ```bash
 cd quickstart
-
-# Download the theme
 git init
 git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
-# Note for non-git users:
-#   - If you do not have git installed, you can download the archive of the latest
-#     version of this theme from:
-#       https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
-#   - Extract that .zip file to get a "gohugo-theme-ananke-master" directory.
-#   - Rename that directory to "ananke", and move it into the "themes/" directory.
-# End of note for non-git users.
-
-# Edit your config.toml configuration file
-# and add the Ananke theme.
-echo 'theme = "ananke"' >> config.toml
 ```
 
+*Note for non-git users:*
+   - If you do not have git installed, you can download the archive of the latest
+     version of this theme from:
+       https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
+   - Extract that .zip file to get a "gohugo-theme-ananke-master" directory.
+   - Rename that directory to "ananke", and move it into the "themes/" directory.
 
-{{< asciicast 7naKerRYUGVPj8kiDmdh5k5h9 >}}
+Then, add the theme to the site configuration:
 
+```bash
+echo 'theme = "ananke"' >> config.toml
+```
+
+{{< asciicast 7naKerRYUGVPj8kiDmdh5k5h9 >}}
 
 ## Step 4: Add Some Content
 
@@ -107,15 +102,12 @@ draft: true
 
 ```
 
-
 ## Step 5: Start the Hugo server
 
 Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
 
 {{< asciicast BvJBsF6egk9c163bMsObhuNXj >}}
 
-
-
 ```
 ▶ hugo server -D
 
@@ -140,12 +132,10 @@ Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
 Press Ctrl+C to stop
 ```
 
-
 **Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).**
 
 Feel free to edit or add new content and simply refresh in browser to see changes quickly (You might need to force refresh in webbrowser, something like Ctrl-R usually works).
 
-
 ## Step 6: Customize the Theme
 
 Your new site already looks great, but you will want to tweak it a little before you release it to the public.
@@ -167,12 +157,10 @@ Replace the `title` above with something more personal. Also, if you already hav
 **Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away, though you may need to [clear your cache](https://kb.iu.edu/d/ahic).
 {{% /note %}}
 
-
 For theme specific configuration options, see the [theme site](https://github.com/budparr/gohugo-theme-ananke).
 
 **For further theme customization, see [Customize a Theme](/themes/customizing/).**
 
-
 ### Step 7: Build static pages
 
 It is simple. Just call: