Hugo

As promised, on this post I’m going to explain how I’ve configured this blog using hugo, asciidoctor and the papermod theme, how I publish it using nginx, how I’ve integrated the remark42 comment system and how I’ve automated its publication using forgejo and json2file-go. It is a long post, but I hope that at least parts of it can be interesting for some, feel free to ignore it if that is not your case …​ :wink: Hugo ConfigurationTheme settingsThe site is using the PaperMod theme and as I’m using asciidoctor to publish my content I’ve adjusted the settings to improve how things are shown with it. The current config.yml file is the one shown below (probably some of the settings are not required nor being used right now, but I’m including the current file, so this post will have always the latest version of it): config.yml baseURL: https://blogops.mixinet.net/ title: Mixinet BlogOps pagination: pagerSize: 5 theme: PaperMod destination: public/ enableInlineShortcodes: true enableRobotsTXT: true buildDrafts: false buildFuture: false buildExpired: false enableEmoji: true pygmentsUseClasses: true minify: disableXML: true minifyOutput: true languages: en: languageName: "English" description: "Mixinet BlogOps - https://blogops.mixinet.net/" author: "Sergio Talens-Oliag" weight: 1 title: Mixinet BlogOps params: homeInfoParams: Title: "Sergio Talens-Oliag Technical Blog" Content: >  taxonomies: category: categories tag: tags series: series menu: main: - name: Archive url: archives weight: 5 - name: Categories url: categories/ weight: 10 - name: Tags url: tags/ weight: 10 - name: Search url: search/ weight: 15 outputs: home: - HTML - RSS - JSON params: env: production defaultTheme: light disableThemeToggle: false ShowShareButtons: true ShowReadingTime: true disableSpecial1stPost: true disableHLJS: true displayFullLangName: true ShowPostNavLinks: true ShowBreadCrumbs: true ShowCodeCopyButtons: true ShowRssButtonInSectionTermList: true ShowFullTextinRSS: true ShowToc: true TocOpen: false comments: true remark42SiteID: "blogops" remark42Url: "/remark42" profileMode: enabled: false title: Sergio Talens-Oliag Technical Blog imageUrl: "/images/mixinet-blogops.png" imageTitle: Mixinet BlogOps buttons: - name: Archives url: archives - name: Categories url: categories - name: Tags url: tags social: true socialIcons: - name: CV url: "https://www.uv.es/~sto/cv/" - name: Debian url: "https://people.debian.org/~sto/" - name: GitHub url: "https://github.com/sto/" - name: GitLab url: "https://gitlab.com/stalens/" - name: Linkedin url: "https://www.linkedin.com/in/sergio-talens-oliag/" - name: RSS url: "index.xml" assets: disableHLJS: true favicon: "/favicon.ico" favicon16x16: "/favicon-16x16.png" favicon32x32: "/favicon-32x32.png" apple_touch_icon: "/apple-touch-icon.png" safari_pinned_tab: "/safari-pinned-tab.svg" fuseOpts: isCaseSensitive: false shouldSort: true location: 0 distance: 1000 threshold: 0.4 minMatchCharLength: 0 keys: ["title", "permalink", "summary", "content"] markup: asciidocExt: attributes: {} backend: html5s extensions: ['asciidoctor-html5s','asciidoctor-diagram'] failureLevel: fatal noHeaderOrFooter: true preserveTOC: false safeMode: unsafe sectionNumbers: false trace: false verbose: false workingFolderCurrent: true privacy: vimeo: disabled: false simple: true twitter: disabled: false enableDNT: true simple: true instagram: disabled: false simple: true youtube: disabled: false privacyEnhanced: true services: instagram: disableInlineCSS: true twitter: disableInlineCSS: true security: exec: allow: - '^asciidoctor$' - '^dart-sass-embedded$' - '^go$' - '^npx$' - '^postcss$' Some notes about the settings: disableHLJS and assets.disableHLJS are set to true; we plan to use rouge on adoc and the inclusion of the hljs assets adds styles that collide with the ones used by rouge.ShowToc is set to true and the TocOpen setting is set to false to make the ToC appear collapsed initially. My plan was to use the asciidoctor ToC, but after trying I believe that the theme one looks nice and I don’t need to adjust styles, although it has some issues with the html5s processor (the admonition titles use <h6> and they are shown on the ToC, which is weird), to fix it I’ve copied the layouts/partial/toc.html to my site repository and replaced the range of headings to end at 5 instead of 6 (in fact 5 still seems a lot, but as I don’t think I’ll use that heading level on the posts it doesn’t really matter).params.profileMode values are adjusted, but for now I’ve left it disabled setting params.profileMode.enabled to false and I’ve set the homeInfoParams to show more or less the same content with the latest posts under it (I’ve added some styles to my custom.css style sheet to center the text and image of the first post to match the look and feel of the profile).On the asciidocExt section I’ve adjusted the backend to use html5s, I’ve added the asciidoctor-html5s and asciidoctor-diagram extensions to asciidoctor and adjusted the workingFolderCurrent to true to make asciidoctor-diagram work right (haven’t tested it yet)....

Welcome to my new Blog for Technical Stuff. For a long time I was planning to start publishing technical articles again but to do it I wanted to replace my old blog based on ikiwiki by something more modern. I’ve used Jekyll with GitLab Pages to build the Intranet of the ITI and to generate internal documentation sites on Agile Content, but, as happened with ikiwiki, I felt that things were kind of slow and not as easy to maintain as I would like. So on Kyso (the Company I work for right now) I switched to Hugo as the Static Site Generator (I still use GitLab Pages to automate the deployment, though), but the contents are written using the Markdown format, while my personal preference is the Asciidoc format. One thing I liked about Jekyll was that it was possible to use Asciidoctor to generate the HTML simply by using the Jekyll Asciidoc plugin (I even configured my site to generate PDF documents from .adoc files using the Asciidoctor PDF converter) and, luckily for me, that is also possible with Hugo, so that is what I plan to use on this blog, in fact this post is written in .adoc. My plan is to start publishing articles about things I’m working on to keep them documented for myself and maybe be useful to someone else. The general intention is to write about Container Orchestration (mainly Kubernetes), CI/CD tools (currently I’m using GitLab CE for that), System Administration (with Debian GNU/Linux as my preferred OS) and that sort of things. My next post will be about how I build, publish and update the Blog, but probably I will not finish it until next week, once the site is fully operational and the publishing system is tested. Spoiler Alert: This is a personal site, so I’m using Forgejo to host the code instead of GitLab. To handle the deployment I’ve configured json2file-go to save the data sent by the hook calls and process it asynchronously using inotify-tools. When a new file is detected a script parses the JSON file using jq and builds and updates the site if appropriate.