Reworked some docs _index and added an article on hugo shortcodes

3 files changed, 133 insertions, 0 deletions

diff --git a/content/blog/hugo/adding-custom-shortcode-age.md b/content/blog/hugo/adding-custom-shortcode-age.md
new file mode 100644
index 0000000..d694813
--- /dev/null
+++ b/content/blog/hugo/adding-custom-shortcode-age.md
@@ -0,0 +1,36 @@
+---
+title: "Adding a custom hugo markdown shortcode to calculate an age"
+date: 2021-03-22
+description: An example of custom hugo shortcode
+tags:
+  - hugo
+---
+
+## Introduction
+
+On the [about-me]({{< relref "/docs/about-me/_index.md" >}}) page I had hardcoded my age. I wanted a way to calculate it automatically when building the site, here is how to do this.
+
+## Adding the shortcode
+
+Added a custom markdown shortcode in hugo in as simple as creating a `layouts/shortcodes/` directory. Each html file created inside will define a shortcode from the filename. In my example I want to calculate my age so I named the shortcode `age.html` and added the following simple template code :
+
+{{< highlight html >}}
+{{ div (sub now.Unix 493473600 ) 31556926 }}
+{{< / highlight >}}
+
+The first number is the timestamp of my birthday, the second represents how many seconds there are in a year.
+
+## Using the shortcode
+
+With this `layouts/shortcodes/age.html` file I can just add the following in a page to add my age :
+
+{{< highlight html >}}
+{{< print "{{% age %}}" >}}
+{{< / highlight >}}
+
+And if you are wondering how I am able to display a shortcode code inside this page without having it render, it is because I defined another shortcode that does exactly that [here](https://git.adyxax.org/adyxax/www/src/branch/master/layouts/shortcodes/print.html)! Hugo really is a powerful static website generator, it is amazing.
+
+## References
+
+  * https://gohugo.io/content-management/shortcodes/
+  * https://github.com/gohugoio/hugo/issues/7561
diff --git a/content/blog/hugo/ditching-the-heavy-hugo-theme.md b/content/blog/hugo/ditching-the-heavy-hugo-theme.md
new file mode 100644
index 0000000..8c56d0c
--- /dev/null
+++ b/content/blog/hugo/ditching-the-heavy-hugo-theme.md
@@ -0,0 +1,37 @@
+---
+title: "Ditching the heavy hugo theme"
+date: 2021-03-12
+description: I needed to trim the fat from this blog you are reading
+tags:
+  - hugo
+---
+
+## Introduction
+
+I felt a need for minimalism. I felt uneasy at the thought of 11 requests totalling about 750KB of minified files just to display a home page without any images, all that because of the docsy theme I went with when I [switched to hugo]({{< relref "/blog/hugo/switching-to-hugo" >}}) two years ago.
+
+I am not complaining about the theme which served me well when I needed to switch and was so focused on manually importing 10 years worth of wiki articles, but this uneasiness prevented me from updating this blog as often as I wanted. I was a bit ashamed about how heavy it was, and in some way prevented me from adding content to this website.
+
+## Learning CSS and hugo templating
+
+I searched the existing hugo themes without finding something light enough to satisfy me, so I did the next logical thing : search how to write my own theme, what it entails and try to estimate how long it is going to take me. There are basically three things to get a grasp on on :
+  - hugo templating and internals
+  - some html
+  - some css
+
+So that's how it went for about a week's worth of time taken here and there : plain old learning and experimenting! I learned myself some css and basic hugo templating to rebuild this website's design from the ground up and squeeze the home page down to only three requests weighing a little less than 5KB total. One could easily argue that the visual result is a little more austere but still like it. It's my own ugly baby know!
+
+I have to admit that I had severe misconceptions dating from about 10-15 years ago when I first did some html and css manually. The web was a very different place at that time, and even though I will never consider myself a web developer with how little I learned I am glad I pushed though these misconceptions and rediscovered these technologies with a fresh eye. Css really is not that hard nowadays and there is no longer a need for weird html tricks to ensure compatibility everywhere... the browser wars with internet explorer are far far behind us and that is a good thing.
+
+I hesitated with several of the lightest css frameworks and tried some, but none left me satisfied. These certainly have their place when working in teams on big projects but they were still too weird and I did not like using any of those (I tried purecss, bulma, foundation and skeleton). I finally went with the idea of doing it all by hand with just a few classes here and there, almost everything simply attached to html tags. I was so surprised when I read all the html elements that exist today which are so much more expressive than I expected! When reading the framework documentations there were either layers of divs everywhere or dozens of classes on every element, but it just seem so unnecessary to get a working website. There are tags like header, footer, main, article, aside etc that have real meaning, no need for div div div div div or class="this that also-that"!
+
+## Afterthoughts
+
+My pre-requisites for this blog were :
+  - a decent look on mobile, similar than on desktop
+  - rss feeds
+  - very light
+
+I added tags to all articles since I lost the search feature, but it was worthwhile to get rid of all the javascript on the website. I might work something out later to get a search feature, but in the meantime losing it is not a heavy price to achieve this degree of minimalism.
+
+You can check the repository [here](https://git.adyxax.org/adyxax/www), so light, so simple... I love it!
diff --git a/content/blog/hugo/switching-to-hugo.md b/content/blog/hugo/switching-to-hugo.md
new file mode 100644
index 0000000..dc2841f
--- /dev/null
+++ b/content/blog/hugo/switching-to-hugo.md
@@ -0,0 +1,60 @@
+---
+title: "Switching to Hugo"
+date: 2019-12-19
+description: I switched my personal wiki from dokuwiki to Hugo
+tags:
+  - hugo
+---
+
+## Introduction
+
+This is the website you are currently reading. It is a static website built using hugo. This article details how I installed hugo, how I initialised this website and how I manage it. I often refer to it as wiki.adyxax.org because I hosted a unique dokuwiki for a long time as my main website (and a pmwiki before that), but with hugo it has become more than that. It is now a mix of wiki, blog and showcase of my work and interests.
+
+## Installing hugo
+
+{{< highlight sh >}}
+go get github.com/gohugoio/hugo
+{{< / highlight >}}
+
+You probably won't encounter this issue but this command failed at the time I installed hugo because the master branch in one of the dependencies was
+tainted. I fixed it with by using a stable tag for this project and continue installing hugo from there:
+{{< highlight sh >}}
+cd go/src/github.com/tdewolff/minify/
+tig --all
+git checkout v2.6.1
+go get github.com/gohugoio/hugo
+{{< / highlight >}}
+
+This did not build me the extended version of hugo that I need for the [docsy](https://github.com/google/docsy) theme I chose, so I had to get it by doing :
+{{< highlight sh >}}
+cd ~/go/src/github.com/gohugoio/hugo/
+go get --tags extended
+go install --tags extended
+{{< / highlight >}}
+
+## Bootstraping this site
+
+{{< highlight sh >}}
+hugo new site www
+cd www
+git init
+git submodule add https://github.com/google/docsy themes/docsy
+{{< / highlight >}}
+
+The docsy theme requires two nodejs programs to run :
+{{< highlight sh >}}
+npm install -D --save autoprefixer
+npm install -D --save postcss-cli
+{{< / highlight >}}
+
+## hugo commands
+
+To spin up the live server for automatic rebuilding the website when writing articles :
+{{< highlight sh >}}
+hugo server --bind 0.0.0.0 --minify --disableFastRender
+{{< / highlight >}}
+
+To publish the website in the `public` folder :
+{{< highlight sh >}}
+hugo --minify
+{{< / highlight >}}