Install

To install the library, you can use pip

$ pip install pelican-autostatic

Usage

1. Update pelicanconf.py:

   1. Add autostatic to PLUGINS.

      You should add it before any metadata-affecting plugins.

      PLUGINS = ['autostatic', ...]

2. Reference static content in your Markdown/rST metadata/text by using the {static} substitution:

   {static url/to/content key1=val1 key2="val 2" ...}

   or:

   {static "url/to/content/with spaces" key1=val1 key2="val 2" ...}

   Example (in markdown):

   [Markdown example file]({static file/example.zip key1=val1 key2="val 2" ...})

   You can also use | instead of spaces if you wish (for use with Markdown inline image syntax which doesn’t accept spaces for the url for instance):

   ![Markdown example image]({static|file/example.png|key1=val1} "Image title")

3. An index of these references will be automatically built and those files will be copied to the output folder preserving the path structure:

   • If using a relative path, the file will be copied to the same path relative to the directory where the .html file is output.

   • If using an absolute path, the file is copied to that same path relative to the base output folder (e.g: output).

Options

Autostatic references can have a number of options after the url for the content. This allows modifications to the content being referenced.

Configuration

You can set the following options in your pelicanconf.py:

• AUTOSTATIC_REFERENCE_PATTERN (String) - Change the regex of the static reference pattern. It needs to have the following groups:

  • path - This should have the path used in the reference.

  • extra - This should have the key1=val1 key2="val 2" ... string.

  For reference, the default pattern is:

  r"""{static(?:\s+|\|)((?:"|')?)(?P<path>[^\1=]+?)\1(?:(?:\s+|\|)(?P<extra>.*))?\s*}"""

• AUTOSTATIC_USE_PELICANLIKE_REF (Boolean) - Activate the usage of a different format of the static reference that is similar to Pelican’s {filename} syntax:

  ![Markdown example image]({static|key1=val1}images/example.png "Image title")

  NOTE: I haven’t actually benchmarked this but this mechanism (the same used by Pelican with {filename}) should be slightly slower than the default one used in this plugin. This is because the {filename} mechanism does matching over all html tags which will surely result in a lot of backtracks on a HTML document.

Extending

Example

For a working example check my site and my site’s source code.