A generator for Pelican allowing flexible referencing of static content

## Project description

A plugin for Pelican that adds automatic resolution of static files.

While the original static generator included in Pelican requires the hardcoding of static paths in the configuration file, pelican-autostatic provides facilities to dinamically add static content independent of its location, just by referencing it.

## 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. ### Core options • output: Allows changing the output path (and the url) of the file in the generated .html. Example: {static /images/example.png output=/images/example_2.png} Will copy content/images/example.png to output/images/example_2.png and the reference will be replaced by$SITEURL/images/example_2.png.

• url: Allows changing the url of the file in the generated .html without changing the output path.

Example:

{static /images/example.png url=/images/example_2.png}

Will copy content/images/example.png to output/images/example.png and the reference will be replaced by \$SITEURL/images/example_2.png.

### Third-party options

• pelican-advthumbnailer adds a thumb option that changes the url of the static image reference so that a thumbnail of that image is generated and linked and not the image itself.

## 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

Available signals

• autostatic_path_found: Signalled when a new autostatic reference is found.

Parameters:

• sender: Always None

• autostatic_path: Object containing:

• source: Read-only property containing source path of reference.

• destination: Read/write property containing destination of referenced file.

• original_destination: Read-only property containing default destination of referenced file.

• url: Read/write property containing url to be substituted for the reference.

• original_url: Read-only property containing default url to be substituted for the reference.

• extra: Dictionary containing the options specified in addition to the path. Can be possibly empty.

pelican-advthumbnailer contains an example usage of this signal.

## Example

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