File Inclusion Shortcode Template

[Xaldew]

I'm trying to create a shortcode template file to include another file, e.g., given a file in post/include-test.md:

<!--
.. title: Include Test
.. slug: include-test
.. date: 2024-10-27 22:39:17 UTC+02:00
.. tags:
.. category:
.. link:
.. description:
.. type: text
-->

Include tests...

{{% include "test.md.inc" %}}

{{% foo bar="baz" spam %}}

(The file test.md.inc is in the same folder as include-test.md)

For this, I created a shortcode template file in shortcodes/include.tmpl which uses the Jinja2 include statement:

{% include _args[0] %}

Obviously, there are probably some pathing issues I need to handle, but that seems like a secondary issue, as I cannot even get the basic example shortcode template example described here to work. When compiling the above file, I get the following partial HTML:

<p>Include tests...</p>
<p>{% include _args[0] %}</p>
<p><div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div></p>

So, it seems like the templates were properly expanded as text, but all Jinja/Mako constructs seems to be ignored. Is this some kind of bug, or am I missing something?

[Kwpolska]

Is your blog using a Jinja2-based theme? The templating language used in shortcodes must follow the language used by your theme.

(I tried your shortcode and got a template lookup error. I would probably not depend on the template system for this, and would instead write a Python shortcode plugin).

[Xaldew]

Ah, that's probably why then: My blog is using Bootstrap4 as the theme, which I guess isn't a Jinja2 based theme then?

Right, I'll see if I can whip that up as Python plugin instead then!

[Xaldew]

The following Python Shortcode class seems to work:

class IncludeShortcode(ShortcodePlugin):
    """Plugin for the include directive."""

    name = "include"

    def handler(self, file_name, post, *args, **kwargs):
        """Include the specified file in the given file."""

        dname = os.path.dirname(post.source_path)
        path = os.path.join(dname, file_name)

        with open(path, "r", encoding="utf-8") as f:
            output = f.read()

        return output, [path, __file__]

However, as expected this only works for the 'first' level, which is probably fine for now. What is the intended behavior, if any, for nested shortcodes? E.g., an include inside an included file in the above example?

[Kwpolska]

If you want to nest shortcodes, you would have to manually call the shortcode processor from your plugin.

[Xaldew]

Right, so the final(tm) plugin that also handles nesting:

#!/usr/bin/env python

"""File inclusion shortcode."""

import os.path

from nikola.plugin_categories import ShortcodePlugin


class IncludeShortcode(ShortcodePlugin):
    """Plugin for the include directive."""

    name = "include"

    def handler(self, file_name, site, post, *args, **kwargs):
        """Include the specified file in the given file."""

        dname = os.path.dirname(post.source_path)
        path = os.path.join(dname, file_name)

        with open(path, "r", encoding="utf-8") as f:
            args = {'post': post}
            output, deps = site.apply_shortcodes(f.read(), extra_context=args)
            deps.extend([path, __file__])

        return output, deps