• The (Hu)go template syntax is bad.

    There is no two ways about it. It’s just bad and often counterintuitive. It’s hard to read, hard to write, hard to debug, hard to fill in blanks. Easy things should be easy and hard things should be possible. I feel like everything is just hard with it - not impossible per se, but often harder then it should be.

    I mean just look at this one line:

    1
    
    {{ $paginator := .Paginate (where .Site.Pages.ByDate.Reverse "Type" "post") (index .Site.Params "archive-paginate" | default 25) }}
    

    This does/means the following:

    • $paginator - that’s a custom variable, it needs to be prefixed with a $
    • := - you need to use this operator to declare a variable and assign a value. But later it’s fine to just use = to reassign it.
    • . - “the dot”. It holds the context, which is basically a kind of scope. Why the scope is not implied? I don’t know. I guess if you’d have a this keyword, you’d end up writing this.whatever… and you would still need to differentiate globals and in-scope vars, so I guess that’s better?
    • .Paginate - Inside “the dot” there exists a Paginate function which has to be upper case because that is the way to make a function visible outside of its “package” in go. If you look at the list of available functions in hugo, you will know that a function was exported, but not why. Also a lot of functions were not exported, but you also do not know why. I assume that the lower case functions are all part of hugo’s templating standard lib. But it’s not explained what is going on in the docs explicitly.
    • - A space (yup). Functions and parameters are separated by spaces, so this space indicates the start of the Paginate function call (And not the parentheses in front of the where, as one might think when coming from other languages).
    • ( - The start of the parentheses denotes a nested expression.
    • where - that’s the where function which takes an array and compares a value at a given key using an operator (equals is implied and can be omitted like has been done here) to a value and only keeps the elements that pass the test.
    • .Site.Pages.ByDate.Reverse - The .Site.Pages part is an array of all pages of the blog. The ByDate.Reverse part is used (and available only) on list pages - another detail you’ll have to know - that is pages that have other pages under them in the file hierarchy. AND that the homepage is a special kind of list page. This is a snippet from the home page, so you can use it here to change the order of the retrieved array. Why you can’t retrieve pages in similar manner on non list pages is unclear to me.
    • "Type" - This is the key parameter of the where function. The key is “Type” here. Why is Type capitalized? Maybe it has to because of exports? Maybe it’s some other reason that I don’t know. In any case it is part of the keys of the element that is kept (or discarded). For the pages array an element includes things like a Permalink, a published Date and a also a Type. How do you know what an element includes? Well, it’s hard to say, because the proposed solution to use something like &#123;&#123; printf "%#v" . }} within a range function call that references the pages from the Paginator above only prints garbage. An actual solution is to use <pre>&#123;&#123; . | jsonify (dict "indent" " ") }}</pre> which gives a pretty printed JSON representation of all the available properties within a given context. But you’ll not find this solution in the docs, you have to get lucky and find it in the forum or Stack Overflow.
    • "post" - this is the match parameter of the where function. In other words the value found for the key “Type” must match this value in order to be included in the filtered array.
    • ) ( - we finish one nested expression - which is parameter one of our .Paginate call (the array to paginate) and start another nested expression - parameter two (the page size) of .Paginate
    • index .Site.Params "archive-paginate" - this returns the value at index or key n of a given array. So in this case the value at .SiteParams.archive-paginate
    • | default 25) if index does not return a value the default function can take over and return a default value. I don’t know why this has to be a function. I also find the whole part index .Site.Params "archive-paginate" | default 25 difficult to parse: Is the pipe still part of the index function call? You’ll have to know what pipes are.

    Finally, we have parsed the whole thing:

    instantiate customVar = 
    functionCallThatReturnsAPaginator(
        functionCallThatReturnsAFilteredArray,
        (
            functionCallThatReturnsANumber ||
            functionCallThatReturnsaAdefaultValue
        )
    )
    

    And .Paginator itself is just an object that makes it easier to refer to and implement a paged navigation for an array of given elements (posts).

    Apart from the unusual syntax I find (Hu)go templates hard to parse, even if I grok them somewhat. (Hu)go’s way to write function expressions, namely using spaces instead of parentheses and commas make the whole line harder to read than it needs to be. Compare:

    1
    
    {{ $paginator := .Paginate (where .Site.Pages.ByDate.Reverse "Type" "post") (index .Site.Params "archive-paginate" | default 25) }}
    

    vs.

    {{$paginator := .Paginate(where(.Site.Pages.ByDate.Reverse,"Type","post"),(index(.Site.Params,"archive-paginate") | default(25)))}}
    

    Granted, this is still hard to read, because a lot is happening in this one line of code, but still: I’d argue it’s much easier to parse, because opening and closing parentheses and commas carry much more information than a simple space could. Spaces are also commonly used to align or balance things as has happened around the pipe char. Does this carry semantic meaning? Nope, not in this case!

    A visualization of what different symbols of the templating syntax mean in our example. It turns out that the space char carries three differnt meanings: an aesthtic space, a start of a parameter list, a delimiter between parameters.

    The space is doing an enormous amount of overtime here and I have yet to see a good justification of muddling the waters like this. The only reason I could see is that you have to balance parentheses, meaning you’re ending up with the line ending in ))). The best part is that you still need parens in any case, you just have to put them around the whole function expression! The real template version safes you two parentheses for the price of a parsing headache. I feel like that’s not worth it.

    Let’s move on: It should be super easy to limit the list of pages to only include a certain category of posts, right? Would this have been what you’d come up with on the first try?

    1
    2
    3
    4
    
    {{ $allPosts := where .Site.Pages.ByDate.Reverse "Type" "post" }}
    {{ $allDailyDogos := where .Site.Pages "Params.categories" "intersect" (slice "DailyDogo") }}
    {{ $onlyDogos := intersect $allPosts $allDailyDogos }}
    {{ $paginator := .Paginate ($onlyDogos) (index .Site.Params "archive-paginate" | default 25) }}
    

    So far so good. How about the inverse? You’ll find that there is no way to tell the line $allDailyDogos to simply do the inverse. There is no "not intersect" or whatever. You have to use another function called symdiff:

    1
    2
    3
    4
    
    {{ $allPosts := where .Site.Pages.ByDate.Reverse "Type" "post" }}
    {{ $allDailyDogos := where .Site.Pages "Params.categories" "intersect" (slice "DailyDogo") }}
    {{ $noDogos := symdiff $allDailyDogos $allPosts }}
    {{ $paginator := .Paginate ($noDogos) (index .Site.Params "archive-paginate" | default 25) }}
    

    Symdiff is short for symmetric difference and means here that we want all elements from the $allPosts array that are not part of the $allDailyDogos array. Meaning we are keeping only those posts, which is like filtering for the inverse of the $onlyDogos array from before.

    We could have mashed this all into one line to make it totally unreadable, but I think this is instructive and it would have not been anymore readable in other template languages (if they even would’ve been able to deal with this as a one liner). Still:

    • Why do I need to make a slice/array out of “DailyDogo”?
    • Why is there no NOT operator? - it would’ve been nice in two instances: 1. inside the where function to save an extra call to symdiff or 2. as a better (I’d say) alternative to using symdiff, because people think more along the lines of “all but not these kinds of things” instead of “symmetrical difference of these two sets”.
    • Why is it so hard to chain conditions to the where function to the point where you’d rather create two arrays instead of filtering the array down in one step?

    Ugh. There is so much in just this one line - and the subsequent slight changes I have done - that I find weird and unergonomic. I hope I could also show that it’s not complete and utter failure to understand what’s going on, either. Sometimes things are just badly designed for the most obvious use cases in order to accommodate fancier goals. I’d rahter have a templating syntax/language that makes things easier. If that makes it more boring: Good. I’m here to improve my blog first and foremost.

  • Yesterday I tried to write three different blog posts about three different half baked ideas and published none. I aborted them one after another after being dissatisfied with their individual messages. Too much hot take, not enough general validity.

    I swear: Someday I will write a blog post again.

  • Even though I want to use the services that Omg.lol provides, I struggle to do so.

    I set up a profile page now, but I feel like this should be a page reachable under my domain (I can probably set this up). I love the idea of a status.log, but I have a micro.blog already and all the content should come from that as the canonical place and be fed into other means to consume my content. I don’t want to produce parallel content or keep things up to date manually.

    I’ll keep my omg.log address, because my mastodon account is registered on their instance, but I’m not sure what I’ll use it for otherwise at the moment.

    UPDATE: My profile page is now reachable under my domain.

  • As somebody who frequently edits older posts to maybe add links and/or fix typos, etc., I just have to say how pleasant it is to do this through @danielpunkass' MarsEdit.

  • The more I read about how mastodon works, the happier I am that I ended up being so curious about the publishing options in iA Writer that I had to check out micro.blog about 1.5 years ago.

    Don't get me wrong: It's great that people are checking out mastodon. It lets me follow them on micro.blog. But moderation and all the other social aspects of running a social network (even if it's "just" a timeline of blogs) are what's hard.

    Many people that are leaving Twitter right now (or at least create a mastodon account on the side, for the time after Twitter finally implodes) end up on mastodon.social, the biggest mastodon instance there is. When I scrolled through their explore timeline I was surprised to find a post by fellow corgi lover and micro.blogger Hollie Butler (@hollie) that urged people to find a better instance, because mastodon.social has had a bad moderation for a long time.

    In the replies to this post a user asked: Can I move my content over to a new (e.g. better moderated) instance? The answer is no. You can move the people you follow, but not your content, it seems.

    With micro.blog this combination of problems doesn't really exist. On the one hand they have and enforce community guidelines that protect the community against hate speech, harassment and so on. Community manager Jean MacDonald (@jean) does an excellent job as far as I can tell. So there is no reason to move. Micro.blog is just a blog hoster with a social timeline component.

    On the other hand exporting your data is easy enough, too. Even if there would be a reason at some point to move: I do own all my content and it's not useless content, because a micro.blog is just a blog and so the content I'd export are just blog posts.

    The point is: At the moment micro.blog seems like the ideal place that is not twitter, but has moderation figured out (and still lets you connect to mastodon users). I feel like I'm in good hands with them. If you're willing to fiddle, you can connect your own blog for free, or you could pay them 5$ a month and have everything set up for you. Connect a domain and you really truly own your content, even in the case you feel the need to move away, since the permalinks point to your domain not micro.blog's (I'm not claiming the moving blog hosters is easy, but it's possible…).

  • In an effort to make my blog perform better - lots of images means slow load times - I have updated all my images to use this somewhat undocumented micro.blog feature that resizes images:

    Micro.blog offers an endpoint to resize uploaded images. Once you upload the image, if you do [micro.blog/photos/](https://micro.blog/photos/#)##x/, but replace ### with the pixel width you want, followed by the full URL to the image, you’ll show an image with that width. For example, if I wanted the image at [json.blog/foo.jpg](https://json.blog/foo.jpg) to be 480px wide, I could use <img src=“https://micro.blog/photos/480x/[json.blog/foo.jpg](https://json.blog/foo.jpg)”>.

    @jsonbecker in the Micro.Blog Forums

    This first page load still takes a long while, since my home page weighs in at about 25 mb of mostly image data. But it's a start.

  • Taking a break from microcasting

    I recently published a post about my microcasts and I‘m now writing this to tell you I’m going to microcast less. Less frequent and less scheduled. This is even weirder because I just created an intricate shortcut that automatically publishes a post with the right episode title and number without having to look up any of those details, which streamlined the entire process a lot.

    But I have noticed that I‘m not as much in the mood at the moment to record my thoughts in this way. The early riser project, for example, was a great McGuffin to get me out of bed, but since I have changed my approach to waking up, it has become less important to me. I don‘t want to record these little episodes for the ramblings alone.

    Being a big fan of podcasts like Back To Work and Cortex, I thought I could do a microcast about my work and how I approach it, but I have noticed that I would like to write about these things, not only talk about them extemporaenously. LeadDev is also the microcast for which the ratio of recorded/published episodes is the worst: I take this as an indicator of my wanting to express myself more carefully than I can while walking the dog and having to observe the environment.

    À propos the dog: I created my first microcast, the PuppyCast, because I wanted to have a record of the challenges and joys of raising a puppy. I wanted to look (DailyDoogo, which I will not abandon, btw.) and listen back to this important time in my life. But I think that this project has run its course: I don‘t feel the need to publish this every week anymore. It‘s not like nothing changes or that there is nothing to report dog-wise, but it all comes down to the need to simplify and de-schedule my life. And I have episodes for the first six months, which seems like a good place to stop.

    Seasons change. And this is how I feel about my microcasting: Right now I‘d much rather write than talk. Looking at my blog I mostly see noise that was produced hastily to satisfy a self-imposed schedule. I will let this stuff go, for now.

  • Short Posts With Titles

    One kind of blog post that I really like is a short post with a title. One or two paragraphs about a topic (almost any topic really) is a great length for me. A title makes sure that it’s going to be a somewhat framed thought.

    A short post with a title can contain a picture or two to illustrate what’s going on. It could have links or a video embed. I would really like to write more posts of this kind myself.

  • Adventures with Hugo: Configure Hugo's Native Syntax Highlighting On Micro.Blog

    If you are one of the brave people that uses Hugo Version 0.91 and wants to take advantage of Hugo’s native syntax highlighting capabilities on a light theme (like the default theme in this example), you might be surprised:

    As you can see… you can’t really see much.

    Thankfully this can be changed, by changing the configuration for syntax highlighting. But in order to do that you have to know the following:

    [@matti](https://micro.blog/matti) interesting … so much is still a blackbox for me. I just tinker until I get results. My two favorite finds are the config directory (which take precedent ahead of the json files) and the assets directory (with which you can build Javascript and Sass files from templates).

    You have to know about the precedence because for some reason, changing the config.json in your theme won’t do the trick. This is how it works:

    Get A Functioning Custom “New-Plugin-Style”-Default-Theme For Your Blog

    EDIT 18.02.2022: The following is not up to date anymore. Plugin-Themes now behave much more convenient: Just install the theme, activate for your blog, create a custom theme and only add config/_default/markup.json template.

    First of all make sure you are on the Hugo version 0.91 (dropdown in the Design screen, remember to save) and install the default theme as a plugin (Plug-ins screen). Then go to Design again and click on “Edit Custom Themes”, on the next screen click on the default theme and duplicate it with the button in the next screen. You should now be back in the custom themes overview list. Click Design in the sidebar once more and choose your custom theme, save. Click “Edit Custom Themes” again and then on your copy of the Default theme.[^1]

    Change Configuration

    You should now be inside your custom theme screen. Click on “New Template”. You will be presented wie the template editor and theme preview split view.

    Name the template config/_default/markup.json and set its contents to:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    
    {
        "highlight": {
          "anchorLineNos": false,
          "codeFences": true,
          "guessSyntax": false,
          "hl_Lines": "",
          "lineAnchors": "",
          "lineNoStart": 1,
          "lineNos": true,
          "lineNumbersInTable": true,
          "noClasses": true,
          "style": "monokailight",
          "tabWidth": 4
        }
    }
    
    

    This is basically the default config from the Hugo documentation, except that for style we use monokailight instead of monokay. Click “Update Template”, your site should be rebuilding as indicated by the spinner. When Hugo is done, syntax highlighting should now be working as intended and the code be legible.

    Example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    
    {{ define "main" }}
    <div class="home h-feed">
      <ul class="post-list">
      {{ $paginator := .Paginate (where (where .Site.RegularPages.ByDate.Reverse "Type" "post") "Params.title" "!=" nil   ) (index .Site.Params "archive-paginate" | default 25) }}
      {{ range $paginator.Pages  }}
          <li class="h-entry">
    			<h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
    
            <a href="{{ .Permalink }}" class="u-url"><span class="post-meta"><time class="dt-published" datetime="{{ .Date.Format "2006-01-02 15:04:05 -0700" }}">{{ .Date.Format "Jan 2, 2006" }}</time></span></a>
    
            <div class="e-content">
             	{{ .Content }}
            </div>
          </li>
        {{ end }}
      </ul>
    
      <p class="rss-subscribe">subscribe <a href="{{ "feed.xml" | absURL }}">via RSS</a></p>
    
    </div>
    {{ end }}
    

    [^1]: I’m not sure if this is all necessary or even the right way to go about it. It seems pretty involved and I don’t even know how you would migrate your customizations in an easy way if you happen to have used the old style of choosing a theme… but this way works, that much I could prove.

  • Able To Post Again

    My playing around with custom themes led to errors in the building of my site. Haven’t been able to post at all because of this for five days or so.

    I published two bigger posts:

    Uff. What a relief to be able to post again (now for real).

subscribe via RSS