fix #932 - Add embed gist instructions to Embed Files

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')
 
@@ -19,23 +20,23 @@ Normally, this will compiled into a link, but in docsify, if you add `:include`
 
 ## 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`
 * **audio** `.mp3`
 * **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 +92,67 @@ 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 in the [Embed files](#embed-files) but uses raw gist URL as the target.
+
+?> No plugin or app config change is needed here. In fact, an "Embed" script tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow the external script.
+
+### Identify gist metadata
+
+Start by viewing a gist on `gist.github.com`. 
+
+For the purposes of this guide, we assume that is this is a valid gist URL:
+
+- https://gist.github.com/docsify/c2bece08f27c4277001f123898d16a7c
+
+Identify the following from the gist:
+
+- **Github username** - e.g. `docsify`
+- **Gist ID** - e.g. `c2bece08f27c4277001f123898d16a7c`
+- **Filename** - choose any valid filename in the gist e.g. `instructions.md`
+
+Now you can create the _raw gist URL_ for the file on the `gist.githubusercontent.com` domain.
+
+For example:
+
+- https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md 
+
+Continue with one of the the sections below to actually embed the gist on a Docsify page.
+
+### Render markdown content from gist
+
+Embed markdown content on your Docsify page. This is a great way to embed content seemlessly without an external link, whether the gist was created by yourself or another account. 
+
+Here is the format:
+
+```markdown
+[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include')
+```
+
+Using the example case, the element on your page would be:
+
+```markdown
+[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include')
+```
+
+?> The the `LABEL` will be the fallback text if the link is broken, so it is useful to repeat the filename in the label.
+
+### Render codeblock from gist
+
+Embed a gist on your Docsify page as a code block. 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 as the generic value of `code`.
+
+Here is the format:
+
+```markdown
+[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code')
+```
+
+Using the example case, the element on your page would be:
+
+```markdown
+[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include :type=code')
+```