spf13/hugo — pull request #676 by halostatue (2014-11-25 03:11:46+00:00)
Title: 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 `Who`.

- There are also `ref` and `relref` template functions (used to create the shortcodes) that expect a `Page` object (see tpl/template.go:426 for code that I’m not happy with) and then the reference string.

- 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.