From e0fd5578d2e9b435019a662a78085b00f5177e45 Mon Sep 17 00:00:00 2001 From: Julien Dessaux Date: Mon, 22 Mar 2021 22:58:22 +0100 Subject: Reworked some docs _index and added an article on hugo shortcodes --- content/blog/hugo/adding-custom-shortcode-age.md | 36 +++++++++++++ content/blog/hugo/ditching-the-heavy-hugo-theme.md | 37 +++++++++++++ content/blog/hugo/switching-to-hugo.md | 60 ++++++++++++++++++++++ .../miscellaneous/ditching-the-heavy-hugo-theme.md | 37 ------------- content/blog/miscellaneous/switching-to-hugo.md | 60 ---------------------- content/docs/_index.md | 4 +- content/docs/adyxax.org/_index.md | 10 ++-- content/docs/adyxax.org/services/www.md | 2 +- layouts/shortcodes/print.html | 1 + 9 files changed, 143 insertions(+), 104 deletions(-) create mode 100644 content/blog/hugo/adding-custom-shortcode-age.md create mode 100644 content/blog/hugo/ditching-the-heavy-hugo-theme.md create mode 100644 content/blog/hugo/switching-to-hugo.md delete mode 100644 content/blog/miscellaneous/ditching-the-heavy-hugo-theme.md delete mode 100644 content/blog/miscellaneous/switching-to-hugo.md create mode 100644 layouts/shortcodes/print.html 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 >}} diff --git a/content/blog/miscellaneous/ditching-the-heavy-hugo-theme.md b/content/blog/miscellaneous/ditching-the-heavy-hugo-theme.md deleted file mode 100644 index 12a052f..0000000 --- a/content/blog/miscellaneous/ditching-the-heavy-hugo-theme.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -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/miscellaneous/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/miscellaneous/switching-to-hugo.md b/content/blog/miscellaneous/switching-to-hugo.md deleted file mode 100644 index dc2841f..0000000 --- a/content/blog/miscellaneous/switching-to-hugo.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -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 >}} diff --git a/content/docs/_index.md b/content/docs/_index.md index 03907d3..740a710 100644 --- a/content/docs/_index.md +++ b/content/docs/_index.md @@ -5,6 +5,6 @@ menu: weight: 2 --- -This is the Docs section of this website. It is an heritage of the old wiki I maintained, with information that does not really fit in a blog format. +This is the Docs section of this website. It is an heritage of the old wiki I maintained before switching to a static website generated with [hugo]({{< relref "/tags/hugo/" >}}), with information that does not really fit in a blog format. -The information is organised in the following sections : +It is organised in the following sections : diff --git a/content/docs/adyxax.org/_index.md b/content/docs/adyxax.org/_index.md index 9d7b25d..ea9b904 100644 --- a/content/docs/adyxax.org/_index.md +++ b/content/docs/adyxax.org/_index.md @@ -5,18 +5,20 @@ description: a set of pages about the computer infrastructure powering this webs ## What is adyxax.org? -adyxax.org is very much like a small personnal cloud of inexpensive servers hosted here and there. I am using my experience as a +adyxax.org is very much like a small personnal cloud of inexpensive servers hosted here and there. I am using my experience as a professional sysadmin to make it all work and provide various services that are useful to me and people that are close to me. As a good sysadmin, I am trying to be lazy and build the most self maintainable solution, with as little maintenance overhead as possible. It used to rely on mostly gentoo (and some optional openbsd) servers interconnected with point to point openvpn links. Services ran inside lxd on alpine linux containers. Communications between all those services work thanks to dynamic routing with bird and ospf along those openvpn links. I made extensive use of ansible to orchestrate all that, deploy the containers and manage them. -Even though it worked really well for years, I do not plan to blog a lot about this setup... but that can change if someone interested writes me at julien -DOT- dessaux -AT- adyxax -DOT- org. On this new documentation site I plan to focus on how I am migrating some of it on kubernetes, because even if it has always worked well it still is a rather unusual infrastructure. Even if I am proud of it, it is stable and easy and comfortable... It is not good for me to not look deeper into new technologies. Gentoo, OpenBSD and LXD is not the most popular combination out there. I will not abandon it completely, but working on more employable skills will do me good. +Even though it worked really well for years, I do not plan to blog a lot about this setup unless someone interested writes me to request information about it. On this new documentation site I plan to focus on how I am migrating the most stable and boring parts on OpenBSD hosts (so without containerisation). The less important or more changing services will be migrated on [kubernetes]({{< relref "/tags/kubernetes/" >}}) as a learning experience. Even though my custom setup with lxd on gentoo has always worked well it still was a rather unusual design that sometimes required maintenance following updates. Even if I am proud of its stability and reliability... It is not good for me to not look deeper into new technologies. Gentoo, OpenBSD and LXD is not the most popular combination out there. I will not abandon it completely (I do not imagine my laptop running anything other than gentoo), but working on more employable skills will do me good. ## Why write about it? -As a system and network administrator I believe I have a deep understanding of linux and other unix like operating systems, networking and storage, and even with all that knowledge and experience getting on kubernetes is hard. Deploying kubernetes itself is not hard, but there are so so many choices that you make each steps of the way that will define how hard it is going to be to maintain and debug. Choosing what kubernetes flavor to deploy is one tough choice, choosing how to deploy it is another. Then choosing your network provider is a juicy one, so many subtle differences come into play! +As a system and network administrator I believe I have a deep understanding of linux and other unix like operating systems, networking and storage, and even with all that knowledge and experience getting on kubernetes is hard. Deploying kubernetes itself is not hard, but there are so so many choices that you make each steps of the way that will define how maintainable and debuggable it will be. Choosing what kubernetes flavor to deploy is one tough choice, choosing how to deploy it is another. Then choosing your network then storage providers are a juicy ones too, so many subtle differences come into play! -I believe there are way too many blogs that focus on the hello world aspects and quick and dirty deployments... and those come out way too often in google search results. Writing about the choices I made will also help me reflect on them as this infrastructure evolves and grows. +On a personal note I also believe there are way too many blogs that focus on the hello world aspects and quick and dirty deployments that show up in google results, I will try to change that a bit. Writing about the choices I made will also help me reflect on them as this infrastructure evolves and grows. + +## Subsections diff --git a/content/docs/adyxax.org/services/www.md b/content/docs/adyxax.org/services/www.md index 852cfcc..3f52e97 100644 --- a/content/docs/adyxax.org/services/www.md +++ b/content/docs/adyxax.org/services/www.md @@ -10,7 +10,7 @@ This is the website you are currently reading. It is a static website built usin 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. -For a log of how I made the initial setup, see [this blog article.]({{< relref "/blog/miscellaneous/switching-to-hugo.md" >}}) +For a log of how I made the initial setup, see [this blog article.]({{< relref "/blog/hugo/switching-to-hugo.md" >}}) ## Installing hugo diff --git a/layouts/shortcodes/print.html b/layouts/shortcodes/print.html new file mode 100644 index 0000000..8ed1b70 --- /dev/null +++ b/layouts/shortcodes/print.html @@ -0,0 +1 @@ +{{ index .Params 0 }} -- cgit v1.2.3