In the continuing saga of this humble website: I have changed the underlying
tech stack again, this time to use Next.js. I am aware that many (most?) of the
posts on this site are related to changing the site itself but since the
intention of this site is to try out new things I am trying not to feel self
conscious about it.




## Why the switch?

The most recent change to [this site was moving from Hugo to
Gatsby](/blog/post/2020/05/switching-to-gatsby). That
previous move was moving towards something more familiar with using React since
I have been using React for the day jobs for the past few years. After moving
to Gastsby I found that I didn't like the GraphQL parts of making changes to
the site. I think that this difficultly was largely from my own lack of
experience with the technology.

Another reason for the switch was the generated TypeScript types generated from
the GraphQL types were large and change superficially frequently making it more
difficult to use.


## Cool things

### All of the cool things from the previous Gatsby rewrite

This incarnation of the site looks mostly the same as the Gatsby version of the
site. This is because it uses the same React components that the Gatsby version
does and changes the data loading to be via the `getStaticProps` and
`getStaticPaths` methods (these are the methods that Next.js uses to generate
pages at build time).


### More control of markdown processing

Previously all of the processing of markdown was happening within Gatsby
plugins. This was really nice from the perspective of getting a lot out of the
box, but meant that some aspects were more difficult to control. This Next.js
approach uses [`markdown-it`](https://github.com/markdown-it/markdown-it) to
process the markdown in a opinionated and extendable way.


## Wrapping up

I am hoping that this change will make it easier to make changes to the site. Perhaps someday I'll use this site to tell stories about other projects rather than use the site to tell stories about itself. 🤞.

Switching to Next.js

This past week I decided to spend some time switching this website to use
Gatsby. This comes on the heels of switching to Hugo at the end of last year.




## Why the switch?

No big grand reason. The biggest reason to make the switch was my experience
with React compared to the Hugo templating. It feels nice to use similar tools
to what I use day to day and feel like I have more control over the look of the
site.

I first worked with Gatsby for a friends wedding website and was really pleased
with it. It's got some very impressive things built in like prefetching links,
and image preprocessing (with cool things like "blur up" where the image first
loads as a minimal blurry base64 equivalent while the full image loads). One of
the things that also encouraged me to make the switch was Gatsby's excellent
docs.

## Cool things

### Automatic dependency updates

The JavaScript ecosystem contains many small packages and changes rapidly. To
help keep up with that there are systems like Dependabot which will open PRs on
the GitHub repo periodically. Normally it's up to people to review these and
merge the changes.

For this repo I decided to try our a service called
[Mergify](https://mergify.io/). It will read a configuration with a set of
rules and will merge dependency pull requests without any human interaction if
the tests pass!

An example of this can be seen
[here](https://github.com/hockeybuggy/hockeybuggy.com/pull/69). Notice that
this was opened by a bot and merged by a bot once the tests passed.


### End to End tests

The "automatic dependency updates" could be a really good way for this site to
break without noticing nice not every dependency is a non-breaking change. In
order to catch the site breaking before merging these changes in this static
site now has tests that fires up a headless browser and checks that the page renders.

This project has a [GitHub
action](https://github.com/hockeybuggy/hockeybuggy.com/actions?query=workflow%3A%22end+to+end+tests%22+branch%3Amaster)
that runs this process. The tests take screen shots while it's running of
various pages. These are collected as build artifacts.


## Wrapping up

Hugo had some really good things going for it. I will miss it's single
executable (since setting up a node environment can occasionally by tricky).
Thanks to the contributors of Hugo as well as the authors of the `hugo-coder`
theme that I recreated here.

Looking forward to continuing to improve the site and writing about it as well
as looking forward to learning more about Gatsby.  Hopefully I'll also write
about other things (other than my lovingly over-built simple website).

Switching to Gatsby

I haven't written anything in my blog for a little while.  I don't really feel
bad about it, but one of the things that I feel prevented me from writing new
things here was that I had some troubles with my previous static site generator
[Jekyll][JEKYLL]. Last week I switched this site over to use [Hugo][HUGO].

[JEKYLL]: https://jekyllrb.com/
[HUGO]:  https://gohugo.io/




## What I like more about Hugo

One of the biggest issues I had with Jekyll was how difficult it was to setup
on a new machine. I am not a Ruby developer (although I know enough Python and
have seen enough Smalltalk to fake it) and so setting up a Ruby interpreter
with `rvm` and getting Bundler setup was quite difficult when all I wanted to
do was write prose. Hugo on the other hand has a single executable. This means
that even though Hugo is written in Go I don't have to have Go setup on the
machine I want to write on. Instead I can just install an executable from my
package manager.

One other thing that I like about Hugo is that it supports [`.toml`
front-matter][TOML] on posts. Not really the biggest of deals, but I am not
wild about `.yml` so this is a nice way to stick with something more familiar.

Finally one of the nicest things about Hugo is the automatic reloading when in
development mode. This feature injects a script that will reload the page is
anything in the file system that it's watching changes. This is really nice
while authoring since it allows you to not have to switch out of your editor to
see rendered changes.

[TOML]: https://github.com/toml-lang/toml


## What was the process 

To perform the switch I used [the `hugo import jekyll`
tool](https://gohugo.io/commands/hugo_import_jekyll/). This tool did a great
deal of the work as it copied over most of the posts and setup a new Hugo site.

After that I removed a number of blog posts that I had written a while ago and
didn't feel so bad about having them fall off the internet (they are archived;
I checked).

Then I went from blog post to blog post and for each:

1. Switched the front-matter from YAML to TOML.
2. Set up aliases so that old urls to live posts will still work.
3. Added some tags and categories.

Finally I made sure that pages looked ok and that static files like the RSS
feed, the `humans.txt` and the `robots.txt` loaded.

Finally I went ahead and made the switch by merging [merged the
branch](https://github.com/hockeybuggy/hockeybuggy.com/pull/46).


------

Thanks Jekyll and the people who support it for helping me build my site for so
long. Thank you Hugo contributors for building a tool so nice that it made it
feel like it was worth finally switching.

Migrated to Hugo Static Site generator

Today I made a change to this blog. I hope that you can't see the difference
between the site now and an archived copy from [last month][archive]. The
change that I made (as you may be able to tell from the title) was to add
semantics to the site.

I was prompted to add semantics after giving some thought to how accessible my
site was to people who use screen readers. After doing some research I realized
that by changing some of my markup and less of my CSS the site would be able to
be better traversed by screen readers. I did quite a bit of my research at
[html5doctor][html5doc]. Here is a summary of the changes I made:




## Landmarking elements

Some elements exist on most websites. Screen readers allow people to jump
between these common elements using semantic tags that perform the same role on
every tag.

### header

The top of the page that in my case includes the title and the navigation bar.

### nav

The unordered list of links to other sections of the page. The tag for this is
\<nav\>.

### footer

The bottom of the page that in my case includes links to the rss feed, twitter,
and Github.

### main

This tag denotes the main section of the page. On each page this is the section
that is light-blue.

### article and section

These tags denote an atom of the page. Each of the *section*s denote a
particular area of the page. The article tag is a particular type of section.
To decide wither I should have used one or the other I looked [here][artVsSec]

## Improving SEO

This is not just an improvement for people using screen readers, but for
everyone. When I searched for my page on the one search engine *to rule them
all* I saw that the listing for my homepage looked really ugly. All of my other
pages had enough content to look ok but because my homepage was just a list of
other pages it looked like this:

![Image of my homepage's Google results before the change][SEOimage_before]

The 'fix' for this was to add a small paragraph of text explaining the intent
of this site. The listing now looks like this:

![Image of my homepage's Google results after the change][SEOimage_after]

---------

Note = I do recognize the irony of having a picture of words on a page that
discusses making the site better for screen readers. If you are reading this on
a screen reader = Sorry.


[archive]: https://web.archive.org/web/20140517102136/http://hockeybuggy.com/
[html5doc]: https://html5doctor.com/
[aria]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
[artVsSec]: http://www.brucelawson.co.uk/2010/html5-articles-and-sections-whats-the-difference/

[SEOimage_before]: /static/img/blog/2014-06-23-misc_2en5AjCl/SEO_before.jpg
[SEOimage_after]: /static/img/blog/2014-06-23-misc_2en5AjCl/SEO_after.jpg

Adding Semantics

Around the beginning of April last year I started to have problems generating
my site from it's source code. At the time it was using [Pelican][PELICAN] and
was somewhat enjoying what it provided. However then it stopped working.

For some time I was having problems working on the site on different computers.
I was using virtualenv to create little bubbles to work on the website from
within but it was proving to be more effort than it was worth. But when site
broke on the computer it original worked on, I become determined to find a new
static site generator.




## Why Jekyll

And now after what has been far to long a time I have decided to move my old
posts to [Jekyll][JEKYLL]. Jekyll seems to be by far the most used static site
generator likely thanks to it adoption by [Github][GITHUB].

I really like Jekyll's approach to static site generation. When using the
Jekyll tool to create a new site I found that it did not take many assumptions
as to how I would like the site to be laid out. I also enjoyed having all most
of the files in the root of the project.

## New Face

So now that I have to redo all of my markup I figured it was time for a new
face for the site. I keep the same colour scheme(borrowed from:[here][COLOUR])
and added some icons in the footer.

[PELICAN]: https://docs.getpelican.com
[JEKYLL]: https://jekyllrb.com
[GITHUB]: https://pages.github.com
[COLOUR]: https://bit.ly/9oo0N3

Migrated to Jekyll

So if you have seen the site before this post you will have noticed that we(the
royal we [aka. we := I ])
have gone though (and are going though) some changes in the layout of the site.




This new change is a result of changing from the static css about a week ago. I
knew that pelican had picked up less support but I did not realize the extent
of the power of the webassets module. I wanted to start with precompiled css
language and I picked up less first. I Started to used it and recreated my
previous css quickly in fewer lines. But as I used it more and did more
research on scss I started to think about how the syntax is nice.

Why do I prefer scss? Here are my thoughts:

## Reason number 1:

I prefer the usage of the '@mixin' and '@include' keywords that sass uses.
The alternative syntax for less would be a mixin name prefixed by a period
followed by parentheses. eg.

### LESS

    #container {
        color: black;
        .rounded-corners(10px);
    }
    .rounded (@radius: 5px){
        border-radius: @radius;
        -moz-border-radius: @radius;
        ...
    }

vs.

### SCSS

    #container {
        color: black;
        @include rounded-corners(10px);
    }
    @mixin rounded ($radius: 5px){
        border-radius: $radius;
        -moz-border-radius: $radius;
        ...
    }

When you are scanning though your code it would be nice to be able to see
things as context free as possible so going through the hassle of writing more
with scss is some-what worth it.

## Reason number 2: 

I like '$' more the '@'.  @ is two keys farther away from the
middle the $ which makes it kinda annoying when you are typing in a lot.

A new a stylish look around the site. Thanks to sass

It is finally time to publish this website. I do not imagine that it is anyway
complete. However I really do want to have something existent up and online.

Things that still need to happened for the site is it still needs a slightly
nicer colour scheme. I however do not really have an overwhelmingly strong
sense of style.

7 posts in the category "meta"