Shortcode for including remote markdown files #1739
Conversation
There was a problem hiding this comment.
@fekete-robert this is fan-flipping-tastic! I ran into one feature request that I've added here. Take a look.
| {{ end }} | ||
|
|
||
| {{/* Output stuff after the frontmatter if a frontmatter was detected. */}} | ||
| {{- index $split 2 | markdownify | safeHTML -}} |
There was a problem hiding this comment.
| {{- index $split 2 | markdownify | safeHTML -}} | |
| {{- delimit (last 1 $split) "" | markdownify | safeHTML -}} |
I have some GitHub README's that have H1s (#) instead of frontmatter. I want to be able to trim those H1s from my pages. This small change will allow us to use the trim parameter to trim H1s too. 🎊
There was a problem hiding this comment.
This seems to miss a few things... it would be great to find a solution here that preserves all built-in Docsy behaviors, such as:
rendering fancy stuff (like mermaid diagrams)adding self-links(these two were resolved with the update to 0.10 and were just me munging two different issues together)- building the in-page ToC
- indexing?
I've tried $.Page.RenderString instead of markdown | safeHTML and that seems to do better with the diagrams, but doesn't catch everything. My hugo-fu doesn't go much beyond that.
There was a problem hiding this comment.
It seems simpler is better here. I've removed all of the filters after finding https://discourse.gohugo.io/t/extend-tableofcontents-from-within-shortcode/31994/3 and it seems to work much better.
I also rewrote the split method so that I believe it only splits on the first delimiter, then rejoins the rest of the content after.
Since my changes have gotten kind of large, I've added the whole of the shortcode in the new review comment.
| The `include-remote-md` shortcode fetches a remote markdown file and includes it in the page. This happens only when your Docsy project is built, so future changes of the remote markdown file are only included when you rebuild your project. | ||
|
|
||
| If the file has a frontmatter, define the marker of the frontmatter in the second parameter of the shortcode (defaults to `---`). Note that if the content after the frontmatter includes the marker (for example, includes `---` as part of a markdown-formatted table) the content is truncated. | ||
|
|
There was a problem hiding this comment.
| If the file has a H1 (`# ....`) instead of frontmatter, you can put the title line in as the second parameter and it will be removed instead. For example: | |
| ```go-html-template | |
| {{%/* include-remote-md "https://raw.githubusercontent.com/google/docsy/main/README.md" "# Docsy" */%}} | |
| \``` | |
| Note: The shortcode _must_ be wrapped with `%` for proper formatting. This will require [configuring Goldmark to render raw HTML](https://www.docsy.dev/docs/adding-content/content/#page-contents-and-markup). |
(The leading \ on the end of the code fence will need to be removed because I'm not sure how to put a fence in a suggestion without breaking it)
There was a problem hiding this comment.
New rewrites to include-remote-md.html that resolve some of the issues discussed above:
{{/* Fetch a remote markdown file and include it in the page. If the file has a frontmatter, define the marker of the frontmatter in the second parameter (defaults to "---"). If the content after the frontmatter includes the marker (for example, includes "---" as part of a markdown-formatted table) the content included will be incomplete. */}}
{{ $url := .Get 0 }}
{{ $marker := .Get 1 | default "---" }}
{{/* Do not change the indentation of the following block. */}}
{{ with resources.GetRemote $url }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{/* Test for frontmatter. */}}
{{ if hasPrefix .Content $marker }}
{{/* Split the content at the first marker. */}}
{{ $split := split .Content $marker }}
{{/* Rejoin the content after the first split, so we don't accidentally truncate tables or other content with similar strings. */}}
{{ $content := delimit (after 1 $split) $marker }}
{{/* Output stuff after the frontmatter if a frontmatter was detected. */}}
{{- $content -}}
{{ else }}
{{/* Output the content of the file if no frontmatter was detected. */}}
{{- .Content -}}
{{ end }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
| {{ end }} | ||
|
|
||
| {{/* Output stuff after the frontmatter if a frontmatter was detected. */}} | ||
| {{- index $split 2 | markdownify | safeHTML -}} |
There was a problem hiding this comment.
It seems simpler is better here. I've removed all of the filters after finding https://discourse.gohugo.io/t/extend-tableofcontents-from-within-shortcode/31994/3 and it seems to work much better.
I also rewrote the split method so that I believe it only splits on the first delimiter, then rejoins the rest of the content after.
Since my changes have gotten kind of large, I've added the whole of the shortcode in the new review comment.
Fixes #1716