Skip to content

Shortcode for including remote markdown files #1739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Shortcode for including remote markdown files #1739

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
91fe87a
Adds shortcode to include remote markdown file
fekete-robert Nov 14, 2023
ae8e761
Document the include-remote-md shortcode
fekete-robert Nov 14, 2023
b6ee9d7
Don't execute sample shortcode
fekete-robert Nov 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions layouts/shortcodes/include-remote-md.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{{/* 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 := split .Content $marker }}

{{ with strings.Contains .Content $marker }} {{- warnf "Remote snippet includes frontmatter marker, content is truncated: %s" $url -}}
{{ end }}

{{/* Output stuff after the frontmatter if a frontmatter was detected. */}}
{{- index $split 2 | markdownify | safeHTML -}}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{{- 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. 🎊

Copy link
Contributor

@froboy froboy Jun 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

{{ else }}
{{/* Output the content of the file if no frontmatter was detected. */}}
{{- .Content | safeHTML -}}
{{ end }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
14 changes: 14 additions & 0 deletions userguide/content/en/docs/adding-content/shortcodes/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -691,6 +691,20 @@ Alternately, Hugo you can display a message on the rendered page instead of thro
{{</* readfile file="includes/deploy.yaml" code="true" lang="yaml" draft="true" */>}}
```

### Include remote markdown files

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.

Copy link
Contributor

@froboy froboy Jun 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)

The remote file must be accessible from the host where you build the project. Authentication is not supported.

If you are including a file from GitHub or a similar provider, use the link of the raw file, for example:

```go-html-template
{{</* include-remote-md "https://github.com/google/docsy/raw/main/userguide/CONTRIBUTING.md" */>}}
```

## Conditional text

The `conditional-text` shortcode allows you to show or hide parts of your content depending on the value of the `buildCondition` parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds.
Expand Down