From 50e9a3a3a36e918f531d05dfdd051d7888437b91 Mon Sep 17 00:00:00 2001 From: Nick Groenen Date: Sun, 11 Apr 2021 16:22:01 +0200 Subject: [PATCH] Document workaround for relative links issue with Hugo --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++ docs/usage-advanced.md | 64 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) diff --git a/README.md b/README.md index 9c9bb3e..3ba2b4a 100644 --- a/README.md +++ b/README.md @@ -148,6 +148,67 @@ By default, this will trigger an error and display the chain of notes which caus This behavior may be changed by specifying `--no-recursive-embeds`. Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. +## Relative links with Hugo + +The [Hugo](https://gohugo.io) static site generator [does not support relative links to files](https://notes.nick.groenen.me/notes/relative-linking-in-hugo/). +Instead, it expects you to link to other pages using the [`ref` and `relref` shortcodes](https://gohugo.io/content-management/cross-references/). + +As a result of this, notes that have been exported from Obsidian using obsidian-export do not work out of the box because Hugo doesn't resolve these links correctly. + +[Markdown Render Hooks](https://gohugo.io/getting-started/configuration-markup#markdown-render-hooks) (only supported using the default `goldmark` renderer) allow you to work around this issue however, making exported notes work with Hugo after a bit of one-time setup work. + +Create the file `layouts/_default/_markup/render-link.html` with the following contents: + +```` +{{- $url := urls.Parse .Destination -}} +{{- $scheme := $url.Scheme -}} + + + {{- .Text | safeHTML -}} + + +{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} +```` + +And `layouts/_default/_markup/render-image.html` for images: + +```` +{{- $url := urls.Parse .Destination -}} +{{- $scheme := $url.Scheme -}} + +{{ . | safeHTML }} + +{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} +```` + +With these hooks in place, links to both notes as well as file attachments should now work correctly. + + > + > Note: If you're using a theme which comes with it's own render hooks, you might need to do a little extra work, or customize the snippets above, to avoid conflicts with the hooks from your theme. + # Library usage diff --git a/docs/usage-advanced.md b/docs/usage-advanced.md index 7dc7e14..6e1817d 100644 --- a/docs/usage-advanced.md +++ b/docs/usage-advanced.md @@ -48,4 +48,68 @@ By default, this will trigger an error and display the chain of notes which caus This behavior may be changed by specifying `--no-recursive-embeds`. Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. +## Relative links with Hugo + +The [Hugo] static site generator [does not support relative links to files][hugo-relative-linking]. +Instead, it expects you to link to other pages using the [`ref` and `relref` shortcodes]. + +As a result of this, notes that have been exported from Obsidian using obsidian-export do not work out of the box because Hugo doesn't resolve these links correctly. + +[Markdown Render Hooks] (only supported using the default `goldmark` renderer) allow you to work around this issue however, making exported notes work with Hugo after a bit of one-time setup work. + +Create the file `layouts/_default/_markup/render-link.html` with the following contents: + +``` +{{- $url := urls.Parse .Destination -}} +{{- $scheme := $url.Scheme -}} + + + {{- .Text | safeHTML -}} + + +{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} +``` + +And `layouts/_default/_markup/render-image.html` for images: + +``` +{{- $url := urls.Parse .Destination -}} +{{- $scheme := $url.Scheme -}} + +{{ . | safeHTML }} + +{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} +``` + +With these hooks in place, links to both notes as well as file attachments should now work correctly. + +> Note: If you're using a theme which comes with it's own render hooks, you might need to do a little extra work, or customize the snippets above, to avoid conflicts with the hooks from your theme. + +[`ref` and `relref` shortcodes]: https://gohugo.io/content-management/cross-references/ [gitignore]: https://git-scm.com/docs/gitignore +[hugo-relative-linking]: https://notes.nick.groenen.me/notes/relative-linking-in-hugo/ +[hugo]: https://gohugo.io +[markdown render hooks]: https://gohugo.io/getting-started/configuration-markup#markdown-render-hooks