Skip to content
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

Jump to bottom

feature: Ability to easily embed markdown docs NOT iframe #1716

Open
dtzar opened this issue Nov 9, 2023 · 7 comments · May be fixed by #1739
Open

feature: Ability to easily embed markdown docs NOT iframe #1716

dtzar opened this issue Nov 9, 2023 · 7 comments · May be fixed by #1739

Comments

@dtzar
Copy link

dtzar commented Nov 9, 2023

I'm trying to find a way to embed GitHub markdown content with Hugo/Docsy like what works today with mdbook as seen here for the Cluster API project (source) and website render of that page.
All that I can find is being able to use iframe with Docsy, which does not work since GitHub does not allow embed and likely will not produce desired behavior (feel/functionality). You can see this example deployed here (and equivalent source code).
It's important I figure out a pattern which will work for not only the karpenter project, but also the CAPI project. The ideal goal would be to have a core shared set of documentation and then embedded documentation for each of the providers. Would really like to migrate CAPI* to Hugo/Docsy as this seems to be the standard and offers nicer functionality, but this is a blocker now for both projects (karpenter Azure website would be new).
@fekete-robert
Copy link
Collaborator

You can try to use something like this shortcode:

Invocation:

{{% include-remote-mdsnippet "https://github.com/bank-vaults/vault-operator/raw/main/VERSIONS.md" %}}

Shortcode (layouts/shortcode/include-remote-mdsnippet.html):

{{/* Fetch a remote markdown file (that doesn't include frontmatter) and include it in the page. */}}
{{ $url := .Get 0 }}

{{/* Do not change the indentation of the following block */}}
{{ with resources.GetRemote $url }}
{{ with .Err }}
    {{ errorf "%s" . }}
{{ else }}
{{- .Content | safeHTML -}}
{{ end }}
{{ else }}
    {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}

I made it for one of my projects for a similar usecase, it doesn't do much, but might be enough for you.

@fekete-robert
Copy link
Collaborator

Alternatively, if you want to include files only from one or two repos, you can add them to your project as dependencies, mount the content of the repos somewhere, and include the files using readfile.

@dtzar
Copy link
Author

dtzar commented Nov 9, 2023 •
edited

Thanks for the quick response @fekete-robert! I think the include-remote-mdsnippet shortcode will work if I can find a way to remove the top header markdown content at the top of the file.

e.g.

---
title: "Development Guide"
linkTitle: "Development Guide"
weight: 80
description: >
  My description
---

Live example here

@fekete-robert
Copy link
Collaborator

Try this, it will handle the frontmatter, with some limitations:

{{/* 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 -}}
{{ 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 }}

Also, I forgot to mention that if the file you want to include contains shortcodes, you have to invoke the include-remote-snippet shortcode with {{< ... >}} instead of {{% ... %}}

@dtzar
Copy link
Author

dtzar commented Nov 10, 2023

That works, thank you! I can live without the table use case for now.👍
This would be nice to have as a default included feature for docsy IMO.

A further enhancement to the include-remote-mdsnippet would be if you could ingest just a named header section of the MD file versus the entire document for fine-grained control of what to embed.

If you want to consider this for being included in Docsy, then perhaps you can keep this issue open. If not, then feel free to close this issue out.

@fekete-robert
Copy link
Collaborator

Glad that it works :)
I can submit it to Docsy, I'll create a PR for it.

I'll think about how to get only a specific section, but honestly I don't see an easy way to do that.

@dtzar
Copy link
Author

dtzar commented Nov 11, 2023 •
edited

Sounds good! I would say something like looking for a specific header code like ## my title until the next ##. I'm sure not an easy piece of code to write if it's possible.

fekete-robert added a commit to fekete-robert/docsy that referenced this issue Nov 14, 2023
@fekete-robert
Adds shortcode to include remote markdown file
91fe87a 
Fixes google#1716
@fekete-robert fekete-robert linked a pull request Nov 14, 2023 that will close this issue
Open
@dtzar dtzar mentioned this issue Dec 1, 2023
Open
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Shortcode for including remote markdown files fekete-robert/docsy
2 participants
@dtzar @fekete-robert