Plugins

If you made a plugin and want it included in this directory, let me know!

Generic

Conditional HTML insertion

This plugin inserts an HTML snippet into the page iff that page has an element matching certain selector.

The key difference from the built-in insert_html widget is that it can check for one element, but insert in another. The element to check for is defined by the check_selector option, while the selector option defines the target element to insert the snippet in.

For example, if some content requires some JavaScript to interpret, you may want to insert that JavaScript only in pages that actually need it. Of course, that JS usually has to go to the page <head>, not inside the content element, and you don't need it in every element, so insert_html doesn't work well for this task.

One example is self-hosted asciinema player. It's smaller than a video would be, but it's still quite a chunk of JS and it's better to insert it only in pages that have any <asciinema-player> elements.

There are other possible uses of course. Here's an example that adds a warning to your page if it has any <blink> elements:

[plugins.insert_if]
  file = "plugins/insert-if.lua"

[widgets.blink-warning]
  widget = "insert_if"
  html = "<div><strong>Warning: blink elements are obsolete!</strong></div>"
  selector = "body"
  check_selector = "blink"

Download: insert-if.lua.

File inclusion

For those who miss {% include "path/to/file" %} directives from template processors.

This plugin adds a fake HTML element <include>path/to/file</include>. For example:

<include> includes/footer.html </include>

When it encounters this element, it reads the includes/footer.html file and replaces the include element with its content.

By default the file is parsed as HTML, but you can also include it as raw text with HTML special characters escaped, using <include raw="raw">...</include>.

You can specify either an absolute or a relative path. If a relative path is given, it's relative to the current directory where you run soupault.

Sample configuration:

[plugins.include-tag]
  file = "plugins/include.lua"

[widgets.process-include-tags]
  widget = "include-tag"

Download: include.lua.

Content

Reading time

Calculates estimated reading time based on word count and inserts it into the page. Sample configuration that counts words inside a <div id="content"> and inserts the result in <span id="reading-time">:

[plugins.reading-time]
  file = "plugins/reading-time.lua"

[widgets.insert-reading-time]
  widget = "reading-time"
  selector = "span#reading-time"
  content_selector = "div#content"

Download: reading-time.lua.

Escape HTML special characters

Writing about HTML in HTML can be especially annoying since you have to replace all special characters (<, >, &) with HTML entities. I always wished the <pre> tag content was treated as raw data, since we sadly gave up on XHTML anyway. With this plugin you can do it easily.

It converts the content of an element to its HTML source. E.g. <pre><p>hello world</p></pre> to <pre>&lt;p&gt;hello world&lt;/p&gt;</pre>.

[plugins.escape_html]
  file = "plugins/escape-html.lua"

[widgets.raw-html-in-pre]
  widget = "escape_html"
  selector = "pre"

Download: escape-html.lua.

Site URL

This plugin changes all relative links like /about.html to absolute like https://www.example.com/about.html. Sample configuration:

[plugins.site-url]
  file = "plugins/site-url.lua"

[widgets.set-site-url]
  widget = "site-url"
  site_url = "https://www.example.com"  

Download: site-url.lua.

This plugin highlights the link to the current page/section in a navigation menu. You can see that the “Plugins” link on this page is bold, it's what this plugin does (it adds a nav-active class to that link).

It assumes that you are using relative links and that you keep all navigation links inside one element (like <nav>). It may require some tweaking for your website. Sample configuration:

[plugins.section-link-highlight]
  file = "plugins/section-link-highlight.lua"

[widgets.nav-menu]
  widget = "include"
  file = "templates/menu.html"
  selector = "div#nav-menu"

[widgets.highlight-active-link]
  after = "nav-menu"
  widget = "section-link-highlight"
  selector = "div#nav-menu"
  active_link_class = "nav-active"

If you keep navigation menu in a separate file like I do, the after = option is necessary for correct ordering, otherwise the highlight-active-link widget may run before navigation links are actually available.

Download: section-link-highlight.lua.

For people who store their site source in a public repository. This plugin inserts a link to the page source file in the repository, by appending the page file path to a base URL (the repo_base option).

Written by Hristos N. Triantafillou.

Sample configuration from his site:

[plugins.source-link]
  file = "plugins/source-link.lua"

[widgets.source-link]
  widget = "source-link"
  selector = "div#source-link"
  link_text = "Source link for this page"
  repo_base = "https://git.sr.ht/~hristoast/hristoast/tree/master/"

Download: source-link.lua.