pelican-random-article

pelican-random-article is a Pelican plugin that automatically generates a /random page.
Visiting /random instantly redirects the reader to a randomly chosen article — just like wiwi.blog/random.

Features

• Generates a static random/index.html page at build time.
• Picks a random article client-side using JavaScript — no server required.
• Works with any Pelican theme; no template changes needed.
• Configurable output path via pelicanconf.py.

Installation

pip install pelican-random-article

Or with uv:

uv add pelican-random-article

Usage

1. Enable the plugin in pelicanconf.py

PLUGINS = [
    # ... your other plugins ...
    "pelican.plugins.random_article",
]

2. (Optional) Add a link in your navigation

Point any link to /random (or wherever RANDOM_ARTICLE_SAVE_AS points):

<a href="{{ SITEURL }}/random/">Random</a>

3. Build your site

pelican content

The plugin will write output/random/index.html automatically.

Configuration

Add these to pelicanconf.py to customise the output path:

# Default values shown below
RANDOM_ARTICLE_SAVE_AS = "random/index.html"

Note: RANDOM_ARTICLE_URL is not consumed by the plugin itself —
it is only needed if you want Pelican's link helpers to resolve /random.
Set it to match RANDOM_ARTICLE_SAVE_AS:

RANDOM_ARTICLE_URL = "random/"
RANDOM_ARTICLE_SAVE_AS = "random/index.html"

Custom template

By default the plugin renders a small built-in HTML/JS template. To use your own Jinja2 template instead, point RANDOM_ARTICLE_TEMPLATE at a file path:

RANDOM_ARTICLE_TEMPLATE = "themes/mytheme/templates/random.html"

The template is rendered with these variables:

• SITENAME – your site's SITENAME setting (HTML-escaped).
• SITEURL – your site's SITEURL setting (HTML-escaped).
• article_urls_json – a JSON array of the selected article URLs, pre-marked safe for embedding directly inside a <script> block (not HTML-escaped).

If RANDOM_ARTICLE_TEMPLATE is unset, the built-in template is used.

Excluding articles

Articles can be excluded from the random pool via any combination of:

# Exclude articles whose category is in this list
RANDOM_ARTICLE_EXCLUDE_CATEGORIES = ["Meta", "Drafts"]

# Exclude articles that carry any of these tags
RANDOM_ARTICLE_EXCLUDE_TAGS = ["no-random", "wip"]

Individual articles can also opt out via metadata, e.g.:

:random: false

Random: false

which becomes article.random and, if falsy, excludes that article. All three settings are optional and default to no exclusion; they combine with the plugin's existing "published only" filter.

How it works

At build time the plugin:

1. Connects to Pelican's article_generator_finalized signal.
2. Collects all published article URLs.
3. Renders a tiny HTML page that contains the full URL list as a JSON array.
4. On page load, JavaScript picks a random entry and calls window.location.href.

Because the redirect happens client-side, the page is completely static and
requires no server-side logic.

Requirements

• Python >= 3.10
• Pelican >= 4.5
• Jinja2 (bundled with Pelican)

License

MIT License © Wei Lee