docsify/docs/embed-files.md

Embed files

With docsify 4.6 it is now possible to embed any type of file.

You can embed these files as video, audio, iframes, or code blocks, and even Markdown files can even be embedded directly into the document.

For example, here is an embedded Markdown file. You only need to do this:

[filename](_media/example.md ':include')

Then the content of example.md will be displayed directly here:

filename

You can check the original content for example.md.

Normally, this will be compiled into a link, but in docsify, if you add :include it will be embedded. You can use single or double quotation marks around as you like.

External links can be used too - just replace the target. If you want to use a gist URL, see Embed a gist section.

Embedded file type

Currently, file extensions are automatically recognized and embedded in different ways.

These types are supported:

• iframe .html, .htm
• markdown .markdown, .md
• audio .mp3
• video .mp4, .ogg
• code other file extension

Of course, you can force the specified type. For example, a Markdown file can be embedded as a code block by setting :type=code.

[filename](_media/example.md ':include :type=code')

You will get:

filename

Markdown with YAML Front Matter

When using Markdown, YAML front matter will be stripped from the rendered content. The attributes cannot be used in this case.

[filename](_media/example-with-yaml.md ':include')

You will get just the content

filename

Embedded code fragments

Sometimes you don't want to embed a whole file. Maybe because you need just a few lines but you want to compile and test the file in CI.

[filename](_media/example.js ':include :type=code :fragment=demo')

In your code file you need to surround the fragment between /// [demo] lines (before and after the fragment). Alternatively you can use ### [demo].

Example:

filename

Tag attribute

If you embed the file as iframe, audio and video, then you may need to set the attributes of these tags.

?> Note, for the audio and video types, docsify adds the controls attribute by default. When you want add more attributes, the controls attribute need to be added manually if need be.

[filename](_media/example.mp4 ':include :type=video controls width=100%')

[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')

cinwell website

Did you see it? You only need to write directly. You can check MDN for these attributes.

The code block highlight

Embedding any type of source code file, you can specify the highlighted language or automatically identify.

[](_media/example.html ':include :type=code text')

⬇️

?> How to set highlight? You can see here.

Embed a gist

You can embed a gist as markdown content or as a code block - this is based on the approach at the start of Embed Files section, but uses a raw gist URL as the target.

?> No plugin or app config change is needed here to make this work. In fact, the "Embed" script tag that is copied from a gist will not load even if you make plugin or config changes to allow an external script.

Identify the gist's metadata

Start by viewing a gist on gist.github.com. For the purposes of this guide, we use this gist:

• https://gist.github.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15

Identify the following items from the gist:

Field	Example	Description
Username	anikethsaha	The gist's owner.
Gist ID	c2bece08f27c4277001f123898d16a7c	Identifier for the gist. This is fixed for the gist's lifetime.
Filename	content.md	Select a name of a file in the gist. This needed even on a single-file gist for embedding to work.

You will need those to build the raw gist URL for the target file. This has the following format:

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

Here are two examples based on the sample gist:

• https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md
• https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js

?> Alternatively, you can get a raw URL directly clicking the Raw button on a gist file. But, if you use that approach, just be sure to remove the revision number between raw/ and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will not show the latest content when the gist is updated.

Continue with one of the sections below to embed the gist on a Docsify page.

Render markdown content from a gist

This is a great way to embed content seamlessly in your docs, without sending someone to an external link. This approach is well-suited to reusing a gist of say installation instructions across doc sites of multiple repos. This approach works equally well with a gist owned by your account or by another user.

Here is the format:

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

For example:

[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include')

Which renders as:

gist: content.md

The LABEL can be any text you want. It acts as a fallback message if the link is broken - so it is useful to repeat the filename here in case you need to fix a broken link. It also makes an embedded element easy to read at a glance.

Render a codeblock from a gist

The format is the same as the previous section, but with :type=code added to the alt text. As with the Embedded file type section, the syntax highlighting will be inferred from the extension (e.g. .js or .py), so you can leave the type set as code.

Here is the format:

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

For example:

[gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code')

Which renders as:

gist: script.js