• View
• Edit
• History
• Attach
• Print
• Backlinks

GistEmbed

Description

This recipe lets you embed Gists in a wikipage.

Git repository for this recipe: https://git.sr.ht/~achmizs/pmwiki-gist-embed.git.

Installation

1. Download and unzip gist-embed.zipΔ
2. Place the file gist-embed.php and the simplehtmldom/ folder into your cookbook/ directory
3. Add such a line to config.php:

 include_once("$FarmD/cookbook/gist-embed.php");

Usage

The basic usage is simple:

(:gist-embed gist-id:)

(For example, (:gist-embed achmizs/0c1b9a3a8c2d3c5e725624392e6da461:).)

There are several optional arguments (which must go after the gist id):

file1,file2,…

If the specified gist is a multi-file gist, then by default, all files will be shown. To show only some of the files, provide a comma-separated list of file names in the (:gist-embed:) markup. This option must come first in the options list! (In other words, it must be placed immediately after the gist-embed username/gistid part, before any of the other options listed below.)

no-js

Do not embed a script which makes the browser retrieve the gist; instead, retrieve the gist server-side, and insert it into the page that’s served to the browser.

Does not apply when the raw argument is used.

nofooter

Don’t show the footer.

Does not apply when the raw argument is used.

nolinenums

Hide the line numbers.

Does not apply when the raw argument is used.

raw

Don’t display syntax coloring, line numbers, footer, etc.; just show the raw text of the gist.

no-pre

Don’t wrap the raw text in a <pre> tag and don’t encode HTML entities (useful if, for example, the text is going to be processed by some other markup, such as PmPygment or MarkdownMarkupExtension).

lines=comma-separated list of lines or line ranges

Show only specified lines/ranges. The lines= parameter takes three kinds of arguments:

1. Single line (e.g., lines=2)
   (This will include the specified line.)
2. Line range with a start and end line (e.g., lines=5-7)
   (This will include all lines from the start to the end of the range, inclusive.)
3. Line range with a start line only (e.g., lines=10-)
   (This will include all lines from the start of the range to the end of the file.)

The three kinds of arguments may be combined freely. For example:

(:gist-embed inanimatt/879259 lines=2,5-7,11,15- :)

This will show lines 2, 5, 6, 7, 11, and line 15 onward.

Note that the lines= parameter works only if only one file is being shown (see Notes, below).

hl=comma-separated list of lines or line ranges

Highlight the specified lines/ranges. The hl= parameter takes exactly the same sort of arguments as the lines= parameter (see above).

$GistEmbedHighlightStyle = "background-color: fuchsia; font-weight: bold;";

Note that the hl= parameter works only if only one file is being shown (see Notes, below).

Notes

The no-js, nofooter, and nolinenums options may be used together, in any combination (for example, (:gist-embed achmizs/0c1b9a3a8c2d3c5e725624392e6da461 nofooter nolinenums:)).

The raw option makes the above three options moot. The no-pre option applies only if raw is also specified.

The no-js option may be used for browsers which do not support Javascript (or for users who have Javascript disabled). However, it will result in slightly slower initial page loads (because the default Javascript method loads the gist asynchronously, after the page has already loaded, whereas with no-js, the gist must be retrieved before the wikipage may be fully rendered). (The same is true of the raw option.)

The lines= and hl= options may be used in combination with any other option, but only work if only one file is being displayed (either because the gist only contains one file, or because one particular file has been specified, from a multi-file gist.

Notes

This recipe uses the PHP Simple HTML DOM Parser by S. C. Chen.

Change log / Release notes

• 2021-12-11: Fixed bugs; updated simplehtmldom version.
• 2018-10-19: Bug fix.
• 2017-12-27: Line highlighting added.
• 2017-12-25-2: Bug fix.
• 2017-12-25: Initial release.

See also

The Gists recipe also allows embedding of gists, but does not currently work (due to being outdated).

Contributors

• Said Achmiz (author)

Comments

See discussion at GistEmbed-Talk