Provide (relative) reference funcs & shortcodes.

-   `.Ref` and `.RelRef` take a reference (the logical filename for a
    page, including extension and/or a document fragment ID) and return
    a permalink (or relative permalink) to the referenced document.

    -   If the reference is a page name (such as `about.md`), the page
        will be discovered and the permalink will be returned: `/about/`
    -   If the reference is a page name with a fragment (such as
        `about.md#who`), the page will be discovered and used to add the
        `page.UniqueID()` to the resulting fragment and permalink:
        `/about/#who:deadbeef`.
    -   If the reference is a fragment and `.*Ref` has been called from
        a `Node` or `SiteInfo`, it will be returned as is: `#who`.
    -   If the reference is a fragment and `.*Ref` has been called from
        a `Page`, it will be returned with the page’s unique ID:
        `#who:deadbeef`.

-   `.*Ref` can be called from either `Node`, `SiteInfo` (e.g.,
    `Node.Site`), `Page` objects, or `ShortcodeWithPage` objects in
    templates.

-   `.*Ref` cannot be used in content, so two shortcodes have been
    created to provide the functionality to content: `ref` and `relref`.
    These are intended to be used within markup, like `[Who]({{% ref
    about.md#who %}})` or `<a href="{{% ref about.md#who %}}">Who</a>`.

-   There are also `ref` and `relref` template functions (used to create
    the shortcodes) that expect a `Page` or `Node` object and the
    reference string (e.g., `{{ relref . "about.md" }}` or `{{
    "about.md" | ref . }}`). It actually looks for `.*Ref` as defined on
    `Node` or `Page` objects.

-   Shortcode handling had to use a *differently unique* wrapper in
    `createShortcodePlaceholder` because of the way that the `ref` and
    `relref` are intended to be used in content.

diff --git a/hugolib/node.go b/hugolib/node.go
index be47863905d9671de27ef6ffed67fa1af94358e9..d502de38983c19d7765e2cb0ae288b809e1e8c9c 100644 (file)
--- a/hugolib/node.go
+++ b/hugolib/node.go
@@ -104,6 +104,14 @@ func (n *Node) IsPage() bool {
        return !n.IsNode()
 }
 
+func (n *Node) Ref(ref string) (string, error) {
+       return n.Site.Ref(ref, nil)
+}
+
+func (n *Node) RelRef(ref string) (string, error) {
+       return n.Site.RelRef(ref, nil)
+}
+
 type UrlPath struct {
        Url       string
        Permalink template.HTML

diff --git a/hugolib/page.go b/hugolib/page.go
index 67a6842c1ad80d9db7d2eb05b9028a5624e9d19a..7bf9e7fec14615ae314cd7e1acbc606535e3df06 100644 (file)
--- a/hugolib/page.go
+++ b/hugolib/page.go
@@ -102,6 +102,14 @@ func (p *Page) UniqueId() string {
        return p.Source.UniqueId()
 }
 
+func (p *Page) Ref(ref string) (string, error) {
+       return p.Node.Site.Ref(ref, p)
+}
+
+func (p *Page) RelRef(ref string) (string, error) {
+       return p.Node.Site.RelRef(ref, p)
+}
+
 // for logging
 func (p *Page) lineNumRawContentStart() int {
        return bytes.Count(p.frontmatter, []byte("\n")) + 1

diff --git a/hugolib/shortcode.go b/hugolib/shortcode.go
index 7e56c2a4a8ff4513beb7d961ae8e0c284790430f..9f7508e12fab328d06e65af8fecfd42a7ce742df 100644 (file)
--- a/hugolib/shortcode.go
+++ b/hugolib/shortcode.go
@@ -41,6 +41,14 @@ type ShortcodeWithPage struct {
        Page   *Page
 }
 
+func (scp *ShortcodeWithPage) Ref(ref string) (string, error) {
+       return scp.Page.Ref(ref)
+}
+
+func (scp *ShortcodeWithPage) RelRef(ref string) (string, error) {
+       return scp.Page.RelRef(ref)
+}
+
 func (scp *ShortcodeWithPage) Get(key interface{}) interface{} {
        if reflect.ValueOf(scp.Params).Len() == 0 {
                return nil
@@ -120,7 +128,6 @@ func (sc shortcode) String() string {
 // all in  one go: extract, render and replace
 // only used for testing
 func ShortcodesHandle(stringToParse string, page *Page, t tpl.Template) string {
-
        tmpContent, tmpShortcodes := extractAndRenderShortcodes(stringToParse, page, t)
 
        if len(tmpShortcodes) > 0 {
@@ -153,7 +160,7 @@ func isInnerShortcode(t *template.Template) bool {
 }
 
 func createShortcodePlaceholder(id int) string {
-       return fmt.Sprintf("<div>%s-%d</div>", shortcodePlaceholderPrefix, id)
+       return fmt.Sprintf("{@{@%s-%d@}@}", shortcodePlaceholderPrefix, id)
 }
 
 func renderShortcodes(sc shortcode, p *Page, t tpl.Template) string {
@@ -171,6 +178,10 @@ func renderShortcodes(sc shortcode, p *Page, t tpl.Template) string {
        return shortcodes
 }
 
+const innerNewlineRegexp = "\n"
+const innerCleanupRegexp = `\A<p>(.*)</p>\n\z`
+const innerCleanupExpand = "$1"
+
 func renderShortcode(sc shortcode, tokenizedShortcodes map[string](string), cnt int, p *Page, t tpl.Template) string {
        var data = &ShortcodeWithPage{Params: sc.params, Page: p}
        tmpl := GetTemplate(sc.name, t)
@@ -201,7 +212,33 @@ func renderShortcode(sc shortcode, tokenizedShortcodes map[string](string), cnt
                }
 
                if sc.doMarkup {
-                       data.Inner = template.HTML(helpers.RenderBytes([]byte(inner), p.guessMarkupType(), p.UniqueId()))
+                       newInner := helpers.RenderBytes([]byte(inner), p.guessMarkupType(), p.UniqueId())
+
+                       // If the type is “unknown” or “markdown”, we assume the markdown
+                       // generation has been performed. Given the input: `a line`, markdown
+                       // specifies the HTML `<p>a line</p>\n`. When dealing with documents as a
+                       // whole, this is OK. When dealing with an `{{ .Inner }}` block in Hugo,
+                       // this is not so good. This code does two things:
+                       //
+                       // 1.  Check to see if inner has a newline in it. If so, the Inner data is
+                       //     unchanged.
+                       // 2   If inner does not have a newline, strip the wrapping <p> block and
+                       //     the newline. This was previously tricked out by wrapping shortcode
+                       //     substitutions in <div>HUGOSHORTCODE-1</div> which prevents the
+                       //     generation, but means that you can’t use shortcodes inside of
+                       //     markdown structures itself (e.g., `[foo]({{% ref foo.md %}})`).
+                       switch p.guessMarkupType() {
+                       case "unknown", "markdown":
+                               if match, _ := regexp.MatchString(innerNewlineRegexp, inner); !match {
+                                       cleaner, err := regexp.Compile(innerCleanupRegexp)
+
+                                       if err == nil {
+                                               newInner = cleaner.ReplaceAll(newInner, []byte(innerCleanupExpand))
+                                       }
+                               }
+                       }
+
+                       data.Inner = template.HTML(newInner)
                } else {
                        data.Inner = template.HTML(inner)
                }
@@ -401,8 +438,8 @@ Loop:
 // Replace prefixed shortcode tokens (HUGOSHORTCODE-1, HUGOSHORTCODE-2) with the real content.
 // This assumes that all tokens exist in the input string and that they are in order.
 // numReplacements = -1 will do len(replacements), and it will always start from the beginning (1)
-// wrappendInDiv = true means that the token is wrapped in a <div></div>
-func replaceShortcodeTokens(source []byte, prefix string, numReplacements int, wrappedInDiv bool, replacements map[string]string) ([]byte, error) {
+// wrapped = true means that the token has been wrapped in {@{@/@}@}
+func replaceShortcodeTokens(source []byte, prefix string, numReplacements int, wrapped bool, replacements map[string]string) ([]byte, error) {
 
        if numReplacements < 0 {
                numReplacements = len(replacements)
@@ -417,8 +454,8 @@ func replaceShortcodeTokens(source []byte, prefix string, numReplacements int, w
        for i := 1; i <= numReplacements; i++ {
                key := prefix + "-" + strconv.Itoa(i)
 
-               if wrappedInDiv {
-                       key = "<div>" + key + "</div>"
+               if wrapped {
+                       key = "{@{@" + key + "@}@}"
                }
                val := []byte(replacements[key])
 
@@ -433,16 +470,17 @@ func replaceShortcodeTokens(source []byte, prefix string, numReplacements int, w
        for i := 0; i < numReplacements; i++ {
                tokenNum := i + 1
                oldVal := prefix + "-" + strconv.Itoa(tokenNum)
-               if wrappedInDiv {
-                       oldVal = "<div>" + oldVal + "</div>"
+               if wrapped {
+                       oldVal = "{@{@" + oldVal + "@}@}"
                }
                newVal := []byte(replacements[oldVal])
                j := start
 
                k := bytes.Index(source[start:], []byte(oldVal))
+
                if k < 0 {
                        // this should never happen, but let the caller decide to panic or not
-                       return nil, fmt.Errorf("illegal state in content; shortcode token #%d is missing or out of order", tokenNum)
+                       return nil, fmt.Errorf("illegal state in content; shortcode token #%d is missing or out of order (%q)", tokenNum, source)
                }
                j += k
 

diff --git a/hugolib/shortcode_test.go b/hugolib/shortcode_test.go
index 9c5bc1c58994d826f9ef83e74b08ecf4b9384139..3a215b77499e0054d69bfa2cea4a4ced93af8f9a 100644 (file)
--- a/hugolib/shortcode_test.go
+++ b/hugolib/shortcode_test.go
@@ -111,7 +111,9 @@ func TestNestedSC(t *testing.T) {
        tem.AddInternalShortcode("scn1.html", `<div>Outer, inner is {{ .Inner }}</div>`)
        tem.AddInternalShortcode("scn2.html", `<div>SC2</div>`)
 
-       CheckShortCodeMatch(t, `{{% scn1 %}}{{% scn2 %}}{{% /scn1 %}}`, "<div>Outer, inner is <div>SC2</div>\n</div>", tem)
+       CheckShortCodeMatch(t, `{{% scn1 %}}{{% scn2 %}}{{% /scn1 %}}`, "<div>Outer, inner is <div>SC2</div></div>", tem)
+
+       CheckShortCodeMatch(t, `{{< scn1 >}}{{% scn2 %}}{{< /scn1 >}}`, "<div>Outer, inner is <div>SC2</div></div>", tem)
 }
 
 func TestNestedComplexSC(t *testing.T) {
@@ -121,11 +123,11 @@ func TestNestedComplexSC(t *testing.T) {
        tem.AddInternalShortcode("aside.html", `-aside-{{    .Inner  }}-asideStop-`)
 
        CheckShortCodeMatch(t, `{{< row >}}1-s{{% column %}}2-**s**{{< aside >}}3-**s**{{< /aside >}}4-s{{% /column %}}5-s{{< /row >}}6-s`,
-               "-row-1-s-col-<p>2-<strong>s</strong>-aside-3-**s**-asideStop-4-s</p>\n-colStop-5-s-rowStop-6-s", tem)
+               "-row-1-s-col-2-<strong>s</strong>-aside-3-**s**-asideStop-4-s-colStop-5-s-rowStop-6-s", tem)
 
        // turn around the markup flag
        CheckShortCodeMatch(t, `{{% row %}}1-s{{< column >}}2-**s**{{% aside %}}3-**s**{{% /aside %}}4-s{{< /column >}}5-s{{% /row %}}6-s`,
-               "-row-<p>1-s-col-2-**s**-aside-<p>3-<strong>s</strong></p>\n-asideStop-4-s-colStop-5-s</p>\n-rowStop-6-s", tem)
+               "-row-1-s-col-2-**s**-aside-3-<strong>s</strong>-asideStop-4-s-colStop-5-s-rowStop-6-s", tem)
 }
 
 func TestFigureImgWidth(t *testing.T) {
@@ -149,7 +151,7 @@ void do();
        CheckShortCodeMatch(t, code, "\n<div class=\"highlight\" style=\"background: #ffffff\"><pre style=\"line-height: 125%\"><span style=\"font-weight: bold\">void</span> do();\n</pre></div>\n", tem)
 }
 
-const testScPlaceholderRegexp = "<div>HUGOSHORTCODE-\\d+</div>"
+const testScPlaceholderRegexp = "{@{@HUGOSHORTCODE-\\d+@}@}"
 
 func TestExtractShortcodes(t *testing.T) {
        for i, this := range []struct {
@@ -182,18 +184,18 @@ func TestExtractShortcodes(t *testing.T) {
                        `inner([], false){[inner2-> inner2([\"param1\"], true){[inner2txt->inner3 inner3(%!q(<nil>), false){[inner3txt]}]} final close->`,
                        fmt.Sprintf("Inner->%s<-done", testScPlaceholderRegexp), ""},
                {"two inner", `Some text. {{% inner %}}First **Inner** Content{{% / inner %}} {{< inner >}}Inner **Content**{{< / inner >}}. Some more text.`,
-                       `map["<div>HUGOSHORTCODE-1</div>:inner([], true){[First **Inner** Content]}" "<div>HUGOSHORTCODE-2</div>:inner([], false){[Inner **Content**]}"]`,
+                       `map["{@{@HUGOSHORTCODE-1@}@}:inner([], true){[First **Inner** Content]}" "{@{@HUGOSHORTCODE-2@}@}:inner([], false){[Inner **Content**]}"]`,
                        fmt.Sprintf("Some text. %s %s. Some more text.", testScPlaceholderRegexp, testScPlaceholderRegexp), ""},
                {"closed without content", `Some text. {{< inner param1 >}}{{< / inner >}}. Some more text.`, `inner([\"param1\"], false){[]}`,
                        fmt.Sprintf("Some text. %s. Some more text.", testScPlaceholderRegexp), ""},
                {"two shortcodes", "{{< sc1 >}}{{< sc2 >}}",
-                       `map["<div>HUGOSHORTCODE-1</div>:sc1([], false){[]}" "<div>HUGOSHORTCODE-2</div>:sc2([], false){[]}"]`,
+                       `map["{@{@HUGOSHORTCODE-1@}@}:sc1([], false){[]}" "{@{@HUGOSHORTCODE-2@}@}:sc2([], false){[]}"]`,
                        testScPlaceholderRegexp + testScPlaceholderRegexp, ""},
                {"mix of shortcodes", `Hello {{< sc1 >}}world{{% sc2 p2="2"%}}. And that's it.`,
-                       `map["<div>HUGOSHORTCODE-1</div>:sc1([], false){[]}" "<div>HUGOSHORTCODE-2</div>:sc2([\"p2:2\"]`,
+                       `map["{@{@HUGOSHORTCODE-1@}@}:sc1([], false){[]}" "{@{@HUGOSHORTCODE-2@}@}:sc2([\"p2:2\"]`,
                        fmt.Sprintf("Hello %sworld%s. And that's it.", testScPlaceholderRegexp, testScPlaceholderRegexp), ""},
                {"mix with inner", `Hello {{< sc1 >}}world{{% inner p2="2"%}}Inner{{%/ inner %}}. And that's it.`,
-                       `map["<div>HUGOSHORTCODE-1</div>:sc1([], false){[]}" "<div>HUGOSHORTCODE-2</div>:inner([\"p2:2\"], true){[Inner]}"]`,
+                       `map["{@{@HUGOSHORTCODE-1@}@}:sc1([], false){[]}" "{@{@HUGOSHORTCODE-2@}@}:inner([\"p2:2\"], true){[Inner]}"]`,
                        fmt.Sprintf("Hello %sworld%s. And that's it.", testScPlaceholderRegexp, testScPlaceholderRegexp), ""},
        } {
 
@@ -286,24 +288,16 @@ func TestReplaceShortcodeTokens(t *testing.T) {
                wrappedInDiv    bool
                expect          interface{}
        }{
-               {[]byte("Hello PREFIX-1."), "PREFIX",
-                       map[string]string{"PREFIX-1": "World"}, -1, false, []byte("Hello World.")},
-               {[]byte("A <div>A-1</div> asdf <div>A-2</div>."), "A",
-                       map[string]string{"<div>A-1</div>": "v1", "<div>A-2</div>": "v2"}, -1, true, []byte("A v1 asdf v2.")},
-               {[]byte("Hello PREFIX2-1. Go PREFIX2-2, Go, Go PREFIX2-3 Go Go!."), "PREFIX2",
-                       map[string]string{"PREFIX2-1": "Europe", "PREFIX2-2": "Jonny", "PREFIX2-3": "Johnny"},
-                       -1, false, []byte("Hello Europe. Go Jonny, Go, Go Johnny Go Go!.")},
-               {[]byte("A PREFIX-2 PREFIX-1."), "PREFIX",
-                       map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, -1, false, false},
-               {[]byte("A PREFIX-1 PREFIX-2"), "PREFIX",
-                       map[string]string{"PREFIX-1": "A"}, -1, false, []byte("A A PREFIX-2")},
-               {[]byte("A PREFIX-1 but not the second."), "PREFIX",
-                       map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, -1, false, false},
-               {[]byte("An PREFIX-1."), "PREFIX",
-                       map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, 1, false, []byte("An A.")},
-               {[]byte("An PREFIX-1 PREFIX-2."), "PREFIX",
-                       map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, 1, false, []byte("An A PREFIX-2.")},
+               {[]byte("Hello PREFIX-1."), "PREFIX", map[string]string{"PREFIX-1": "World"}, -1, false, []byte("Hello World.")},
+               {[]byte("A {@{@A-1@}@} asdf {@{@A-2@}@}."), "A", map[string]string{"{@{@A-1@}@}": "v1", "{@{@A-2@}@}": "v2"}, -1, true, []byte("A v1 asdf v2.")},
+               {[]byte("Hello PREFIX2-1. Go PREFIX2-2, Go, Go PREFIX2-3 Go Go!."), "PREFIX2", map[string]string{"PREFIX2-1": "Europe", "PREFIX2-2": "Jonny", "PREFIX2-3": "Johnny"}, -1, false, []byte("Hello Europe. Go Jonny, Go, Go Johnny Go Go!.")},
+               {[]byte("A PREFIX-2 PREFIX-1."), "PREFIX", map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, -1, false, false},
+               {[]byte("A PREFIX-1 PREFIX-2"), "PREFIX", map[string]string{"PREFIX-1": "A"}, -1, false, []byte("A A PREFIX-2")},
+               {[]byte("A PREFIX-1 but not the second."), "PREFIX", map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, -1, false, false},
+               {[]byte("An PREFIX-1."), "PREFIX", map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, 1, false, []byte("An A.")},
+               {[]byte("An PREFIX-1 PREFIX-2."), "PREFIX", map[string]string{"PREFIX-1": "A", "PREFIX-2": "B"}, 1, false, []byte("An A PREFIX-2.")},
        } {
+               fmt.Printf("this<%#v>", this)
                results, err := replaceShortcodeTokens(this.input, this.prefix, this.numReplacements, this.wrappedInDiv, this.replacements)
 
                if b, ok := this.expect.(bool); ok && !b {

diff --git a/hugolib/site.go b/hugolib/site.go
index b17a19280ab9cad49f37fa27b9a76e735ee5180d..75f34386cde16cbcbfddb8edce15f21506e08fe1 100644 (file)
--- a/hugolib/site.go
+++ b/hugolib/site.go
@@ -19,6 +19,7 @@ import (
        "fmt"
        "html/template"
        "io"
+       "net/url"
        "os"
        "strconv"
        "strings"
@@ -128,6 +129,65 @@ func (s *SiteInfo) GetParam(key string) interface{} {
        return nil
 }
 
+func (s *SiteInfo) refLink(ref string, page *Page, relative bool) (string, error) {
+       var refUrl *url.URL
+       var err error
+
+       refUrl, err = url.Parse(ref)
+
+       if err != nil {
+               return "", err
+       }
+
+       var target *Page = nil
+       var link string = ""
+
+       if refUrl.Path != "" {
+               var target *Page
+
+               for _, page := range []*Page(*s.Pages) {
+                       if page.Source.Path() == refUrl.Path || page.Source.LogicalName() == refUrl.Path {
+                               target = page
+                               break
+                       }
+               }
+
+               if target == nil {
+                       return "", errors.New(fmt.Sprintf("No page found with path or logical name \"%s\".\n", refUrl.Path))
+               }
+
+               if relative {
+                       link, err = target.RelPermalink()
+               } else {
+                       link, err = target.Permalink()
+               }
+
+               if err != nil {
+                       return "", err
+               }
+       }
+
+       if refUrl.Fragment != "" {
+               link = link + "#" + refUrl.Fragment
+
+               if refUrl.Path != "" {
+                       link = link + ":" + target.UniqueId()
+               } else if page != nil {
+                       link = link + ":" + page.UniqueId()
+               }
+       }
+
+       return link, nil
+}
+
+func (s *SiteInfo) Ref(ref string, page *Page) (string, error) {
+       return s.refLink(ref, page, false)
+}
+
+func (s *SiteInfo) RelRef(ref string, page *Page) (string, error) {
+       return s.refLink(ref, page, true)
+}
+
 type runmode struct {
        Watching bool
 }

diff --git a/tpl/template.go b/tpl/template.go
index d057f174d91ee9ad5a8487189464dd71f9319ee8..bd700f6ab36fbdbcf3f82c5380ea5aa6f6f93912 100644 (file)
--- a/tpl/template.go
+++ b/tpl/template.go
@@ -16,6 +16,7 @@ package tpl
 import (
        "bytes"
        "errors"
+       "fmt"
        "github.com/eknkc/amber"
        "github.com/spf13/cast"
        "github.com/spf13/hugo/helpers"
@@ -110,6 +111,8 @@ func New() Template {
                "upper":       func(a string) string { return strings.ToUpper(a) },
                "title":       func(a string) string { return strings.Title(a) },
                "partial":     Partial,
+               "ref":         Ref,
+               "relref":      RelRef,
        }
 
        templates.Funcs(funcMap)
@@ -427,6 +430,41 @@ func Markdownify(text string) template.HTML {
        return template.HTML(helpers.RenderBytes([]byte(text), "markdown", ""))
 }
 
+func refPage(page interface{}, ref, methodName string) template.HTML {
+       value := reflect.ValueOf(page)
+
+       method := value.MethodByName(methodName)
+
+       if method.IsValid() && method.Type().NumIn() == 1 && method.Type().NumOut() == 2 {
+               result := method.Call([]reflect.Value{reflect.ValueOf(ref)})
+
+               url, err := result[0], result[1]
+
+               if !err.IsNil() {
+                       jww.ERROR.Printf("%s", err.Interface())
+                       return template.HTML(fmt.Sprintf("%s", err.Interface()))
+               }
+
+               if url.String() == "" {
+                       jww.ERROR.Printf("ref %s could not be found\n", ref)
+                       return template.HTML(ref)
+               }
+
+               return template.HTML(url.String())
+       }
+
+       jww.ERROR.Printf("Can only create references from Page and Node objects.")
+       return template.HTML(ref)
+}
+
+func Ref(page interface{}, ref string) template.HTML {
+       return refPage(page, ref, "Ref")
+}
+
+func RelRef(page interface{}, ref string) template.HTML {
+       return refPage(page, ref, "RelRef")
+}
+
 func SafeHtml(text string) template.HTML {
        return template.HTML(text)
 }

diff --git a/tpl/template_embedded.go b/tpl/template_embedded.go
index e2ad1fd9379669fe939864b9281e01b9c9b862e9..85015c50eab3b7a5f9ed3864da8287395a9d759a 100644 (file)
--- a/tpl/template_embedded.go
+++ b/tpl/template_embedded.go
@@ -19,6 +19,8 @@ type Tmpl struct {
 }
 
 func (t *GoHtmlTemplate) EmbedShortcodes() {
+       t.AddInternalShortcode("ref.html", `{{ .Get 0 | ref .Page }}`)
+       t.AddInternalShortcode("relref.html", `{{ .Get 0 | relref .Page }}`)
        t.AddInternalShortcode("highlight.html", `{{ .Get 0 | highlight .Inner  }}`)
        t.AddInternalShortcode("test.html", `This is a simple Test`)
        t.AddInternalShortcode("figure.html", `<!-- image -->