commit 2681633db8d340d2dc59cf801419874d572fc704
parent 1b2472825664763c0b88807b0d193e73553423ec
Author: Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
Date: Sun, 7 Feb 2021 18:08:46 +0100
markup/goldmark: Add attributes support for blocks (tables etc.)
E.g.:
```
> foo
> bar
{.myclass}
```
There are some current limitations: For tables you can currently only apply it to the full table, and for lists the ul/ol-nodes only, e.g.:
```
* Fruit
* Apple
* Orange
* Banana
{.fruits}
* Dairy
* Milk
* Cheese
{.dairies}
{.list}
```
Fixes #7548
Diffstat:
8 files changed, 303 insertions(+), 6 deletions(-)
diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md
@@ -40,6 +40,34 @@ unsafe
typographer
: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/).
+attribute
+: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
+
+{{< new-in "0.81" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
+
+A blockquote with a CSS class:
+
+```md
+> foo
+> bar
+{.myclass}
+```
+
+There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.:
+
+```md
+* Fruit
+ * Apple
+ * Orange
+ * Banana
+ {.fruits}
+* Dairy
+ * Milk
+ * Cheese
+ {.dairies}
+{.list}
+```
+
autoHeadingIDType ("github") {{< new-in "0.62.2" >}}
: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs work as with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func.
diff --git a/docs/data/docs.json b/docs/data/docs.json
@@ -1509,7 +1509,10 @@
"parser": {
"autoHeadingID": true,
"autoHeadingIDType": "github",
- "attribute": true
+ "attribute": {
+ "title": true,
+ "block": false
+ }
},
"extensions": {
"typographer": true,
@@ -3023,7 +3026,7 @@
"Examples": []
},
"Merge": {
- "Description": "Merge creates a copy of the final parameter and merges the preceeding\nparameters into it in reverse order.\nCurrently only maps are supported. Key handling is case insensitive.",
+ "Description": "Merge creates a copy of the final parameter and merges the preceding\nparameters into it in reverse order.\nCurrently only maps are supported. Key handling is case insensitive.",
"Args": [
"params"
],
@@ -3526,6 +3529,12 @@
"Aliases": null,
"Examples": null
},
+ "Overlay": {
+ "Description": "",
+ "Args": null,
+ "Aliases": null,
+ "Examples": null
+ },
"Pixelate": {
"Description": "",
"Args": null,
@@ -4371,7 +4380,7 @@
]
},
"CountRunes": {
- "Description": "CountRunes returns the number of runes in s, excluding whitepace.",
+ "Description": "CountRunes returns the number of runes in s, excluding whitespace.",
"Args": [
"s"
],
diff --git a/markup/goldmark/convert.go b/markup/goldmark/convert.go
@@ -21,6 +21,8 @@ import (
"path/filepath"
"runtime/debug"
+ "github.com/gohugoio/hugo/markup/goldmark/internal/extensions/attributes"
+
"github.com/gohugoio/hugo/identity"
"github.com/pkg/errors"
@@ -137,10 +139,14 @@ func newMarkdown(pcfg converter.ProviderConfig) goldmark.Markdown {
parserOptions = append(parserOptions, parser.WithAutoHeadingID())
}
- if cfg.Parser.Attribute {
+ if cfg.Parser.Attribute.Title {
parserOptions = append(parserOptions, parser.WithAttribute())
}
+ if cfg.Parser.Attribute.Block {
+ extensions = append(extensions, attributes.New())
+ }
+
md := goldmark.New(
goldmark.WithExtensions(
extensions...,
diff --git a/markup/goldmark/convert_test.go b/markup/goldmark/convert_test.go
@@ -17,6 +17,8 @@ import (
"strings"
"testing"
+ "github.com/spf13/cast"
+
"github.com/gohugoio/hugo/markup/goldmark/goldmark_config"
"github.com/gohugoio/hugo/markup/highlight"
@@ -193,6 +195,103 @@ func TestConvertAutoIDBlackfriday(t *testing.T) {
c.Assert(got, qt.Contains, "<h2 id=\"let-s-try-this-shall-we\">")
}
+func TestConvertAttributes(t *testing.T) {
+ c := qt.New(t)
+
+ withBlockAttributes := func(conf *markup_config.Config) {
+ conf.Goldmark.Parser.Attribute.Block = true
+ conf.Goldmark.Parser.Attribute.Title = false
+ }
+
+ withTitleAndBlockAttributes := func(conf *markup_config.Config) {
+ conf.Goldmark.Parser.Attribute.Block = true
+ conf.Goldmark.Parser.Attribute.Title = true
+ }
+
+ for _, test := range []struct {
+ name string
+ withConfig func(conf *markup_config.Config)
+ input string
+ expect interface{}
+ }{
+ {
+ "Title",
+ nil,
+ "## heading {#id .className attrName=attrValue class=\"class1 class2\"}",
+ "<h2 id=\"id\" class=\"className class1 class2\" attrName=\"attrValue\">heading</h2>\n",
+ },
+ {
+ "Blockquote",
+ withBlockAttributes,
+ "> foo\n> bar\n{#id .className attrName=attrValue class=\"class1 class2\"}\n",
+ "<blockquote id=\"id\" class=\"className class1 class2\"><p>foo\nbar</p>\n</blockquote>\n",
+ },
+ {
+ "Paragraph",
+ withBlockAttributes,
+ "\nHi there.\n{.myclass }",
+ "<p class=\"myclass\">Hi there.</p>\n",
+ },
+ {
+ "Ordered list",
+ withBlockAttributes,
+ "\n1. First\n2. Second\n{.myclass }",
+ "<ol class=\"myclass\">\n<li>First</li>\n<li>Second</li>\n</ol>\n",
+ },
+ {
+ "Unordered list",
+ withBlockAttributes,
+ "\n* First\n* Second\n{.myclass }",
+ "<ul class=\"myclass\">\n<li>First</li>\n<li>Second</li>\n</ul>\n",
+ },
+ {
+ "Unordered list, indented",
+ withBlockAttributes,
+ `* Fruit
+ * Apple
+ * Orange
+ * Banana
+ {.fruits}
+* Dairy
+ * Milk
+ * Cheese
+ {.dairies}
+{.list}`,
+ []string{"<ul class=\"list\">\n<li>Fruit\n<ul class=\"fruits\">", "<li>Dairy\n<ul class=\"dairies\">"},
+ },
+ {
+ "Table",
+ withBlockAttributes,
+ `| A | B |
+| ------------- |:-------------:| -----:|
+| AV | BV |
+{.myclass }`,
+ "<table class=\"myclass\">\n<thead>",
+ },
+ {
+ "Title and Blockquote",
+ withTitleAndBlockAttributes,
+ "## heading {#id .className attrName=attrValue class=\"class1 class2\"}\n> foo\n> bar\n{.myclass}",
+ "<h2 id=\"id\" class=\"className class1 class2\" attrName=\"attrValue\">heading</h2>\n<blockquote class=\"myclass\"><p>foo\nbar</p>\n</blockquote>\n",
+ },
+ } {
+ c.Run(test.name, func(c *qt.C) {
+ mconf := markup_config.Default
+ if test.withConfig != nil {
+ test.withConfig(&mconf)
+ }
+ b := convert(c, mconf, test.input)
+ got := string(b.Bytes())
+
+ for _, s := range cast.ToStringSlice(test.expect) {
+ c.Assert(got, qt.Contains, s)
+ }
+
+ })
+ }
+
+}
+
func TestConvertIssues(t *testing.T) {
c := qt.New(t)
diff --git a/markup/goldmark/goldmark_config/config.go b/markup/goldmark/goldmark_config/config.go
@@ -37,7 +37,10 @@ var Default = Config{
Parser: Parser{
AutoHeadingID: true,
AutoHeadingIDType: AutoHeadingIDTypeGitHub,
- Attribute: true,
+ Attribute: ParserAttribute{
+ Title: true,
+ Block: false,
+ },
},
}
@@ -82,5 +85,12 @@ type Parser struct {
AutoHeadingIDType string
// Enables custom attributes.
- Attribute bool
+ Attribute ParserAttribute
+}
+
+type ParserAttribute struct {
+ // Enables custom attributes for titles.
+ Title bool
+ // Enables custom attributeds for blocks.
+ Block bool
}
diff --git a/markup/goldmark/internal/extensions/attributes/attributes.go b/markup/goldmark/internal/extensions/attributes/attributes.go
@@ -0,0 +1,119 @@
+package attributes
+
+import (
+ "github.com/yuin/goldmark"
+ "github.com/yuin/goldmark/ast"
+ "github.com/yuin/goldmark/parser"
+ "github.com/yuin/goldmark/text"
+ "github.com/yuin/goldmark/util"
+)
+
+// This extenion is based on/inspired by https://github.com/mdigger/goldmark-attributes
+// MIT License
+// Copyright (c) 2019 Dmitry Sedykh
+
+var (
+ kindAttributesBlock = ast.NewNodeKind("AttributesBlock")
+
+ defaultParser = new(attrParser)
+ defaultTransformer = new(transformer)
+ attributes goldmark.Extender = new(attrExtension)
+)
+
+func New() goldmark.Extender {
+ return attributes
+}
+
+type attrExtension struct{}
+
+func (a *attrExtension) Extend(m goldmark.Markdown) {
+ m.Parser().AddOptions(
+ parser.WithBlockParsers(
+ util.Prioritized(defaultParser, 100)),
+ parser.WithASTTransformers(
+ util.Prioritized(defaultTransformer, 100),
+ ),
+ )
+}
+
+type attrParser struct{}
+
+func (a *attrParser) CanAcceptIndentedLine() bool {
+ return false
+}
+
+func (a *attrParser) CanInterruptParagraph() bool {
+ return true
+}
+
+func (a *attrParser) Close(node ast.Node, reader text.Reader, pc parser.Context) {
+}
+
+func (a *attrParser) Continue(node ast.Node, reader text.Reader, pc parser.Context) parser.State {
+ return parser.Close
+}
+
+func (a *attrParser) Open(parent ast.Node, reader text.Reader, pc parser.Context) (ast.Node, parser.State) {
+ if attrs, ok := parser.ParseAttributes(reader); ok {
+ // add attributes
+ var node = &attributesBlock{
+ BaseBlock: ast.BaseBlock{},
+ }
+ for _, attr := range attrs {
+ node.SetAttribute(attr.Name, attr.Value)
+ }
+ return node, parser.NoChildren
+ }
+ return nil, parser.RequireParagraph
+}
+
+func (a *attrParser) Trigger() []byte {
+ return []byte{'{'}
+}
+
+type attributesBlock struct {
+ ast.BaseBlock
+}
+
+func (a *attributesBlock) Dump(source []byte, level int) {
+ attrs := a.Attributes()
+ list := make(map[string]string, len(attrs))
+ for _, attr := range attrs {
+ var (
+ name = util.BytesToReadOnlyString(attr.Name)
+ value = util.BytesToReadOnlyString(util.EscapeHTML(attr.Value.([]byte)))
+ )
+ list[name] = value
+ }
+ ast.DumpHelper(a, source, level, list, nil)
+}
+
+func (a *attributesBlock) Kind() ast.NodeKind {
+ return kindAttributesBlock
+}
+
+type transformer struct{}
+
+func (a *transformer) Transform(node *ast.Document, reader text.Reader, pc parser.Context) {
+ var attributes = make([]ast.Node, 0, 500)
+ ast.Walk(node, func(node ast.Node, entering bool) (ast.WalkStatus, error) {
+ if entering && node.Kind() == kindAttributesBlock && !node.HasBlankPreviousLines() {
+ attributes = append(attributes, node)
+ return ast.WalkSkipChildren, nil
+ }
+ return ast.WalkContinue, nil
+ })
+
+ for _, attr := range attributes {
+ if prev := attr.PreviousSibling(); prev != nil &&
+ prev.Type() == ast.TypeBlock {
+ for _, attr := range attr.Attributes() {
+ if _, found := prev.Attribute(attr.Name); !found {
+ prev.SetAttribute(attr.Name, attr.Value)
+ }
+ }
+ }
+ // remove attributes node
+ attr.Parent().RemoveChild(attr.Parent(), attr)
+ }
+}
diff --git a/markup/markup_config/config.go b/markup/markup_config/config.go
@@ -44,6 +44,8 @@ type Config struct {
func Decode(cfg config.Provider) (conf Config, err error) {
conf = Default
+ normalizeConfig(cfg)
+
m := cfg.GetStringMap("markup")
if m == nil {
return
@@ -65,6 +67,17 @@ func Decode(cfg config.Provider) (conf Config, err error) {
return
}
+func normalizeConfig(cfg config.Provider) {
+ // Changed from a bool in 0.81.0
+ const attrKey = "markup.goldmark.parser.attribute"
+ av := cfg.Get(attrKey)
+ if avb, ok := av.(bool); ok {
+ cfg.Set(attrKey, goldmark_config.ParserAttribute{
+ Title: avb,
+ })
+ }
+}
+
func applyLegacyConfig(cfg config.Provider, conf *Config) error {
if bm := cfg.GetStringMap("blackfriday"); bm != nil {
// Legacy top level blackfriday config.
diff --git a/markup/markup_config/config_test.go b/markup/markup_config/config_test.go
@@ -46,6 +46,8 @@ func TestConfig(t *testing.T) {
c.Assert(err, qt.IsNil)
c.Assert(conf.Goldmark.Renderer.Unsafe, qt.Equals, true)
c.Assert(conf.BlackFriday.Fractions, qt.Equals, true)
+ c.Assert(conf.Goldmark.Parser.Attribute.Title, qt.Equals, true)
+ c.Assert(conf.Goldmark.Parser.Attribute.Block, qt.Equals, false)
c.Assert(conf.AsciidocExt.WorkingFolderCurrent, qt.Equals, true)
c.Assert(conf.AsciidocExt.Extensions[0], qt.Equals, "asciidoctor-html5s")
@@ -63,6 +65,14 @@ func TestConfig(t *testing.T) {
v.Set("footnoteReturnLinkContents", "myreturn")
v.Set("pygmentsStyle", "hugo")
v.Set("pygmentsCodefencesGuessSyntax", true)
+
+ v.Set("markup", map[string]interface{}{
+ "goldmark": map[string]interface{}{
+ "parser": map[string]interface{}{
+ "attribute": false, // Was changed to a struct in 0.81.0
+ },
+ },
+ })
conf, err := Decode(v)
c.Assert(err, qt.IsNil)
@@ -72,5 +82,8 @@ func TestConfig(t *testing.T) {
c.Assert(conf.Highlight.Style, qt.Equals, "hugo")
c.Assert(conf.Highlight.CodeFences, qt.Equals, true)
c.Assert(conf.Highlight.GuessSyntax, qt.Equals, true)
+ c.Assert(conf.Goldmark.Parser.Attribute.Title, qt.Equals, false)
+ c.Assert(conf.Goldmark.Parser.Attribute.Block, qt.Equals, false)
+
})
}