figueirego. – figueirego

Building my blog, part 1: writing without running a backend

Tue, 13 Oct 2026 12:03:00 -0300

This blog starts with text files. Hugo reads those files, applies the layouts, and generates the pages delivered to the browser. I do not need to run a publishing API or my own database to serve the articles.

That was the main requirement when I started: I wanted somewhere to explain what I build, record decisions, and return to them later. I also wanted it to carry the figueirego identity, feel comfortable on a phone, and support reading in Portuguese or English.

Between the first reference and the published version, I had to make decisions about design, navigation, comments, search, hosting, and images. I split the story into three parts so that each responsibility has room for a proper explanation:

Architecture: why I chose this foundation and what each component does.
The reading experience: organization, languages, search, themes, and comments.
Publishing and operations: from Markdown to the live website, including images and analytics.

Akita was the reference; the result needed to be mine

The starting point was Fabio Akita’s Meu Novo Blog — Como Eu Fiz. What interested me was his choice to publish Markdown files as a static site and reduce the work involved in maintaining a custom blog engine. The priority was being able to write.

I liked the technical approach, but wanted a different visual direction: my website’s colors, my brand, and an organization suited to the content I intend to produce. Separating those decisions helped. Choosing Hugo did not require reproducing another blog’s appearance.

I also had to clear up the names early on: Hugo is the generator; Hextra is the theme. Hugo is written in Go. Hextra provides layouts and features to build on. The Hextra repository documents that relationship.

What happens when someone opens an article

The page has already been generated when the reader arrives. The host serves HTML, CSS, JavaScript, and the necessary assets. There is no query to my own database to assemble the article on every request.

The main path looks like this:

Markdown text + metadata + layouts
 ↓
 Hugo
 ↓
 static pages
 ↓
 Hostinger
 ↓
 reader's browser

This still leaves room for interaction. Search runs in the browser, filters respond to clicks, the theme changes, and comments come from an external service. The useful distinction is what I need to operate: the main content does not depend on an application server of my own staying online.

I chose this structure because it fits the kind of publishing I want to do. I am not building a platform with its own reader accounts, subscription billing, or simultaneous browser editing. If those needs arise, they will deserve a separate decision.

A clear job for each tool

The implementation ended up with these responsibilities:

Component	Its job in this blog
Markdown	Store articles and their metadata.
Hugo + Hextra	Generate pages and provide the visual and functional foundation.
Custom layouts, CSS, and JavaScript	Apply the figueirego identity and specific interactions.
Private GitHub repository	Version the source and run checks and builds.
Hostinger	Serve the static site at its public URL.
Amazon S3	Store images uploaded separately from the site.
Disqus	Host comments and their moderation.
GoatCounter	Record visits used to generate the most-read lists.

An important decision was to use the hosting I already had. I considered other destinations, but the blog was published on Hostinger. AWS handles images, not page hosting. There is no CloudFront distribution in this workflow.

The source files remain in a private repository. Readers receive the published output and do not need repository access. That does not make files served by the site private: articles, images, HTML, and JavaScript delivered to a browser are public.

The theme is a foundation I can customize

For this first version, I pinned Hugo Extended 0.167.0 and Hextra 0.13.0. The theme is included in the repository. Building this project with the installed Hugo binary does not require installing Go or running a local npm build.

Customizations live separately from the theme directory:

content/ Portuguese and English content
layouts/ custom pages and components
assets/ styles, search, and interactions
static/ fonts, brand assets, and local images
i18n/ interface messages
themes/hextra/ the underlying theme
scripts/ upload and validation helpers

This separation makes problems easier to locate. Incorrect article text belongs in content/. An English button label belongs in i18n/. Spacing or contrast belongs in the styles. A comment-service change belongs in that integration.

A future theme update will still require review. Keeping these files separate makes the work easier to understand; it does not guarantee automatic compatibility with every new release.

Where do I actually write?

That was one of my questions during the build. There is no administration tab inside the blog where I sign in and start typing. Editing happens on my computer, in Markdown files, using a text or code editor.

Each publication begins with metadata: title, date, summary, topics, and draft status. The text follows. The content remains editable without opening a particular editing service, and Git records the changes I choose to commit.

For review, I use Hugo’s local preview. It renders the actual layout and can include drafts. Publishing is a separate step: submit the reviewed content, generate the production version, and check the live website. The full commands are in part 3.

Akita’s article about Docker also informed that investigation. Docker provides a local environment for contributing to his repository. Running that copy does not automatically publish to his site; contributions go through pull requests. My current workflow runs Hugo locally without making Docker a requirement.

Languages became part of the structure early

I wanted English at the domain root and Portuguese under /pt/. That became a content decision: each language has its own files, connected through a stable translation key.

Akita’s account of translating his archive was another reference. In my case, I am starting with pairs of articles rather than migrating a historical archive. The language control navigates between prepared versions; it does not call a translator on every click.

That puts review inside the editorial process. Titles, explanations, and examples need to make sense in both languages. The infrastructure connects the files, but it cannot decide whether a translation reads well.

Building with AI still required checking the result

I used Codex to help turn decisions into code, review behavior, and organize this series. To show the result, this series uses actual screenshots, with captions identifying their context. The process involved previews, screenshots, requests for changes, and checks of the site actually being served.

Some corrections came directly from using it: the search button that did not open as expected, comments split between languages, and excessive spacing in the footer. Choosing an appropriate technology alone would not have resolved any of them.

The build also included proposals for a newsletter and more menu sections. The newsletter was left out for now, and content formats were gathered inside the Archive. Having the ability to implement something did not mean it had to enter the first release.

The next step is to use this structure to write. To see how it works for someone arriving at the blog, continue to part 2: the reading experience.

Building my blog: 1. Architecture · 2. The reading experience · 3. Publishing and operations.

Building my blog, part 2: the reader's experience

Tue, 13 Oct 2026 12:02:00 -0300

Editorial note: This series documents the initial Hugo blog, which was separate from the portfolio. The unified version of the site brings both together at figueirego.com, with the blog under /blog/ (English) and /pt/blog/ (Portuguese). The navigation and screenshots below document that initial stage.

A reader arrives looking for a piece of writing. They might remember its subject, want to see what I have published recently, or have followed a link. The blog needs to support those paths without requiring anyone to understand how I organize my files.

This was the most iterative part of the build. I wanted the simplicity of the approach Akita described, with my website’s identity and an experience of its own. Colors and fonts were the starting point; the more consequential decisions involved navigation, search, and comments.

In part one, I explain the architecture. Here, the focus is what happens after the page opens.

Keeping the figueirego identity

I used the SVG wordmarks already present on my website, with versions for light and dark backgrounds. This preserves the actual shape of the logo. Manrope handles headings, interface text, and prose; JetBrains Mono handles code. The blog serves the font files itself.

Petroleum green identifies links and actions in the light theme. In dark mode, the accent becomes a lighter turquoise so it remains visible against the background. Subtle surfaces, dividers, and spacing organize the content.

The header received the glass effect I also wanted on my website: a translucent background, blur, and a light border. It falls back to a solid surface when the browser lacks support or the visitor prefers reduced transparency. The effect should support reading, not make it harder.

Four paths in the header

Earlier versions put Articles, Notes, and Experiments at the top. As Responses and Transcripts joined them, putting every format in the header would make the navigation compete for space, particularly on a phone.

In the standalone version described here, the final navigation had four destinations:

Latest: all publications, newest first.
Archive: the complete collection, with filters to find a particular entry.
About: my introduction and links to find me elsewhere.
My website: figueirego.com in the corresponding language.

External links open a new tab. Navigation within the blog stays in the current one. On phones, the header rearranges its controls and navigation into rows while retaining touch targets and accessible labels.

Format and topic answer different questions

An article about Go can share its subject with an experiment or a response to a reader. That is why I kept formats separate from topics:

Format	Intended use
Articles	Develop an idea, decision, or process with context.
Notes	Record a shorter observation or something learned.
Experiments	Document an attempt, its setup, and the observations.
Responses	Develop a question received on social media or in comments.
Transcripts	Publish text versions of my videos and conversations.

Topics are tags: software engineering, learning, Go, and other subjects that emerge from the writing. An entry can belong to several topics without being copied into several places.

In the Archive, readers can combine format, year, topic, and a text query. Filters are preserved in the URL, so the selection can be shared and browser back and forward continue to work. Without JavaScript, the complete list remains available. Topic counts come from published content; I did not fill the interface with demonstration numbers.

Images help when they serve a purpose

I liked the idea of showing covers on posts. They can make an entry easier to recognize and introduce a concept, such as a workflow or an architecture. I kept them optional: a short note may work perfectly well with a title and text alone.

The newest publication receives more space on the home page. The others follow with a title, summary, and metadata, plus a thumbnail when a cover exists. On the article page, the image appears in full, with alternative text and a caption when provided.

I also record its dimensions to reserve space before it loads. To explain this build, I chose actual screenshots of the process. This part’s cover shows the Archive in the local preview, with articles from this series. The caption identifies the environment: a local screenshot can show the interface, but it does not prove that version is already published.

Search needs to find what is in the text

During the revisions, search became a point of attention. The button needed to be easy to notice, open reliably, and find more than titles. A good-looking control that gets stuck interrupts the reader’s path.

The implementation uses FlexSearch in the browser, with an index for the current language. It considers titles, descriptions, summaries, tags, and full text. Accent normalization lets a Portuguese reader search for publicacao and find content containing “publicação.” The button and Ctrl+K or ⌘K open the dialog.

There are two search tools with different jobs. The Archive field filters its list using titles, summaries, and topics. The header search also looks inside articles. Someone who remembers a passage about translationKey can use the latter to find this post.

Local search follows the content generated by Hugo. It requires JavaScript in the browser but does not require me to operate a search server.

Searching the local preview for translationKey, before publishing the series.

Two languages, a linked publication

In that version, English lived at the root of blog.figueirego.com; Portuguese lived under /pt/ on the same subdomain. Each version has its own Markdown file. The language selector opens the corresponding translation when one exists; clicking it does not translate the text.

The relationship between this article’s versions is explicit:

translationKey: building-blog-reading

Both files use the same key, even though their titles and URLs differ. That allows the translation to be edited as a piece of writing in its own right. It also means an editorial correction needs to be considered in both languages.

Language does not determine appearance. By default, the theme follows the system. One click switches between light and dark and saves the preference in that browser. Icon transitions respect the reader’s reduced-motion preference.

One conversation across both versions

In the initial test, switching languages could lead to a different discussion. For the same article, I preferred shared comments: English and Portuguese readers can participate in the same conversation.

Disqus uses an identity shared by the translations, based on the translationKey. Its interface follows the page language. Each person’s comments remain in the language in which they wrote them.

Comments load automatically on eligible production publications. If loading fails, a retry option appears. The local preview does not open the live discussions.

Theme changes required an extra precaution. The Disqus editor lives in an iframe from another domain. After a reader interacts with it, the blog preserves the component when changing theme because it may contain an unsent comment. It offers a manual refresh instead. Readers should submit or copy their text before using that option.

This is an external integration, with its own moderation, appearance settings, and advertisements on the selected plan. A static blog still has dependencies; it simply means I do not maintain a comments backend myself.

Following the blog without another task to manage

I kept RSS in the footer, with a page that explains it and lets readers copy the feed address. Published entries from all five formats appear in their language’s RSS feed. Anyone using a feed reader can follow new posts there.

The newsletter is left out for now. Most read depends on real data, which I cover in part three, on publishing and operations.

To try the organization, open the Archive and select software engineering. Then search for translationKey from the header and switch this article’s language. Those paths provide a more useful test of the interface than a screenshot of the home page alone.

Building my blog series: 1. Architecture · 2. Reading experience · 3. Publishing and operations.

Building my blog, part 3: from Markdown to publishing

Tue, 13 Oct 2026 12:01:00 -0300

Editorial note: This series documents the initial Hugo blog, which was separate from the portfolio. The unified version of the site brings both together at figueirego.com, with the blog under /blog/ (English) and /pt/blog/ (Portuguese). The commands, screenshots, and main → published → blog.figueirego.com workflow below belong to the standalone version; they do not describe publishing the unified site.

The file containing this article lives in content/en/posts/. Its Portuguese version lives in content/pt/posts/. To publish, I review both, generate the site, check the output, and push the changes to GitHub. The hosting platform receives finished pages.

That was the experience I wanted: being able to write without looking after a publishing application running around the clock. There are still tools and services involved. The difference is knowing what each one does and keeping the path between the text and its reader short.

This is the third part of building the blog. In part one, I explained the architecture; in part two, the reading and navigation decisions. Here, I’ll walk through publishing from start to finish.

The editor works on a file on my computer

I write Markdown in a code editor. To start an article, I use the template already in the repository:

hugo new content content/pt/posts/meu-artigo.md --kind default
hugo new content content/en/posts/my-article.md --kind default

Both files start as drafts. The header, called front matter, holds the information the layout needs. Here is a shortened example following this project’s conventions:

---
title: "How I published my blog"
date: 2026-10-13T09:00:00-03:00
draft: true
sample: false
author: "Matheus Figueirêdo"
translationKey: "how-i-published-my-blog"
description: "From writing in Markdown to publishing."
summary: "The decisions and workflow behind putting the blog online."
tags: ["software engineering", "Hugo"]
image: "/images/my-cover.webp"
imageAlt: "The blog Archive, with publications organized by year."
imageCaption: "Screenshot of the local Archive preview."
imageWidth: 1512
imageHeight: 805
---

The title, summary, and body change in the translation. The translationKey stays the same, even when the filenames differ. That is how I connect the two versions. The language selector finds an existing translation; it does not translate the article itself. This use of the key follows Hugo’s front matter documentation.

Dimensions must match the actual image. A cover is optional: a short note may work better as text alone. To insert an image into the body, I use the usual syntax:

![Description of what the diagram explains](/images/my-diagram.webp)

Saving, previewing, and publishing are different steps

While writing, I start the preview:

hugo server --buildDrafts --bind 127.0.0.1

The local address lets me review the text, images, and both languages. --buildDrafts includes drafts in this preview. Saving updates the preview; none of this puts the article on the internet.

For the standalone version, before publishing, I changed draft to false and checked the output with this production configuration:

python3 -m unittest discover -s tests -v

hugo --config hugo.yaml,hugo.production.yaml \
 --environment production --minify --panicOnWarning \
 --cleanDestinationDir \
 --baseURL https://blog.figueirego.com/

python3 scripts/check-site.py public \
 --production-url https://blog.figueirego.com/

Tests cover the project’s behavior; the checker inspects the generated HTML, local links, translations, feeds, and publication metadata. The production configuration also removes the indexing restrictions used in the preview. Building only the local version and copying its files could carry those restrictions onto the public site.

Tests do not replace reading. I still need to check whether the cover fits the text, whether the translation sounds natural, and whether the examples make sense.

GitHub delivers; Hostinger serves the pages

In that version, after reviewing, I pushed the content files and any required local images to main. The workflow repeated the tests, ran Hugo, and prepared the published branch with the output.

The publishing path for the standalone blog looked like this:

Markdown and local images
 ↓
GitHub: main
 ↓
tests + Hugo + generated-file checks
 ↓
GitHub: published
 ↓
Hostinger → blog.figueirego.com

The source remains separate from the files being served. I do not edit published manually because the workflow generates its contents.

That branch includes a minimal package.json for compatibility with Hostinger’s preset. It has no dependencies, and its build command only checks that public/index.html exists. Hugo has already run on GitHub; the hosting platform receives finished HTML, CSS, JavaScript, and assets. I do not need to maintain my own application server or database to deliver the articles.

A publication is confirmed only after checking three things: the GitHub checks, the corresponding deployment in Hostinger, and the page on the live website. A green workflow proves that execution succeeded; it does not, by itself, prove which version a reader received.

Images can travel with the site or live in S3

AWS joined the setup as image storage. The pages remain on Hostinger. A file in static/images/ goes with the build; an image in S3 is uploaded separately and referenced by its public URL.

I do not need to move every image to AWS to use the blog. I can publish a local cover with its article and use S3 when I want a file outside the site’s package. The build does not upload images automatically.

For uploads, I configured a dedicated IAM user with permissions limited to the bucket’s image prefix. It uses passkey MFA and temporary AWS CLI authentication, without a permanent access key inside the project. AWS documents this browser-based sign-in flow.

The upload script lets me inspect the destination before sending anything. The names below are examples; they must be replaced with the values of an environment that has already been configured:

aws login --profile my-blog --region us-east-1

python3 scripts/upload-image.py /path/to/cover.webp \
 --bucket my-image-bucket \
 --base-url https://my-image-bucket.s3.us-east-1.amazonaws.com \
 --profile my-blog \
 --prefix images \
 --dry-run

--dry-run validates the file and shows a possible destination, but uploads nothing and does not confirm public access. To upload, I repeat the script command without that option. Each execution generates a new key; the simulated URL will not be the final URL.

After uploading, I open the returned URL without an AWS session and check the image. The script does not make a private bucket public: read access must already be configured. In my workflow, published images use HTTPS without a temporary signature, so the address does not expire with a session.

Uploads use long-lived caching with immutable and unique filenames. If I correct an image, I upload another file and update its URL in the text. The previous version remains in the bucket until removed. There is also a cost alert: it reports spending but does not enforce a cap or shut resources down. A simple blog is not a promise of a zero-dollar bill.

“Most read” without fetching statistics on every visit

GoatCounter records visits, and GitHub fetches those statistics during publication and through a scheduled daily run. The result becomes a static list included in the homepage.

The token has permission to read statistics and lives in a GitHub secret, available to the step responsible for that request. It does not enter the reader’s JavaScript. The browser runs the public counting script; the ranking is assembled before the page is served. Authentication follows the GoatCounter API.

The filters have precise meanings:

Week: the seven complete days before the update, in UTC.
Month: the thirty complete days before the update, in UTC.

These are rolling windows, not calendar weeks or months. The current day is excluded because it is incomplete. The list updates daily, with no promise of real-time results.

Visits to Portuguese and English versions are combined using translationKey; links and titles appear in the reader’s language. The number represents recorded visits, not a guarantee of completed reading or unique people across languages. Blockers can also prevent collection.

If a request fails, I preserve that period’s last valid result with its original timestamp. Without valid data, I do not invent numbers: the list stays empty, and the section remains hidden when neither period has content.

The routine after launch

Comments live in Disqus and need moderation. RSS includes eligible publications in each language and offers a way to follow the blog. The newsletter is out of scope for now.

Delegating these functions reduces what I operate, but leaves dependencies: hosting, storage, comments, and statistics can fail or change their terms. The text and its publication remain grounded in versioned files.

For the next article, my routine is concrete: write, review the translation, prepare the cover, check the preview, run the checks, push the changes, and open the published page. Then respond to comments and fix anything that needs it. The infrastructure has to leave room for that work.

In this series: 1. Architecture · 2. Reading and navigation · 3. Publishing.