Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pelican-plugins/liquid-tags

Pelican plugin that supports Liquid-style tags in Markdown
https://github.com/pelican-plugins/liquid-tags

liquid-tags markdown pelican

Last synced: 3 months ago
JSON representation

Pelican plugin that supports Liquid-style tags in Markdown

Awesome Lists containing this project

README 

        
# Liquid Tags



[![Build Status](https://img.shields.io/github/actions/workflow/status/pelican-plugins/liquid-tags/main.yml?branch=main)](https://github.com/pelican-plugins/liquid-tags/actions)

[![PyPI Version](https://img.shields.io/pypi/v/pelican-liquid-tags)](https://pypi.org/project/pelican-liquid-tags/)

![License](https://img.shields.io/pypi/l/pelican-liquid-tags?color=blue)



This Pelican 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 pre-processor stream. There are several built-in tags, which

can be added as follows below.



## Installation



This plugin can be installed via:



    python -m pip install pelican-liquid-tags



For more detailed plugin installation instructions, please refer to the

[Pelican Plugin Documentation](https://docs.getpelican.com/en/latest/plugins.html).



## Configuration



While this plugin does provide an extensive set of built-in tags (see below),

none of them is imported and made available by default. In order to use specific

tags in your post, you need to explicitly enable them in your settings file:



    LIQUID_TAGS = ["img", "literal", "video", "youtube",

                   "vimeo", "include_code"]



### Configuration Settings in Custom Tags



Tags do not have access to the full set of Pelican settings, and instead arrange

for the variables to be passed to the tag. Tag authors who plan to add their

tag as an in-tree tag can just add the variables they need to an array in

`mdx_liquid_tags.py`. Out-of-tree tag authors can specify which variables they

need by including a tuple of (variable, default value, helptext) via the

appropriate Pelican setting:



    LIQUID_CONFIGS = (('PATH', '.', "The default path"), ('SITENAME', 'Default Sitename', 'The name of the site'))



## Tags in this Plugin



### Image Tag



To insert a sized and labeled image in your document, enable the

`img` tag and use the following:



    {% img [class name(s)] path/to/image [lazy | eager] [width [height]] [title text | "title text" ["alt text"]] %}



The configuration variable `IMG_DEFAULT_LOADING` can change the default beahavior

of the plugin. `lazy` setting takes precendence over the default `eager`.

If `lazy` is set, all the images will receive the attribute. This is not the case

with `eager` because it's the default behavior of browsers when faced with an image.

Explicit parameters specified in liquid-tags `img` will always take precedence

and will always be translated into attributes.



### 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 an `` will be collapsed when the HTML page is

loaded and can be expanded by tapping on them. Cells containing the

comment line `# ` 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.



## Compatibility with [Jinja2Content plugin](https://github.com/pelican-plugins/jinja2content)



Jinja2Content plugin allows you to use Jinja2 directives inside your Pelican

articles and pages. You may encounter issues when using both Liquid Tags and

Jinja2Content, because Liquid Tag's `{% tag %}` syntax is also valid Jinja2

template syntax.



Jinja2Content will process file first, and only rendered content is then

processed by Liquid Tags. To ensure seamless operation of Liquid Tags, make

sure that `{% tag %}` syntax appears **after** file is rendered by Jinja2.

This can be achieved with [Jinja2 escaping](https://jinja.palletsprojects.com/en/latest/templates/#escaping):



     {% raw %}{% my_liquid_tag arguments %}{% endraw %}



     {{ '{%' }} my_liquid_tag arguments {{ '%}' }}



## Testing



To run the plugin test suite, [set up your development environment][] and run:



    cd path/to/liquid_tags

    invoke tests



To test the plugin in multiple environments, install and use [Tox](https://tox.readthedocs.io/en/latest/):



    tox



## Contributing



Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].



To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.



## Gratitude



Thanks to [Jake Vanderplas](https://github.com/jakevdp) for creating this plugin, which has subsequently been enhanced by [dozens of contributors](https://github.com/pelican-plugins/liquid-tags/graphs/contributors).



[IPython]: http://ipython.org/

[set up your development environment]: https://docs.getpelican.com/en/latest/contribute.html#setting-up-the-development-environment

[existing issues]: https://github.com/pelican-plugins/liquid-tags/issues

[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html