Introducing my Custom Shortcodes for Nikola Static Site Generator

TLDR

I introduce three new custom shortcodes for Nikola: series-button, infobox, and disclaimer. Each shortcode offers simple functionalities to streamline your Nikola site's design and user experience, and prevent you from repeating yourself.

Context

Nikola, the Python-based static site generator I use for this website , allows the use of something called shortcodes. A shortcode is a simple snippet of code that can be used to add functionality to your website.

While writing some of my new posts, I realized that I was repeating myself a lot. I was adding the same buttons, some info boxes, and disclaimers. So I decided to create some custom shortcodes to make my life easier and make them available for others.

These shortcodes are designed for practical use and are available under the MIT License.

Shortcodes Overview

series-button

• Template Engine : Jinja2
• Usage : series-button-md-html-example.html(Source)

{{% series_buttons previous_url="/previous-article" previous_text="Previous Article" next_url="/next-article" next_text="Next Article" %}}

• Functionality :
• Renders navigation buttons for article series.
• Omitting previous_url or next_url will skip the respective button.
• Defaults to "Previous in series" or "Next in series" if texts are not specified.
• Customizable with CSS (#series-buttons ID).
• Use Bootstrap 4 classes for styling.

infobox

• Template Engine : Jinja2
• Usage : infobox-md-html-example.html(Source)

{{% infobox type="book" text="This is a book infobox" disclaimer="true" %}}

• Example:

This is a book infobox

• • Functionality :
• Displays an infobox for various content types.
• Supports font-awesome icons: book, video, audio, link, quote, image, sticky-note.
• Optional disclaimer can be added.
• Use Bootstrap 4 classes for styling.

disclaimer

• Usage : disclaimer-md-html-example.html(Source)

{{% disclaimer %}}

• Functionality :
• A simple shortcode to insert a disclaimer anywhere on the page.
• Use Bootstrap 4 classes for styling.

How to Use and Why

Integrating these shortcodes into your Nikola site is straightforward. Simply add the shortcode in your content where you want the feature to appear.

• Series-button : Ideal for multipart articles or blogs, it allows easy navigation between series entries, improving user experience.
• Infobox : Useful for highlighting information, such as book recommendations or important notices, making your content more interactive and engaging.
• Disclaimer : Adds necessary legal or ethical notifications efficiently, ensuring transparency with your audience.

These shortcodes save time and maintain consistency across your site, adhering to the DRY principle.

They also allow you to focus on the content, not the code, and to update their content and styles in one place, instead of having to update it in every article.

Installation Guide

To install these shortcodes in your Nikola site, follow these steps:

1. Go to https://github.com/dacog/nikola-shortcodes.git and download the shortcodes you want to use.
2. Copy the shortcodes to your Nikola site's shortcodes directory. If this directory doesn't exist, create it in your site's root directory.
3. Add the shortcodes to your article. See the shortcode overview above for usage instructions.
4. Run nikola build to build your site.
5. Run nikola serve to preview your site.

Remember, these shortcodes are flexible and can be customized to fit the style and needs of your website. Once you download them and add them to your shortcodes directory, you can modify them as you wish, changing the HTML, CSS and text to suit your needs.

References

1. Custom Shortcodes for Nikola on GitHub
2. Official Nikola Shortcodes Repository

License

These shortcodes are available under the MIT License. See the MIT LICENSE file for more information.