I’ve been messing about some things behind the curtains:

Theme changes

I wanted to use a Hugo theme for documentation (structured documents), if possible with an associated blog for less structured content.
My wishlist was (in no particular order):

• Light / dark theme
• Multilanguage (i18n)
• Several independent sections
• Ability to include in the code boxes not only line numbers but also prompts outside of the text, so that they were ignored when copying the contents of the box
• Have command output boxes with distinct formatting

I only found this theme, Zdoc, that had most of it (Docz seems to be shaping up as an alternative), but it still lacks a lot:

• Doesn’t support command output boxes
• Only includes the prompts $ and > (and I also needed #, PS andPS#)
• Could not insert external configuration files inline with the page text
• Doesn’t have a button to copy the contents of a code box

By the way, no single Hugo theme has all these features

Command output

I solved this with a shortcode and inline CSS formatting

1
2

  <pre style="font-style: italic; font-size: 0.79rem">
    {{.Inner}}</pre>

Output...

Prompts for root, PowerShell and PowerShell admin

Not something to be overly proud of, the original code was drop-dead easy to copy-paste and fiddle with some values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

var hashCodeElem = document.querySelectorAll('div.language-\\#');

hashCodeElem ?
hashCodeElem.forEach(function(elem) {
    var lnts = elem.parentNode.parentNode ? elem.parentNode.parentNode.querySelectorAll('.lnt') : null;
    lnts ? 
    lnts.forEach(function(lnt) {
      lnt.innerHTML = '#<br/>';
    }) : null;
}) : null;

var psCodeElem = document.querySelectorAll('div.language-\\ps');

psCodeElem ?
psCodeElem.forEach(function(elem) {
    var lnts = elem.parentNode.parentNode ? elem.parentNode.parentNode.querySelectorAll('.lnt') : null;
    lnts ? 
    lnts.forEach(function(lnt) {
      lnt.innerHTML = 'PS><br/>';
    }) : null;
}) : null;
    
var psadmCodeElem = document.querySelectorAll('div.language-\\psa');

psadmCodeElem ?
psadmCodeElem.forEach(function(elem) {
    var lnts = elem.parentNode.parentNode ? elem.parentNode.parentNode.querySelectorAll('.lnt') : null;
    lnts ? 
    lnts.forEach(function(lnt) {
      lnt.innerHTML = 'PS#<br/>';
    }) : null;
}) : null;

1

rm -rf /

1

Stop-Computer

1

Stop-Computer -Computer DC01

Insert external text files

I could not get what I wanted but I’ve made do with:

• A shortcode to read an external file and put it inside a Code Fence:

1
2
3
4

<!--https://stackoverflow.com/a/45421343-->
{{ $file := .Get "file" | readFile }}
{{ $lang := .Get "language" }}
{{ (print "```" $lang "\n" $file "\n```") | markdownify }}

• Placed inside an expand shortcode (included with Zdocs) to create a dropdown
• Which is preceded by a link to download the file.
  All these shenanigans were needed because of the next problem.

Copying code blocks

I could not get around this. Because of the processing that the theme does to code fences to insert the prompts, all the code I found to do this fails because it tries to copy the text from the wrong place or puts the Copy button on the wrong place.
And since CINEL, bless their hearts, did not teach me CSS or DOM structure (the first year in which they stopped teaching this in my specific course), I’m a bit lost because I still haven’t grokked it.

Title font change

The original title font of the theme was Montserrat, which was graphically very interesting, but I found that in the Black-900 weight that was being used it unbalanced the page and made reading difficult (so, too much interesting…).
I changed it to the font MPlus.

Content

Developing content to put here has been harder than I thought (also, I have a day job now). Most of what I had ready was developed as part of my Net/Sysadmin training, and I can’t very well publish it and solve everything for the new students that come through!
I’m trying to filter the most advanced stuff that was icing on my projects and that won’t sell the farm.
Meanwhile, I’m preparing a series of articles on Public Key Infrastructure
Keep in touch.

Schedule

I’m going to stagger the content; each article will appear first on the Portuguese side of the site, and the following week a translated version will appear on the English side (along with a debugged Portuguese version).
I’m aiming to publish new articles every other week