Docsify - embed a gist that stays update to date

docsify-embed-gist.md

Docsify - embed a gist that stays update to date

To learn more about how to use Docsify to make a light Markdown-based docs site, see:

• https://michaelcurrin.github.io/docsify-js-tutorial/#/

TL;DR

Approach

• Use Docsify embed syntax - a markdown link with ':include' added.
• Use the raw gist URL.
• Specify the filename of the file in the gist.
• Remove the revision number from the URL, so you always have the latest version.

Syntax

• Display code snippet as codeblock (e.g. main.js)

  [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code')

• Render markdown (e.g. index.md)

  [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include')

Replace the variables which are indicated in all capital letters. The label text is useful so that text can be shown if the link is broken.

A standard gist URL

Without embedding, this is what a gist URL looks like when viewing on Github:

https://gist.github.com/USERNAME/GIST_ID/

e.g. This gist is here:

https://gist.github.com/MichaelCurrin/c2bece08f27c4277001f123898d16a7c/

Gist embedded with a script tag

The standard way of embedding.

<script src="https://gist.github.com/USERNAME/GIST_ID.js"></script>

e.g.

<script src="https://gist.github.com/MichaelCurrin/c2bece08f27c4277001f123898d16a7c.js"></script>

This does not work in DocsifyJS when I tested, even adjusting the protocol. As Docsify does not allow arbitrary script execution.

You can enable that with the executeScript option, though that may not work for gists specifically based on this Docsify issue #982.

Docsify embedding

Here is the way to a local path or external URL on Docsify. Note the use of the Markdown alt text attribute in quotes, which Docsify makes useful of specifying its own rules.

Local:

[Label text](/path/to/hello.js ":include")

External:

[Label text](http://example.com/path/to/hello.js ":include")

[Label text](https://raw.githubusercontent.com/UserName/repo-name/main/hello.js ":include")

See Embed Files in the docs for more info.

Raw URL

With the revision number included, the content is fixed:

• https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/REVISION_ID/FILENAME

If the revision number is left out, the reference will point to the latest content.

• https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME

Note that the content can be cached in your browser, so open the URL in your browser directly and hard refresh, then open the page which embeds it and refresh that. Doing only the latter even with "Disable cache" in DevTools was not sufficient.

Applying to Docsify

The raw URL for a file in a gist. This includes the gist ID and a revision number, so will not auto update.

• https://gist.githubusercontent.com/MichaelCurrin/c2bece08f27c4277001f123898d16a7c/raw/2fb7607de66d7fb0f2b9873cb85ab9049e96db09/docsify_embed_gist.md

As an experiment this actually worked without revision.

• https://gist.githubusercontent.com/MichaelCurrin/c2bece08f27c4277001f123898d16a7c/raw/docsify_embed_gist.md

How to embed in DocsifyJS in markdown. Use the URL above and the embed syntax.

[run_docsify_locally.md](https://gist.githubusercontent.com/MichaelCurrin/c2bece08f27c4277001f123898d16a7c/raw/docsify_embed_gist.md ':include')

Note that the https protocol works even running a local server on HTTP.

How many files in a gist

This will get the first file in a gist. However, this will not give syntax highlighting in DocsifyS.

• https://gist.github.com/USERNAME/GIST_ID/raw/

Get a specific file in a multi-file gist. Docsify will use appropriate syntax highighting based on the extension of the file.

• https://gist.github.com/USERNAME/GIST_ID/raw/FILENAME

Note that in order to get syntax highlighting, you also have to load language specific highlighting. e.g. For Python:

<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-python.min.js"></script>

Credit

This gist guide was inspired by this gist.