Alexandre Norman 033ddd95c2 Add support for python3 in liquid_tags/b64img.py | 6 年之前 | |
---|---|---|
.. | ||
test_data | 7 年之前 | |
.gitignore | 9 年之前 | |
Readme.md | 7 年之前 | |
__init__.py | 11 年之前 | |
audio.py | 9 年之前 | |
b64img.py | 6 年之前 | |
diag.py | 8 年之前 | |
flickr.py | 9 年之前 | |
generic.py | 7 年之前 | |
giphy.py | 9 年之前 | |
gram.py | 9 年之前 | |
graphviz.py | 8 年之前 | |
img.py | 10 年之前 | |
include_code.py | 8 年之前 | |
liquid_tags.py | 7 年之前 | |
literal.py | 11 年之前 | |
mdx_liquid_tags.py | 9 年之前 | |
notebook.py | 7 年之前 | |
pelicanhtml_1.tpl | 10 年之前 | |
pelicanhtml_2.tpl | 10 年之前 | |
pelicanhtml_3.tpl | 8 年之前 | |
pygalcharts.py | 8 年之前 | |
soundcloud.py | 9 年之前 | |
speakerdeck.py | 8 年之前 | |
spotify.py | 10 年之前 | |
test_audio.py | 9 年之前 | |
test_flickr.py | 9 年之前 | |
test_generation.py | 9 年之前 | |
test_generic.py | 7 年之前 | |
test_giphy.py | 9 年之前 | |
test_notebook.py | 7 年之前 | |
test_soundcloud.py | 9 年之前 | |
tox.ini | 7 年之前 | |
video.py | 8 年之前 | |
vimeo.py | 8 年之前 | |
youtube.py | 8 年之前 |
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.
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"]] %}
b64img
is based on theimg
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:
liquid_tags.b64img
{% 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).
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
.
To insert a Flickr image to a post, follow these steps:
liquid_tags.flickr
Add this to your source document:
{% flickr image_id [small|medium|large] ["alt text"|'alt text'] %}
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 from Giphy. If you just want to try it out, you can use the public beta key contained within the GiphyAPI README file.
To insert a Soundcloud widget in your content, follow these steps:
liquid_tags.soundcloud
Add this to your source document:
{% soundcloud track_url %}
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.
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.
To insert a Speakerdeck viewer into your content, enable the
liquid_tags.speakerdeck
plugin and add the following to your source document:
{% speakerdeck speakerdeck_id %}
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.
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.
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']
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:
EXTRA_HEADER = open('_nb_header.html').read().decode('utf-8')
This will insert the proper CSS formatting into your generated document.
The notebook tag also has two optional arguments: cells
and language
.
{% notebook filename.ipynb cells[2:8] %}
{% notebook filename.ipynb language[julia] %}
This may be helpful for those using IJulia
or notebooks in other languages, especially as the IPython project broadens its
scope to support
other languages. The default language for highlighting
is ipython
.
cells
must come before language
:{% notebook filename.ipynb cells[2:8] language[julia] %}
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.
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'))
To test the plugin in multiple environments we use tox. To run the entire test suite:
cd path/to/liquid_tags
tox