Spinx

// Wrangling Sphinx - aka abusing lua AND python and why I was up till 3 am

So, as the astute reader may be aware, this blog/site/collection of words, is pretty well statically generated. And while there's other software you can use (see the footnotes on this page), I wanted to make my life difficult and contemplate suicide at the same time[#].

To make my life easier, Pandoc does most of the heavy lifting, I do write most of the things in PHP, and then the actual content itself is typically a reStructuredText document. It's pretty similar to markdown but has a few nice things like comments, and replacement words/phrases, footnotes getting handled automatically. I probably under-utilise it, it's no LaTeX, but honestly, it's decent af.

Anyway, so the issue at hand that I faced, was that I had a bunch of static pages, that all had the menu cooked into them, and while that wasn't bad, it was starting to make a lot of my pages dirty/regenerated for when a new page was added, or the styles changed (which I have now fixed, and it's just the MD5 of the content). I resolved that by moving my content into an iframe, which in itself proved to be a bit of work. However, I try to be as compliant as I can with standards, so my pages contain the meta that limits sources to this domain only, fine in theory, but trying to redirect an iframe to an external site hits the CSP.

The work around is hacky af - I originally had patched/extended a PHP plugin for Pandoc but ended up needing to over-ride a bunch of things so that I could stream data into Pandoc (vs always having to write to a temporary file). Now I get to where I was before this fix, I needed a way to add extra arguments to the Pandoc argument, and I didn't need a bunch of the extra logic the plugin had, so I overrode the last function I needed (dependency removed, woo!).

Now with my own implementation based off of someone else's work - I am able to make the patch I need. I ended up getting the helloworld.lua file working (which was a macro to replace {{helloworld}} with Hello, World!). And boy, what a journey that was! I've played GMod before, but never written lua for it. I went through a few iterations, but now I am at a point where I am happy with it. So here's the lua file:

-- hyperlinks.lua

-- End URLs in hyperlinks with {blank}, {parent}, {top}, or {self} to have the appropriate target added to the link.

local suffixes = { 'blank', 'parent', 'top', 'self' }

function targetAdjust(elem, suffix, targetDest)
    local url = elem.target:sub(1, -string.len(suffix) - 1)
    local targetNameParts = {}
    for i = 1, #elem.content do
        table.insert(targetNameParts, elem.content[i].text)
    end
    local targetName = table.concat(targetNameParts, ' ')
    return pandoc.RawInline('html', string.format("<a href='%s' target='%s'>%s</a>", url, targetDest, targetName))
end

return {
    {
        Link = function(elem)
            for i = 1, #suffixes do
                local suffix = suffixes[i]
                local suffixFull = '%7B' .. suffix .. '%7D'
                if elem.target:sub(-string.len(suffixFull)) == suffixFull then
                    return targetAdjust(elem, suffixFull, '_' .. suffix)
                end
            end
            return elem
        end,
    }
}

If that's hard to copy - you can find the content here. An example of how it looks is here:

`the content here</blog/2022-05/sphinx-hyperlinks-lua.html{self}>`_

That's all there is too - you might notice that the check we do is looking at '%7B' .. suffix .. '%7D' - that's because I believe this code is already running -after- the filter step. Obviously, it'd be better to fix it up, but this works for the time being.

To run it, you'd do the following on the CLI:

pandoc --lua-filter ./hyperlinks.lua --from=rst --to=html my-blog.rst

and that's it, done!