Musings, Rants, & Other Matters

Site TODO

rob@Loci.net (Rob Arnold) — Tue, 09 Aug 2016 00:00:00 +0000

TODO:

Site plumbing

fix CI for gitlab vs. netlify
create a preview workflow for deployed content, not just hugo server (netlify git branch support or deploy preview feature - gitlab equiv?)
rss setup properly?
[-] site search (via Google) ~~broken: fix~~ [fixed but still consider] or do differently, static… at least look at css integration similar to google powered search at https://stiobhart.net
analytics
base url for netlify deploy vs config.toml

External (or not) services, additions

Disqus fix - “unable to load” (also, improve js variable use so comment threads don’t proliferate across gitlab/selfserve/netlify, and http vs. https URL variants
- issue was a relative url for the disqus_url js variable. Base url being set fully would fix it, but doesn’t fix deployment under multiple sites causing independent threads, so need to consider best way to fully fix - for now, baseURL is set and the main site is good, plus gitlab version still seems to pull from same comment threads, so maybe a non issue.
[-] check netlify cms progress
- looked at their linked demo - looks early still, but maybe it doesn’t reflect their actual progress
integrate, eval prose.io
keep researching and trying 100% client side edit/cms type options

create a tag footer display like category footer
[-] check font, try options
- Is the same font as used in the HTML5UP theme - the color is full black whereas the base theme was grayer. Have some other fonts to try still.
continue fixing remaining URL assumption issues
category/tag - the age old do I need both? Nesting? Kind of would like a category landing page with a templated description
series in taxonomy to create ordered groups of related posts
whitespace/margins around list items - seems a little excessive to me. Would like to see them closer together [update: theme whitespace tweaked - will see how this feels for a while]
post ordering - isn’t sorting by date / reverse date, maybe mod time on file timestamp?
links in the theme seem to break out of https -> http.
- it’s doing what it’s told - consider using RelPermalink instead of Permalink, etc.?

… and stuff

post scheduling and ordering and the whole concept. Truth is, I don’t care very much about the blog aspect, so much as the wiki/collected, linked thoughts aspect. The blog part is little more than a recent changes callout type feature to me. That said, the more ephemeral and random thoughts type stuff definitely fits in more of a blog format.

Notes on Site Build and Deploy

rob@Loci.net (Rob Arnold) — Fri, 05 Aug 2016 00:00:00 +0000

So I thought that as I created a Hugo based site, I’d keep running notes of what issues I encountered and what I did about them. That way later on I could refer back to know what the hell I was thinking when x came up.

Then I charged forward, did most of the research on tablet, and just otherwise completely ignored my plan.

So instead, here’s my recollection of a few things that I do sort of recall…

Notes

site relative vs. relative root URLs

One of the biggest issues I ran across were some theme files had URL references in them to project files, like css or js, etc., that were given as root relative urls, eg. ref="/css/somestyle.css" Similar issues occured when themes would create their own url to a post, category, etc. Fixes generally involved using the hugo RelURL function.

baseURL

In my hugo site directory, I had intended to keep the baseURL as “/” as many themes and articles I’d read suggested. Hugo server itself ignores the setting by default when running locally, but since I wasn’t sure where (all) I’d be deploying to anyway, it seemed to me like keeping everything relative was a good thing. Unfortunately, I found that I needed to set the baseURL more fully for a couple reasons.

In the case of netlify and gitlab/github user sites, it almost worked to use /, but due to the way the internal template for integrating disqus provides the url (using the .Permalink variable), if baseURL is relative, then so will be the url provided to disqus, which keeps it from embedding properly.

In the case of gitlab and github project sites, the site URL becomes something like http://name.gitlab.io/project/ so having the baseURL as / led to bad links. Obvious now, but I for some reason just thought everything would magically work with / getting interpreted as project root and the site somehow knowing to prepend the directory part of the initial url. Stopping to think about it though - don’t see how it could. I suppose this partly goes back to root relative urls getting peppered through things vs. more disciplined usage of relative urls.

Regardless, the easy fix in both deploy situations was to use the hugo command line base url arg, like so: -baseURL=https://myorg.gitlab.io/projectname/, in my CI build instructions. That was stuck in .gitlab-ci.yml in my case for gitlab.

and -baseURL=https://rob.loc.net/ for netlify.

I am still not sure I should be putting the http(s): part in the url, but I saw no examples with anything that was just like //rob.loci.net/. It seems to work as far as basic site gen with hugo is concerned, but disqus still won’t load with it not having the http: or https: at the start.

I thought I ran into an issue with not having a trailing slash on baseURL, at least in the config.toml, though it seemed to work fine using --baseURL=mymachinename.local with hugo server on the command line, so not sure if it always in all cases adds a / if one isn’t already on the baseURL, or not.

Other Gitlab CI and Netlify deploy notes:

The most popular Hugo Docker image publysher/hugo was recently updated to latest hugo and includes git, but examples exist to use a small base image then manually add hugo should the need arise.

Git submodules

I have a git submodule in my project. It contains the theme, which I host separately on github as a fork from the original dev. I found that while netlify automatically pulled the submodule contents during it’s build step (kudos to netlify on that 👍), gitlab does not. However, since current versions of the docker image contain git, I was able to just do this in my .gitlab-ci.yml script:

image: publysher/hugo

pages:
    script:
    - git submodule update --init --recursive
    - hugo --baseURL="https://intelligence.gitlab.io/musings/"
    artifacts:
      paths:
      - public
    only:
    - master

There are alternate approaches to do it in a before-script section. Since there’s just one job, I didn’t see any difference.

Checking progress was easy on both platforms.

Just go to the pipeline view in gitlab, click on the build status button, and you can see it running live. Cool.

On Netlify, same sort of thing, but is even simpler. It’s a nice interface.

Netlify setup

In general, I’m really impressed with netlify. They have a pretty polished setup. I still have to go through the hooks and triggers stuff to try out the deploy preview stuff with slack, etc. integration. And I’d like to try out the Pro tier’s git branch support. It’d be nice if there were ez-button type help with some of those integrations similar to what they have with the rest of site setup, but not sure how possible that’d be. update: I set up notifications, etc. and it was pretty straightforward.

I am trying out their pro plan using the new (awesome) free for non-commercial / open source feature. I note that they don’t have password support show up on their dashboard like they are supposed to - I haven’t contacted them about it. I am guessing they took that out of the pro tier if you are using it for free. Too bad, because I can definitely see it being useful for branch-deploys in particular as well as internal portions of a site.

Other notes

Hugo on Sierra

Turns out the 4th beta of Sierra broke go for a while, which in turn breaks Hugo.

I started having lots of issues with livereloading and hugo crashing during site (re)gen, to the point where I’d have to rerun the hugo server command after most changes, and run it more than once often, till it got through without crashing.

I had installed using brew, but I couldn’t really (easily) use it to update to a patched version of go because it had to be applied manually. I ended up installing a binary build from the Go site, which worked fine, but then wouldn’t work with brew to allow me to recompile Hugo. I’m sure I could have figured that out if I had more brew packaging and use experience, but since I used brew to make it easier, I didn’t want to take the time to do that vs. just get back to work. So I used go’s package facility to grab, build, and install hugo and it was pretty painless.

Hugo config.toml differences

When trying out different themes, one annoying thing I discovered were different themes using varying ways of specifying commonly used options in the config.toml. For example, author info, copyright info, site description/about type stuff, social integration

Different themes obviously are going to have different configuration needs, but it’d be nice to see more common, best practice, type suggestions in the Hugo docs and to have theme authors pay more attention to them.

Hugo shortcodes

Odd thing I came across. I started using a blockquote shortcode and noticed if I didn’t have the named params (or at least the link param) followed by an = with no space between them, it would throw an error and not render the rest of the page. The error was (for example):

ERROR: 2016/08/13 11:14:52 shortcode.go:287: AI-Q&A-Yann-LeCun:19: got positional parameter 'link'. Cannot mix named and positional parameters.

I didn’t think whitespace should matter like that, but haven’t tracked down if it’s my misunderstanding, or something odd about that shortcode in particular.

Hugo, Shortcodes, & XKCD refs

rob@Loci.net (Rob Arnold) — Sun, 24 Jul 2016 00:00:00 +0000

Way back when I started with hugo, a few days ago, I said in this post that I really liked the xkcd footnote/reference popup/popover things[1]Like this! he uses in his “what if?” posts.

I decided to try to add them to Hugo, first just as part of a theme, then make it easier to use them by making a shortcode for them. After many travails*mostly due to either span/div hover issues with iOS, or history issues with an approach using anchor refs with a pure css approach, I realized that jQuery was already loaded in the theme I was using anyway, and that using the same approach they used would be simple and easy, and work on mobile as well as desktop (one of the issues I had with some pure CSS approaches)

After getting the span based html/css/js version working I went on to making a shortcode version so I could do something like this:

{{% refpo "[1]" "Like this!" %}}

vs. this

<span class="ref"><span class="refnum">[1]</span><span class="refbody">Like this!</span></span>

If the popup should have a larger chunk of text, links, etc. arbitrary markdown or html, I could do this:

{{% refpo "[2]" %}}Lots of stuff, with [links](http://www.xkcd.com) and some html <i>italic tags</i> etc.{{% /refpo %}}

Which would give me this[2]Lots of stuff, with links and some html italic tags etc. .

That is useful because Markdown isn’t rendered in the 2nd arg in the single shortcode version, though html is. For example same as above in single version[3]Lots of stuff, with [links](http://www.xkcd.com) and some html italic tags etc. .

Unfortunately, I ran into an issue where the non-paired version of the shortcode causes extra <p> tags to be placed around some of the shortcodes.[4]it p'd all over my code! . Apparently this is an ongoing and hard to eradicate set of issues, but also I’m new to hugo, go, and shortcodes so ~~it’s certainly possible~~ it’s definitely the case I’ve misunderstood something.

The shortcode is pretty simple and I’ve tried a few variations and not been able to avoid the extra <p> tags in any variant where I tried to accomplish both variations in one shortcode. For example,

<span class="ref"><span class="refnum">{{.Get 0}}</span><span class="refbody">{{ if len .Params | eq 2 }}{{.Get 1|safeHTML}}{{end}}{{ with .Inner}}{{ .|safeHTML}}{{end}}</span></span>

causes the issue. It seems that having .Inner is part of the trigger for the issue. I thought maybe I couldn’t test the existence of .Inner like that, so I tried this variant:

<span class="ref"><span class="refnum">{{.Get 0}}</span><span class="refbody">{{ if len .Params | eq 2 }}{{.Get 1|safeHTML}}{{end}}{{ if len .Inner}}{{ .Inner|safeHTML}}{{end}}</span></span>

But the actual issue turned out to be that the existence of .Inner in the shortcode itself (whether or not it has a value) is a flag of sorts to hugo which makes it consider the shortcode to be the paired type, as per discussion here. Apparently if you don’t then use closing tags, bad things happen ranging from the extra <p> codes to chunks of your text getting pulled into the shortcode. Once I knew that, I thought everything would be ok because I’d read

A shortcode with .Inner content can be used without the inline content, and without the closing shortcode, by using the self-closing syntax:
{{< innershortcode />}}

That quote uses the “shortcode without markdown syntax” rather than the “with markdown syntax”, but I figured it was the same for both. Either I was wrong about it working for the with markdown version, or something is wrong altogether, because when I do

{{% refpo "test1" "Some stuff" /%}}

I get a hugo error from the next shortcode about not having a closing shortcode*and actually, I get an error for the no markdown versions too, so clearly I'm assuming something that isn't true . But if I do:

    {{% refpo "test1" "Some stuff" %}}{{% /refpo %}}

Things work fine.

So, based on that, kinda makes the shortcode not so short for the simple case. So I broke down and made two different shortcodes*and changed the name while I was at it. Better? Meh, /shrug , poref for the simple, non-paired case, and porefx for the extended, paired version that can handle markdown, etc.

poref:

<span class="ref"><span class="refnum">{{.Get 0}}</span><span class="refbody">{{ if len .Params | eq 2 }}{{.Get 1|safeHTML}}{{end}}</span></span>

porefx:

<span class="ref"><span class="refnum">{{.Get 0}}</span><span class="refbody">{{ .Inner|safeHTML}}</span></span>

I’d considered using a scratch variable and making the refnum arg optional, with it counting up on its own if not provided, but I kind of like having arbitrary reference indicators, whether it’s 1, [1], *, or whatever. So I think I’ll call them done for now and move on.

I mean, it’s not groundbreaking or anything, but I think it’ll be handy. I’d prefer a shorter syntax more akin to markdown footnotes, but it’s not awful.

Now to work on the style a bit and figure out if I should use a different main font for the whole site - seeing too many jaggies for my taste here. I didn’t really notice it on the original HTML5 UP theme, so need to investigate.

Disclaimer

rob@Loci.net (Rob Arnold) — Fri, 22 Jul 2016 00:00:00 +0000

Oh, hey. Didn’t expect anyone.
Oh yeah, first post and all.

So look, I’m jotting down things sometimes, as I think of them. I’m just a guy, not an expert about, well, pretty much anything. I mean, I’ve read a lot, but many have read more. I tend to soak up a lot of knowledge - but I’m sure some of it is wrong, even if I correctly understood it. Bottom line, this is just me talking. Take it with a lump of salt. But maybe it’ll make you think too, or you’ll find something useful.

That’d be cool.

What’ll I be talking about? Well, I don’t know. Since it’s fresh on my mind, I’m sure early on there will be a lot about the details of the site itself and my experiences with Hugo (and whatever else I try), hosting, etc. But past that, mostly just random thoughts and experiences. See /about/ for more.