From bebd2a968ff557c0c22e171b2ad922a81aae4953 Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Sun, 21 Jun 2020 21:58:38 +0200 Subject: [PATCH 1/6] Clarify embed file explanations --- docs/embed-files.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/embed-files.md b/docs/embed-files.md index d50387477..5f56aa771 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') @@ -19,9 +20,9 @@ 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` @@ -29,13 +30,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') From 231eaf7ae501db66afe11dd2d6b0be26fedcd755 Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Sun, 21 Jun 2020 22:30:34 +0200 Subject: [PATCH 2/6] Add Embed a gist section --- docs/embed-files.md | 55 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/embed-files.md b/docs/embed-files.md index 5f56aa771..5413821f3 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -92,3 +92,58 @@ 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. No plugin or app config change is needed - just an element which follows the formatting covered in [Embed files](#embed-files) and uses a raw gist URL. + +Start by viewing a gist on `gist.github.com`. + +For the purposes of the examples below, we assume is this is a valid gist URL. + +- https://gist.github.com/docsify/c2bece08f27c4277001f123898d16a7c + +Identify the following: + +- **Github username** - e.g. `docsify` +- **Gist ID** - e.g. `c2bece08f27c4277001f123898d16a7c` +- **Filename** - choose any valid filename in the gist e.g. `instructions.md` + +Next, you can create the full URL for the file on the `gist.githubusercontent.com` domain. See below for markdown or codeblock approaches. + +### 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') +``` + +Note that the `LABEL` will be the fallback text if the link is broken - so if the filename is there it helps for debugging. + +Using the example case, the element would be: + +```markdown +[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include') +``` + +### Render codeblock from gist + +Embed a gist on your Docsify page as a code block. The format is the same as the previous section except it just has `:type=code` added on in 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 `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 would be: + +```markdown +[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include :type=code') +``` + From 8ef71e31b5dd3f8be8fa610a3bce7a2f52282bfd Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Sun, 21 Jun 2020 22:39:30 +0200 Subject: [PATCH 3/6] Update gist instructions --- docs/embed-files.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/embed-files.md b/docs/embed-files.md index 5413821f3..da9161ef7 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -95,21 +95,31 @@ Embedding any type of source code file, you can specify the highlighted language ## Embed a gist -You can embed a gist as markdown content or as a code block. No plugin or app config change is needed - just an element which follows the formatting covered in [Embed files](#embed-files) and uses a raw gist URL. +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 the examples below, we assume is this is a valid gist URL. +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: +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` -Next, you can create the full URL for the file on the `gist.githubusercontent.com` domain. See below for markdown or codeblock approaches. +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 @@ -121,19 +131,19 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include') ``` -Note that the `LABEL` will be the fallback text if the link is broken - so if the filename is there it helps for debugging. - -Using the example case, the element would be: +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 except it just has `:type=code` added on in the alt text. +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 `code`. +?> 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: @@ -141,9 +151,8 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code') ``` -Using the example case, the element would be: +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') ``` - From ade8c170fdcb5dbeeb6b9b8c6da0a3fbe066dd5e Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Mon, 22 Jun 2020 10:19:34 +0200 Subject: [PATCH 4/6] Fix grammar errors and clarify notes around gists --- docs/embed-files.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/embed-files.md b/docs/embed-files.md index da9161ef7..5b9ba4d78 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -95,15 +95,13 @@ Embedding any type of source code file, you can specify the highlighted language ## 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. +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. 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. +?> **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 gist metadata +### Identify the gist's 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: +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 @@ -113,17 +111,21 @@ Identify the following from the gist: - **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. +Now you have to build the _raw gist URL_ for the target 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. +?> Alternatively, you can get a raw gist URL directly from a gist by clicking the _Raw_ button on a gist file. But if you use that value, 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 -### Render markdown content from 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. -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. +?> This approach works equally well with a gist owned by your account or by someone else. Here is the format: @@ -131,19 +133,19 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include') ``` -Using the example case, the element on your page would be: +Using the example case, the element on your Docsify page would be: ```markdown -[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include') +[gist: 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. +?> The `LABEL` can be any text you want. It acts fallback text if the link is broken - so it is useful to repeat the filename here in case you need to fix the link. -### Render codeblock from gist +### Render a codeblock from a 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. +The format is the same as the previous section, but with `:type=code` added to the alt text at the end. -?> 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`. +?> 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: @@ -151,8 +153,8 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code') ``` -Using the example case, the element on your page would be: +Using the example case, the element on your Docsify page would be: ```markdown -[instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include :type=code') +[gist: instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include :type=code') ``` From 5880e6437ca91c0fe78918f83928f19da56116ba Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Mon, 22 Jun 2020 11:18:11 +0200 Subject: [PATCH 5/6] Add real gist to embed-files.md --- docs/embed-files.md | 52 +++++++++++++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/docs/embed-files.md b/docs/embed-files.md index 5b9ba4d78..43a192d7a 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -18,6 +18,8 @@ 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 extensions are automatically recognized and embedded in different ways. @@ -101,23 +103,28 @@ You can embed a gist as markdown content or as a code block - this is based on t ### Identify the gist's 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: +Start by viewing a gist on `gist.github.com`. For the purposes of this guide, we use this gist: -- https://gist.github.com/docsify/c2bece08f27c4277001f123898d16a7c +- https://gist.github.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15 -Identify the following from the gist: +Identify the following items 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` +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. -Now you have to build the _raw gist URL_ for the target file on the `gist.githubusercontent.com` domain. +You will need those to build the _raw gist URL_ for the target file. This has the following format: -For example: +- https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME + +Here are two examples based on the sample gist: -- https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md +- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md +- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js -?> Alternatively, you can get a raw gist URL directly from a gist by clicking the _Raw_ button on a gist file. But if you use that value, 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. +?> Alternatively, you can get a raw URL directly from a gist by clicking the _Raw_ button next to 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. @@ -125,7 +132,7 @@ Continue with one of the sections below to embed the gist on a Docsify page. 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 someone else. +?> This approach works equally well with a gist owned by your account or by another user. Here is the format: @@ -133,19 +140,23 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include') ``` -Using the example case, the element on your Docsify page would be: +?> 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. + +For example: ```markdown -[gist: instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include') +[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include') ``` -?> The `LABEL` can be any text you want. It acts fallback text if the link is broken - so it is useful to repeat the filename here in case you need to fix the link. +Which renders as: + +[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include') ### Render a codeblock from a gist -The format is the same as the previous section, but with `:type=code` added to the alt text at the end. +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`. +?> 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: @@ -153,8 +164,13 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code') ``` -Using the example case, the element on your Docsify page would be: +For example: ```markdown -[gist: instructions.md](https://gist.githubusercontent.com/docsify/c2bece08f27c4277001f123898d16a7c/raw/instructions.md ':include :type=code') +[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') + From d3a049d7261b91b934fb3f17126847f65e15d2b9 Mon Sep 17 00:00:00 2001 From: michaelcurrin Date: Mon, 22 Jun 2020 11:25:37 +0200 Subject: [PATCH 6/6] Clean up embed-files.md --- docs/embed-files.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/embed-files.md b/docs/embed-files.md index 43a192d7a..d1a447338 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -117,22 +117,20 @@ Field | Example | Description 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 +- `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 from a gist by clicking the _Raw_ button next to 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. +?> 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. +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: @@ -140,8 +138,6 @@ Here is the format: [LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':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. - For example: ```markdown @@ -152,11 +148,11 @@ Which renders as: [gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include') -### Render a codeblock from a gist +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. -The format is the same as the previous section, but with `:type=code` added to the alt text. +### Render a codeblock from a gist -?> 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`. +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: @@ -173,4 +169,3 @@ For example: Which renders as: [gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code') -