With two entries of frequently encountered or obscured troubles so far:
- "Categories with accented characters" Unicode NFC/NFD mismatch
on Mac OS X (See #739)
- `hugo new` aborts with cryptic EOF error (See #776)
I was initially confused about how to use summaries. The only example code I found in the docs was on the page for list nodes, but that uses `Render "summary"`, which is for views, not an article summary. I thought a little example here might clarify the issue for future users.
It allows to use `where` template function like SQL `where` clause.
For example,
{{ range where .Data.Pages "Type" "!=" "post" }}
{{ .Content }}
{{ end }}
Now these operators are implemented:
=, ==, eq, !=, <>, ne, >=, ge, >, gt, <=, le, <, lt, in, not in
It also fixes `TestWhere` more readable
'where' template function used to accept only each element's struct
field name, method name and map key name as its second argument. This
extends it to accept dot chaining key like 'Params.foo.bar' as the
argument. It evaluates sub elements of each array elements and checks it
matches the third argument value.
Typical use case would be for filtering Pages by user defined front
matter value. For example, to filter pages which have 'Params.foo.bar'
and its value is 'baz', it is used like
{{ range where .Data.Pages "Params.foo.bar" "baz" }}
{{ .Content }}
{{ end }}
It ignores all leading and trailing dots so it can also be used with
".Params.foo.bar"
- Rejigged the weight of the extras/ content for the new crossreferences
page.
- Used the new {{</*…*/>}} format for documenting highlighting and to
prevent a warning about the missing `fig` shortcode.
- Correct some typos
- Add backticks and commas where necessary
- Use fenced code blocks specifying "bash" as the language
to avoid weird highlighting
- Place commas outside of quotation marks surroundingn codes
to avoid possible confusion
- Suggest users to use the discussion forum rather than the
mailing list
The whole article should maybe be rewriten to have a better content flow (maybe adding a table of content), to introduce both possible strategies. But at least, the technical steps are there!
This small function feels important enough to maybe deserve more than these three lines, but this will have to do for now.
This assumes that #652 gets merged.
This commit contains a restructuring and partial rewrite of the shortcode handling.
Prior to this commit rendering of the page content was mingled with handling of the shortcodes. This led to several oddities.
The new flow is:
1. Shortcodes are extracted from page and replaced with placeholders.
2. Shortcodes are processed and rendered
3. Page is processed
4. The placeholders are replaced with the rendered shortcodes
The handling of summaries is also made simpler by this.
This commit also introduces some other chenges:
1. distinction between shortcodes that need further processing and those who do not:
* `{{< >}}`: Typically raw HTML. Will not be processed.
* `{{% %}}`: Will be processed by the page's markup engine (Markdown or (infuture) Asciidoctor)
The above also involves a new shortcode-parser, with lexical scanning inspired by Rob Pike's talk called "Lexical Scanning in Go",
which should be easier to understand, give better error messages and perform better.
2. If you want to exclude a shortcode from being processed (for documentation etc.), the inner part of the shorcode must be commented out, i.e. `{{%/* movie 47238zzb */%}}`. See the updated shortcode section in the documentation for further examples.
The new parser supports nested shortcodes. This isn't new, but has two related design choices worth mentioning:
* The shortcodes will be rendered individually, so If both `{{< >}}` and `{{% %}}` are used in the nested hierarchy, one will be passed through the page's markdown processor, the other not.
* To avoid potential costly overhead of always looking far ahead for a possible closing tag, this implementation looks at the template itself, and is branded as a container with inner content if it contains a reference to `.Inner`
Fixes#565Fixes#480Fixes#461
And probably some others.
Update heading levels to confirm to the other tutorials. Create a similar front-matter using YAML, since I couldn't figure out how to get the menu:main:parent working as TOML.
