255 lines
9.8 KiB
Markdown
255 lines
9.8 KiB
Markdown
|
# Liquid-style Tags
|
|||
|
*Author: Jake Vanderplas <jakevdp@cs.washington.edu>*
|
|||
|
|
|||
|
This plugin allows liquid-style tags to be inserted into Markdown within
|
|||
|
Pelican documents via tags bounded by `{% ... %}`, a convention also used
|
|||
|
to extend Markdown in other publishing platforms such as Octopress.
|
|||
|
|
|||
|
This set of extensions does not actually interface with liquid, but allows
|
|||
|
users to define their own liquid-style tags which will be inserted into
|
|||
|
the Markdown preprocessor stream. There are several built-in tags, which
|
|||
|
can be added as follows.
|
|||
|
|
|||
|
First, in your pelicanconf.py file, add the plugins you want to use:
|
|||
|
|
|||
|
PLUGIN_PATH = '/path/to/pelican-plugins'
|
|||
|
PLUGINS = ['liquid_tags.img', 'liquid_tags.video',
|
|||
|
'liquid_tags.youtube', 'liquid_tags.vimeo',
|
|||
|
'liquid_tags.include_code', 'liquid_tags.notebook']
|
|||
|
|
|||
|
Following below is more information about these and other tags.
|
|||
|
|
|||
|
## Image Tag
|
|||
|
To insert a sized and labeled image in your document, enable the
|
|||
|
`liquid_tags.img` plugin and use the following:
|
|||
|
|
|||
|
{% img [class name(s)] path/to/image [width [height]] [title text | "title text" ["alt text"]] %}
|
|||
|
|
|||
|
### Base64 Image (inline image) tag
|
|||
|
|
|||
|
`b64img` is based on the`img` tag, but instead of inserting a link to the image it encodes it as base64 text and inserts it into a`<img src=` attribute.
|
|||
|
|
|||
|
To use it:
|
|||
|
|
|||
|
1. Enable `liquid_tags.b64img`
|
|||
|
1. Insert a tag as follows: `{% b64img [class name(s)] path/to/image [width [height]] [title text | "title text" ["alt text"]] %}`
|
|||
|
|
|||
|
Images are encoded at generation time, so you can use any local path (just be sure that the image will remain in the same location for subsequent site generations).
|
|||
|
|
|||
|
## Instagram Tag
|
|||
|
To insert a sized and labeled Instagram image in your document by its shortcode (such as `pFI0CAIZna`), enable the `liquid_tags.gram` plugin and use the following:
|
|||
|
|
|||
|
{% gram shortcode [size] [width] [class name(s)] [title text | "title text" ["alt text"]] %}
|
|||
|
|
|||
|
You can specify a size with `t`, `m`, or `l`.
|
|||
|
|
|||
|
## Flickr Tag
|
|||
|
To insert a Flickr image to a post, follow these steps:
|
|||
|
|
|||
|
1. Enable `liquid_tags.flickr`
|
|||
|
2. [Get an API key from Flickr](https://www.flickr.com/services/apps/create/apply)
|
|||
|
3. Add FLICKR_API_KEY to your settings file
|
|||
|
4. Add this to your source document:
|
|||
|
|
|||
|
{% flickr image_id [small|medium|large] ["alt text"|'alt text'] %}
|
|||
|
|
|||
|
## Giphy Tag
|
|||
|
To insert a GIF from Giphy in your document by its ID (such as `aMSJFS6oFX0fC`), enable the `liquid_tags.giphy` plugin and use the following:
|
|||
|
|
|||
|
{% giphy gif_id ["alt text"|'alt text'] %}
|
|||
|
|
|||
|
**Important:** You must [request a production API key](https://api.giphy.com/submit) from Giphy.
|
|||
|
If you just want to try it out, you can use the public beta key contained within the [GiphyAPI](https://github.com/giphy/GiphyAPI) README file.
|
|||
|
|
|||
|
## Soundcloud Tag
|
|||
|
To insert a Soundcloud widget in your content, follow these steps:
|
|||
|
|
|||
|
1. Enable `liquid_tags.soundcloud`
|
|||
|
2. Add this to your source document:
|
|||
|
|
|||
|
{% soundcloud track_url %}
|
|||
|
|
|||
|
## YouTube Tag
|
|||
|
To insert a YouTube video into your content, enable the
|
|||
|
`liquid_tags.youtube` plugin and add the following to your source document:
|
|||
|
|
|||
|
{% youtube youtube_id [width] [height] %}
|
|||
|
|
|||
|
The width and height are in pixels and are optional. If they
|
|||
|
are not specified, then the dimensions will be 640 (wide) by 390 (tall).
|
|||
|
|
|||
|
If you experience issues with code generation (e.g., missing closing tags),
|
|||
|
add `SUMMARY_MAX_LENGTH = None` to your settings file.
|
|||
|
|
|||
|
## Vimeo Tag
|
|||
|
To insert a Vimeo video into your content, enable the `liquid_tags.vimeo`
|
|||
|
plugin and add the following to your source document:
|
|||
|
|
|||
|
{% vimeo vimeo_id [width] [height] %}
|
|||
|
|
|||
|
The width and height are in pixels and are optional. If they
|
|||
|
are not specified, then the dimensions will be 640 (wide) by 390 (tall).
|
|||
|
|
|||
|
If you experience issues with code generation (e.g., missing closing tags),
|
|||
|
add `SUMMARY_MAX_LENGTH = None` to your settings file.
|
|||
|
|
|||
|
## Speakerdeck Tag
|
|||
|
|
|||
|
To insert a Speakerdeck viewer into your content, follow these steps:
|
|||
|
|
|||
|
1. Enable the `liquid_tags.soundcloud` plugin
|
|||
|
2. Add the following to your source document:
|
|||
|
|
|||
|
```html
|
|||
|
{% speakerdeck speakerdeck_id [ratio] %}
|
|||
|
```
|
|||
|
|
|||
|
### Note
|
|||
|
|
|||
|
- The ratio is a decimal number and is optional.
|
|||
|
- Ratio accept decimal number and digit after decimal is optional.
|
|||
|
- If ratio is not specified, then it will be `1.33333333333333` (4/3).
|
|||
|
- An example value for the ration can be `1.77777777777777` (16/9).
|
|||
|
|
|||
|
## Video Tag
|
|||
|
To insert HTML5-friendly video into your content, enable the `liquid_tags.video`
|
|||
|
plugin and add the following to your source document:
|
|||
|
|
|||
|
{% video /url/to/video.mp4 [width] [height] [/path/to/poster.png] %}
|
|||
|
|
|||
|
The width and height are in pixels and are optional. If they are not specified,
|
|||
|
then the native video size will be used. The poster image is a preview image
|
|||
|
that is shown prior to initiating video playback.
|
|||
|
|
|||
|
To link to a video file, make sure it is in a static directory, transmitted
|
|||
|
to your server, and available at the specified URL.
|
|||
|
|
|||
|
## Audio Tag
|
|||
|
To insert HTML5 audio into a post, enable the `liquid_tags.audio` plugin
|
|||
|
and add the following to your source document:
|
|||
|
|
|||
|
{% audio url/to/audio [url/to/audio] [url/to/audio] %}
|
|||
|
|
|||
|
This tag supports up to three audio URL arguments so you can add different
|
|||
|
audio file versions, as different browsers support different file formats.
|
|||
|
|
|||
|
To link to a audio file, make sure it is in a static directory, transmitted
|
|||
|
to your server, and available at the specified URL.
|
|||
|
|
|||
|
## Include Code
|
|||
|
To include code from a file in your document with a link to the original
|
|||
|
file, enable the `liquid_tags.include_code` plugin, and add the following to
|
|||
|
your source document:
|
|||
|
|
|||
|
{% include_code /path/to/code.py [lang:python] [lines:X-Y] [:hidefilename:] [title] %}
|
|||
|
|
|||
|
All arguments are optional but must be specified in the order shown above.
|
|||
|
If using `:hidefilename:`, a title must be provided as indicated above.
|
|||
|
|
|||
|
{% include_code /path/to/code.py lines:1-10 :hidefilename: Test Example %}
|
|||
|
|
|||
|
This example will show the first ten lines of the file while hiding the actual
|
|||
|
filename.
|
|||
|
|
|||
|
The script must be in the `code` subdirectory of your content folder;
|
|||
|
the default location can be changed by specifying the directory in your
|
|||
|
settings file thusly:
|
|||
|
|
|||
|
CODE_DIR = 'code'
|
|||
|
|
|||
|
Additionally, in order for the resulting hyperlink to work, this directory must
|
|||
|
be listed in the STATIC_PATHS setting. For example:
|
|||
|
|
|||
|
STATIC_PATHS = ['images', 'code']
|
|||
|
|
|||
|
## IPython notebooks
|
|||
|
|
|||
|
To insert an [IPython][] notebook into your post, enable the
|
|||
|
``liquid_tags.notebook`` plugin and add the following to your source document:
|
|||
|
|
|||
|
{% notebook filename.ipynb %}
|
|||
|
|
|||
|
The file should be specified relative to the `notebooks` subdirectory of the
|
|||
|
content directory. Optionally, this subdirectory can be specified in your
|
|||
|
settings file:
|
|||
|
|
|||
|
NOTEBOOK_DIR = 'notebooks'
|
|||
|
|
|||
|
Because the conversion and rendering of notebooks is rather involved, there
|
|||
|
are a few extra steps required for this plugin. First, you must install IPython:
|
|||
|
|
|||
|
pip install ipython==2.4.1
|
|||
|
|
|||
|
After running Pelican on content containing an IPython notebook tag, a file
|
|||
|
called `_nb_header.html` will be generated in the main directory. The content
|
|||
|
of this file should be included in the header of your theme. An easy way to
|
|||
|
accomplish this is to add the following to your theme’s header template…
|
|||
|
|
|||
|
{% if EXTRA_HEADER %}
|
|||
|
{{ EXTRA_HEADER }}
|
|||
|
{% endif %}
|
|||
|
|
|||
|
… and in your settings file, include the line:
|
|||
|
|
|||
|
from io import open
|
|||
|
EXTRA_HEADER = open('_nb_header.html', encoding='utf-8').read()
|
|||
|
|
|||
|
This will insert the proper CSS formatting into your generated document.
|
|||
|
|
|||
|
### Optional Arguments for Notebook Tags
|
|||
|
|
|||
|
The notebook tag also has two optional arguments: `cells` and `language`.
|
|||
|
|
|||
|
- You can specify a slice of cells to include:
|
|||
|
|
|||
|
`{% notebook filename.ipynb cells[2:8] %}`
|
|||
|
|
|||
|
- You can also specify the name of the language that Pygments should use for
|
|||
|
highlighting code cells. For a list of the language short names that Pygments
|
|||
|
can highlight, refer to the [Pygments lexer list](http://www.pygments.org/docs/lexers/).
|
|||
|
|
|||
|
`{% notebook filename.ipynb language[julia] %}`
|
|||
|
|
|||
|
This may be helpful for those using [IJulia](https://github.com/JuliaLang/IJulia.jl)
|
|||
|
or notebooks in other languages, especially as the IPython project [broadens its
|
|||
|
scope](https://github.com/ipython/ipython/wiki/Roadmap:-IPython) to [support
|
|||
|
other languages](http://jupyter.org/). The default language for highlighting
|
|||
|
is `ipython`.
|
|||
|
|
|||
|
- These options can be used separately, together, or not at all. However,
|
|||
|
if both tags are used then `cells` must come before `language`:
|
|||
|
|
|||
|
`{% notebook filename.ipynb cells[2:8] language[julia] %}`
|
|||
|
|
|||
|
### Collapsible Code in IPython Notebooks
|
|||
|
|
|||
|
The IPython plugin also enables collapsible code input boxes. For this to work
|
|||
|
you must first copy the file `pelicanhtml_3.tpl` (for IPython 3.x) or
|
|||
|
`pelicanhtml_2.tpl` (for IPython 2.x) to the top level of your content
|
|||
|
directory. Notebook input cells containing the comment line `#
|
|||
|
<!-- collapse=True -->` will be collapsed when the HTML page is
|
|||
|
loaded and can be expanded by tapping on them. Cells containing the
|
|||
|
comment line `# <!-- collapse=False -->` will be expanded on load but
|
|||
|
can be collapsed by tapping on their header. Cells without collapsed
|
|||
|
comments are rendered as standard code input cells.
|
|||
|
|
|||
|
## Configuration settings in custom tags
|
|||
|
|
|||
|
Tags do not have access to the full Pelicans settings, and instead arrange for
|
|||
|
the variables to be passed to the tag. For tag authors who plan to add their
|
|||
|
tag as in-tree tags, they can just add the variables they need to an array in
|
|||
|
`mdx_liquid_tags.py`, but out-of-tree tags can specify which variables they
|
|||
|
need by including a tuple of (variable, default value, helptext) in the
|
|||
|
user's `pelicanconf.py` settings:
|
|||
|
|
|||
|
LIQUID_CONFIGS = (('PATH', '.', "The default path"), ('SITENAME', 'Default Sitename', 'The name of the site'))
|
|||
|
|
|||
|
## Testing
|
|||
|
|
|||
|
To test the plugin in multiple environments we use [tox](http://tox.readthedocs.org/en/latest/). To run the entire test suite:
|
|||
|
|
|||
|
cd path/to/liquid_tags
|
|||
|
tox
|
|||
|
|
|||
|
[IPython]: http://ipython.org/
|