diff --git a/docs/embed-files.md b/docs/embed-files.md index d50387477..d1a447338 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -1,15 +1,16 @@ # 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 embedded a Markdown file. You only need to do this: +For example, here is an embedded Markdown file. You only need to do this: ```markdown [filename](_media/example.md ':include') ``` -Then the content of `example.md` will be displayed directly here +Then the content of `example.md` will be displayed directly here; [filename](_media/example.md ':include') @@ -17,11 +18,13 @@ You can check the original content for [example.md](_media/example.md ':ignore') Normally, this will compiled into a link, but in docsify, if you add `:include` it will be embedded. +External links can be used too - just replace the target. If you want to use a gist URL, see [Embed a gist](#embed-a-gist) section. + ## Embedded file type -Currently, file extension are automatically recognized and embedded in different ways. +Currently, file extensions are automatically recognized and embedded in different ways. -This is a supported embedding type: +These types are supported: * **iframe** `.html`, `.htm` * **markdown** `.markdown`, `.md` @@ -29,13 +32,13 @@ This is a supported embedding type: * **video** `.mp4`, `.ogg` * **code** other file extension -Of course, you can force the specified. For example, you want to Markdown file as code block embedded. +Of course, you can force the specified type. For example, a Markdown file can be embedded as a code block by setting `:type=code`. ```markdown [filename](_media/example.md ':include :type=code') ``` -You will get it +You will get: [filename](_media/example.md ':include :type=code') @@ -91,3 +94,78 @@ Embedding any type of source code file, you can specify the highlighted language [](_media/example.html ':include :type=code text') ?> How to set highlight? You can see [here](language-highlight.md). + +## 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](#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: + +```markdown +[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include') +``` + +For example: + +```markdown +[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include') +``` + +Which renders as: + +[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include') + +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](#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: + +```markdown +[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code') +``` + +For example: + +```markdown +[gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code') +``` + +Which renders as: + +[gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code')