The Problem

The distance between being motivated to write here again and actually writing here again could not be greater as it is. I’ve been telling people I have reactivated this site and I want to write more again. But I don’t. And the only reason is that I dread creating new posts. Which is ironic because the whole reason this site looks very different from a couple of months ago is that I redesigned and - to some extent reprogrammed - the whole thing in Hugo to have a fresh start. So, in an effort to dig down on what is stopping me, here goes nothing:

The structure

Having built this on Hugo, there’s tons and tons of nested folders. Which is okay because content that goes content/stmfd/2024/04/my-post-title does make sense in my head. What throws me off when setting out to write is that right next to that all of the logic and layout of the site are situated. A simple solution here might be to only open the content folder and leave all the others alone.

That however is only half of the pain relief.

The real pain is that my brain doesn’t compute writing blog entries or stories the same way it does code. The above mentioned path makes perfect sense in my code brain. It’s well structured, it contains all the required information, everything is about this is reasonable. But. Everything about this path disturbs my creative mind. Beginning with the fact that I even have to think about it. Like post titles. Why, in higher-being-of-your-choice name do I have to think about the title of something I’m just in that moment pouring out of my mind?

The editor

This one is more tricky. As I am writing this, I am typing into Obsidian, which for better or worse is currently the tool for my second brain. That works. Obsidian feels non-code enough to lift my mind out of looking at everything all the time all at once mode into admiring the donut and taking a step back. Unfortunately, this isn’t the final home for this text. In Hugo, like in pretty much every static site generator, content is kept alongside the configuration. That, for better or worse, triggers my coding brain. The beauty of Apples products isn’t so much that they look good on the outside. The beauty of Apples products is that they are designed well down to the PCB. I – conditionally, but that is an other post – love Apples products. I love the philosophy. I feel good in a clean environment, offline like online. Writing text in one place only to temporarily escape the implications of the other feels wrong.

Now, I don’t want to get to a point where I can comfortably write posts in VS Code. While being a mediocre modern replacement for the forever missed Sublime Text 2, it is by design not a prose editor. You might venture to say Obsidian also ain’t. True. We’ll get to that.

The format

Markdown is by far the most versatile Hypertext reduction format out there. Yes, reStructuredText is easier to write, yes WikiText is much more powerful, yes. All of those are standalone formats however. Markdown isn’t. Markdowns’ whole original premise was to convey semantics without obstructing the content even if visual formatting fails. That, again, works fine for my coder brain. And in part, no thanks to Obsidian, it works well enough for my creative brain too. And it is fast to write, once internalised.

It is in any case not pleasurable. Not as editing experience, not while looking at it on git diffs. Not ever. It looks like code, because, in a way, it is code. A dumbed down, prose-accomodated version of code, but nevertheless, it’s code.

My issue isn’t so much with the formatting indicators. Obsidian especially has a very nice way of dealing with those. Just showing them when actively in their context keeps the disruption to the required minimum. On the contrary, I would even go so far as to say that Markdowns formatting indicators are its greatest strength and should be part of every text editor’s core behaviour. I mean, even Google added it to Docs, albeit in a oftentimes strangely behaving way.

My issue is with the writing experience feeling technical. I cannot quite put a finger on what I mean by that. Some pointers would be other editing programs I’ve used in the past. First and foremost Scrivener, but also WriteRoom. The latter sadly not having been updated in more than a decade. There’s a fun way to be reminded of one’s own aging.

The solution

A little bit of history

There’s a (private) repository on my GitHub where the first commit says Date: Sun Feb 12 12:56:45 2017 +0100. That is a while ago. There is other repositories on backups, some of those burned DVDs (remember burning CDs and DVDs, if not, you’re too young for this section of the post, but welcome!) that date back years before that. What’s in it? Attempts to fix the above I abandoned for various reasons.

For many years, the answer was Wordpress. Wordpress was and is arguably the Platzhirsch for single or (small) team web publishing. Wordpress also very much doesn’t make me happy. I will not bash it, but I also won’t use or recommend it ever again.

What’s the alternative? Or, more precisely, why is this post in the devlog section and not on the main blog? Well, for as long as I can remember, I have been dreaming about building my own CMS. Fortunately, in the beginning I was young enough to not realise the amount of effort that would take. Out of that dream, the most relevant remaining tidbit is content editing and publishing that doesn’t have too much but grows with the needs.

That repository I mentioned is named Fountain. Fountain was supposed to be my solution. Since I am not stupidly young anymore, I reduced the scope from a full blown CMS to something more akin to a blog slash static site manager. I have a pretty clear vision of what that thing should be and do and what it shouldn’t be. I made one mistake: I started writing it in Vala. Now, don’t get me wrong. Vala is a great programming language and I will likely continue to use it where applicable. But it is also very much married to Linux even though GTK as it’s basically required foundational library tries very hard not to be Linux-limited. Using Vala hindered me more than I want to admit and lead to the slow death of the project. Well, no, the patient is not dead. Let’s go with a cryo-chamber frozen until needed by the world again sort of situation. That feels less harsh.

Fountain is supposed to be my solution.

Going with Hugo was and is only intended as an intermediary step. The previous setup was, for several reasons, not maintained for a couple of years so a refresher was necessary anyway. I had waited for Fountain to get to a point of being ready to be that successor and to be fair, in many ways it is, but in many other ways it isn’t.

Is the solution to just not write until that magical Fountain is finished? Most definitely not! (Most defiantly not?!)

The solution is multi-faceted:

1. I need to code a few things that are likely technically more throw-aways onto the Hugo setup but nevertheless necessary for peace of mind:

2. Fountain needs a rebirth

Making things bearable

The goal for now is to make my current setup work for my mind. To allow myself to pour my thoughts into writing despite not being at peace with the publishing system.

This means I will likely invest a little time here and there to write little helper scripts and stuff. This section of this post exists to give me permission to whatever time is required for this into a system I do not intend on keeping longer term.

This is what we do as programmers. We create things, than we are unhappy with them and we throw them away and create something new. “Beauty is terror”, Donna Tartt once wrote. Such is the way we code. Everything made from nothing must become nothing again.

Fountain, again

In the spirit of the luck throwing money into Fontana di Trevi is supposed to be bestowed onto the beholder, I want to throw some quite radical change at fountain: A rewrite.

A good rewrite starts with boiling down the requirements to what is actually necessary. This time, to keep myself accountable, I will do a lot of that in public from the beginning. Maybe not the code, but at least regular rapports and maybe even discussions of some form somewhere.

So, long story short: I am lowkey starting a side project again I have been in a co-dependency with for the past six to ten years. Stay tuned. I promise it’s not yet another static site generator. It’s also not a CMS. Remember? I’m unhappy with the status quo. More on this next time – whenever that will be. At some point, I might set a schedule for updates and ponderings, right now, I don’t see myself able to.

Recently, I finally got around to designing something of a portfolio website for me. There really is never time to do these, is there? You can head over to GitHub to view the source if you want, no need to keep it private. 

The general setup is a Jigsaw-based static site using TailwindCSS as style framework. The whole site does not have a single line of JavaScript in production which – surprise! – massively simplifies the setup! (Also, like, loading times are amazeballs.)

Decisions

Before deciding on the frameworks to use, I set up some constraints for the design and more so for the technical foundation of the site:

• Graceful degradation on older browsers
• Very good accessibility
• Responsive-ish layout
• Fast
• Low-barrier content modification

Along came also some quirky demands like wanting to use flexbox for layout and having Twig or Blade as a Template Engine as I am most comfortable thinking template logic in those. I also wanted to write as little as possible server or generation code as this site will – for the foreseeable future – not have any dynamic content. Nevertheless, some kind of content editing that can be easier than always writing everything in HTML was added as a nice-to-have.

In my toolbox, these requirements form a straight path towards static site generators. Among these, since I am well-versed in Laravel, Jigsaw is the obvious choice for me. One never knows if there’s any modifications to be made and it always helps to know ones way around the underlying architecture.

Choosing TailwindCSS as a style framework was a no-brainer. It is a wonderfully simple solution and I find myself clicking with the utility-only approach.

Getting it done

Jigsaw provides several events to modify and extend the build process. Since my goal was to add content to the resulting HTML files after all other build steps, I opted for adding a handler on the afterBuild event:

1
2
3
4

// in Jigsaw's bootstrap.php

/** @var $events \TightenCo\Jigsaw\Events\EventBus */
$events->afterBuild(InlineStyles::class);

The Inline Styles event handler is of course where the magic happens. First, all built html files need to be gathered, Symfony’s Finder component is great at that:

1
2
3
4

$htmlFilesFinder = Finder::create()
            ->in($jigsaw->getDestinationPath())
            ->name('*.html')
            ->files();

Then, we can fetch the compiled CSS and inject it into a style tag in the head using SimpleXML:

1
2
3
4
5
6
7
8
9

$htmlFile = simplexml_load_file($htmlFilePath);

        $cssPath = $jigsaw->getDestinationPath() . (string)$htmlFile->head->style['data-src'];

        $cssContents = file_get_contents($cssPath);

        $htmlFile->head->style = $cssContents;

        file_put_contents($htmlFilePath, $htmlFile->asXML());

The full code is available on GitHub: http://github.com/eFrane/efrane.com.

Since the last time I wrote about integrating Mermaid with Vuepress the latter matured to version 1.0. With that came a much more refined plugin interface - or maybe that existed before and I just didn’t notice it in the docs. In the meantime, I have been implementing that previous approach in a growing number of documentation sites and figured that having this as a plugin to a) reduce the hassle of getting it to work to basically zero and b) stop copying a bunch of code around would be a good idea.

So, without further ado I present vuepress-plugin-mermaidjs. When you do the search on npm, you will unfortunately find another package named very similar (vuepress-plugin-mermaid). One might ask now, “eFrane, why didn’t you just contribute to that one instead, wouldn’t that have been the healthier choice for the ecosystem?” Yes, it would have. Alas, the GitHub Repository for that plugin is empty and it doesn’t have a readme and wasn’t updated in over a year. All in all, that feels like an abandoned package to me. So that’s why I decided to publish my take as a package. 

NPM Package: https://www.npmjs.com/package/vuepress-plugin-mermaidjs
GitHub Repo:https://github.com/eFrane/vuepress-plugin-mermaidjs

I released [efrane/console-additions](https://packagist.org/packages/efrane/console-additions) v0.6.0 today. More than a year after the last bigger release this probably could have been a v1.0. However, I still feel like there’s some fundamentals I do with Symfony’s Console component in my everyday work which I would like to extract into a reusable form in this library.

So, what’s changed?

For one, this development episode was focused on reorganising the code. There’s still very few files in the repository but that doesn’t mean that there wasn’t room for optimisation. The result of this is, that the tests folder now resemble the folder structure of the src folder, thus making it easier to find the corresponding test file.

The bigger change is a partial rewrite of command batches. Before, the Batch class internally managed every possible action as a combination of strings and weird arrays. This type-conglomerate lead to a quite a few ugly places in the code which felt like they might break at a moment’s notice. Since this version, Batch internally relies on Action classes which know how to handle themselves. This also means, that Batch just became that much more powerful since all Batch wants to know about them is how to represent them as a string and a way to start their execution:

1
2
3
4
5

interface Action
{
    public function execute(OutputInterface $output): int;
    public function __toString(): string;
}

Usable actions are now:

• StringCommandAction - This handles executing console commands given a full command signature
• InstanceCommandAction - No need to do string parsing of a signature? Pass a command instance to this one!
• MessageAction - This is your basic echo action. Especially when PHP-izing former shell scripts, this can come in quite handy
• ProcessAction - Pass a configured Process from the Symfony Process component to this one
• ShellAction - Just want to execute a shell command and don’t feel like configuring the process yourself? This one is there for your convenience!

All of the built-in actions have convenience methods on Batch, e.g. $batch->addProcess() or $batch->addMessage().

Along with these internal updates came the jump to PHP 7.0 or newer as a language dependency and Symfony Components 3.4 or newer are required to work with this library now. The latter also means that string parsing for commands in $batch->addShell() has been deprecated and will be removed in the next release. I highly encourage any user of this library to switch to the array-Syntax.

I recently set up Vuepress for the first time to create a documentation for a new library I am working on (more on that in a future post). Since that library will do a few things that might appear sort of magical it seems like a good idea to add a few explanatory graphs to the documentation.

Now, what tool combines markdown-friendliness with creating graphs? Yep, you guessed it: Mermaid.js.

There are numerous ways of making Vuepress do things it can’t by default:

• You can overwrite the whole theme
• You can add Markdown-It plugins for additional markdown processing
• You can add global components

The long story here would be to elaborate on why overwriting the theme is not an option and the plugin route didn’t pan out. But let’s not bore ourselves with that story. So yeah, I created a new global component in .vuepress/components/Mermaid.vue and worked away. However, it’s unfortunately not exactly that simple. Since Vuepress is a SPA or rather even an PWA, rendering works a little bit different. Which in short means that it’s very easy to get something to show up on first load of a component but there’s a little work involved in having things work after navigation. The technical background to this can be referenced in the vue-router Documentation.

What I ended up with is rendering the mermaid graphs to SVG and then rendering the SVG in the component’s render() Function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import mermaid from 'mermaid/src/mermaidAPI'

let graphIdCounter = 0

export default {
  name: 'Mermaid',
  data() {
    return {
      svg: undefined,
      graph: this.$slots.default[0].text
    }
  },
  render(h) {
    return h('div', { domProps: { innerHTML: this.svg }})
  },
  mounted() {
    mermaid.initialize({ startOnLoad: true })

    let renderDiv = document.createElement('div')
    document.body.appendChild(renderDiv)

    mermaid.render(
      'mermaid' + ++graphIdCounter,
      this.graph,
      (svg) => {
        this.svg = svg
        document.body.removeChild(renderDiv)
      },
      renderDiv
    )
  }
}

Alas, this was not quite the end of it. I would have hoped that I’d be off to the races with yarn add mermaid. That’s not even close. Here’s the full list of dependencies you’ll have to add:

• mermaid
• sass-loader
• node-sass

After this, adding mermaid graphs anywhere in the documentation markdown is as easy as

1
2
3
4
5

<mermaid>
graph TD
mermaid-->isAwesome
isAwesome-->mermaid
</mermaid>

Which then renders to:

Update (2019-10-16): I published an npm package that provides the <mermaid>-Component.

Pretty much every modern language has an established Coding Style Guide. For PHP, this is PSR-2. As with other style guides of this sort, there is a tool for automatically applying the appropriate fixes to one’s code

I only recently finally switched to using PSR-2 and to make sure I wouldn’t accidentally miss running the style fixer, I added this little snipped to my .git/hooks/pre-commit-Hook:

1
2
3
4
5
6

modified_php=$(git ls-files --modified | grep "\.php$")

for f in $modified
do
    php-cs-fixer fix --level psr2 $f
done

This may well be one of the most important talks about the future of our culture.