Provide (relative) reference funcs & shortcodes. #676
Conversation
|
As I mentioned in the message above, I am very unhappy about tpl/template.go:432. Yes, my original line number was wrong. It works, but I think that I can probably make this work better just by doing the MethodByName and returning an error on the case where the method cannot be found. Advice on improving this is definitely appreciated. I should add some tests around this, but I have tested this manually for all of the cases indicated. I’m on my iPhone’s hotspot, so I’m going to be avoiding doing much with this until my home internet is back. I’ll probably do it as I fix the tests broken by using |
|
You should do type assertion instead. if p, ok := page.(*hugolib.Page); ok { |
|
Also can you add documentation for this as well. I'm not quite sure even I follow how to use it. |
|
I will add documentation. It’s pretty easy, but the corner cases are a bit weird. Most people will use it with shortcodes, and that is a fairly easy case to document. (Which is to say that I would probably rather not document the I tried the type assertion first, and it won’t work because |
|
This should be good to go now, modulo tests on the |
| --- | ||
|
|
||
| Hugo makes it easy to link documents together with the `ref` and `relref` | ||
| shortcodes. These shortcodes are also used to safely provide links to headers |
|
Thank you for this great work. For some reason, generated doc pages show no body text (all the rest is there), even though the text is in each page's HTML. Not a problem of this branch, because the same thing happens for Hugo's HEAD (7831690). |
|
Modulo the broken Windows tests (fixed by #699), this is fixed and ready to have another round of eyes on it and hopefully merged soon. HEAD is now generating headings that can’t easily be linked without seeing what they are nicely, and I’m using this (at least partially) in my own site without problems (I have a few more to fix, but it works well enough). |
|
@halostatue Let me know when this is ready to merge and I'll merge it in. |
|
I just reworked the documentation based on some comments by @bjornerik. It’s much more example-focused and I’m really happy with it now. I’d like some quick eyes on the new documentation, but I think it’s ready now. |
- `.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.
- 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.
|
Something happened that appears to have removed ab3d2ad from master, but it still looks correct to me. |
|
@halostatue Thanks for this. Merged and pushed as fd33e5d |
d1cf9adc4 Fix typo 26e10a690 Fix the name and arg mismatch between partial defn and call 2db0e53cd Merge commit '9c36cff15224f6cbd19058ad61311229b7a23c83' 9c36cff15 Squashed 'themes/gohugoioTheme/' changes from 68ddff44..b8202f5 4b021eff8 Update lang.Merge.md b37af2916 Add title to yaml a9a281233 Fixed incorrect usage of the code-toggle shortcode 4560a0169 Update Warning for Theme Links (#676) 0305e3c6b Document .File.ContentBaseName 6d30c5aa1 Update configuration.md 158df174a Document .Sites and .Sites.First 0c0f583b8 Add stale config e2531afd8 Document path template functions 4dd779057 Clarify that partialCached is per site/language 19e5bbe0c Update index.md 44b000857 Add missing dot a41300cf9 Release 0.52 2d1d92b88 Merge branch 'temp52' c5925250d releaser: Prepare repository for 0.53-DEV d000b04a2 releaser: Add release notes to /docs for release of 0.52 4bb983a0a releaser: Bump versions for release of 0.52 36736ca28 tpl: Add "param" shortcode 378677aa6 Add Elasticsearch/bonsai.io to services doc. 4c3fd4fa4 docs: Document inline shortcodes 6c64c374c Whitelist CSS modules from purge 817a872b9 Improve search icon position cf86ff1c7 Add minification and resource cache clear to build command fd77e8df3 Update asset dependencies and adopt Hugo Pipes cdbe97e8c Update render.md b0e279220 git command to update submodule to latest a1cb98c12 cache/filecache: Add a :project placeholder 07c1b2b46 cache/filecache: Use time.Duration for maxAge ffa9b165e Add AND as a title 6e7733b40 Add OR as a sub title to make it easier to find in search 72b6791a1 docs: Document the new file cache 714d3ca91 Fix minification issues cd1e961da Revert "Add Elasticsearch/bonsai.io to services doc." 15a0cda6e Add Elasticsearch/bonsai.io to services doc. f931d86de Release 0.51 e2ffe867a Merge branch 'temp51' 423e7f5c8 releaser: Prepare repository for 0.52-DEV c6f2d6ae1 releaser: Add release notes to /docs for release of 0.51 5bbb556dc releaser: Bump versions for release of 0.51 3b2b172b9 docs: Document shortcode error handling b8672f3d4 docs: Document symdiff 4bc6071e6 docs: Document complement d1baab752 docs: Re-generate CLI docs 9ea667e24 Revert "tpl: Update Jsonify to return pretty-print output" ce5a1403d docs: Regenerate the docs helper 99a1f4a94 Fix note for reserved partial name(starting with -> including). eba3cbc42 fix accidentally modification on paragraph. 3eebd98c3 Add note for reserved partial name. 40b881cc2 Document templates.Exists b5c3bcd3b Update multilingual.md 61c59c67e Fix misspelling (#648) f21d8c4a4 Correct minor typo (#5372) e967001b9 Release 0.50 685fd6b08 releaser: Prepare repository for 0.51-DEV f245a9faa releaser: Add release notes to /docs for release of 0.50 4354da30d releaser: Bump versions for release of 0.50 feaa05469 docs: Regenerate CLI docs 5c724200c Merge commit 'd6a4af7018e8618944a6471ceeb7aae1d4df6afa' 2ddab36c2 Merge commit '74309fe5699a595080fdb3a14711e0869babce99' 8cf296a7c docs: Regenerate CLI docs 9097683dd tpl: Update Jsonify to return pretty-print output git-subtree-dir: docs git-subtree-split: d1cf9adc412245c96d9d32592a903370d3972aef
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
.Refand.RelReftake 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.about.md), the page will be discovered and the permalink will be returned:/about/about.md#who), the page will be discovered and used to add thepage.UniqueID()to the resulting fragment and permalink:/about/#who:deadbeef..*Refhas been called from aNodeorSiteInfo, it will be returned as is:#who..*Refhas been called from aPage, it will be returned with the page’s unique ID:#who:deadbeef..*Refcan be called from eitherNode,SiteInfo(e.g.,Node.Site),Pageobjects, orShortcodeWithPageobjects in templates..*Refcannot be used in content, so two shortcodes have been created to provide the functionality to content:refandrelref. These are intended to be used within markup, like[Who]({{% ref about.md#who %}})or<a href="{{% ref about.md#who %}}">Who</a>.refandrelreftemplate functions (used to create the shortcodes) that expect aPageobject (see tpl/template.go:426 for code that I’m not happy with) and then the reference string.createShortcodePlaceholderbecause of the way that therefandrelrefare intended to be used in content.