Figueirego Blog – Behind the blog

Building my blog, part 5: SEO, languages, and RSS

Mon, 19 Oct 2026 04:15:50 -0300

An article can open normally in the browser and still present itself incorrectly elsewhere. Its search title may be generic, a Portuguese page may advertise the English feed, or a topic feed may contain every article on the blog.

While reviewing the website, I began looking at these outputs too. Published content needs to remain identifiable outside the layout I designed for it.

Visible identity and metadata have their own roles

On the page, a title and description help people understand where they are. Metadata provides the title, description, URL, and other information used by external services. These fields should agree about the content without repeating the brand in every visible sentence.

Articles in this project use editorial data to generate social metadata and structured information. Review starts with the writing: a specific title, a description explaining the subject, and sections that deliver what was promised. Adding search terms that the article never explains would not help.

Each part of this series has a focus: architecture, reading, publishing, images, or discovery. Links between them help readers follow the story without turning five articles into variations of the same introduction.

Two languages need clear addresses

English articles live under /blog/; Portuguese articles under /pt/blog/. A translationKey relates the files, while language metadata points to the equivalent pages.

A canonical URL identifies the preferred address for that page. hreflang identifies language alternatives. The Portuguese version should not treat English as the only primary page and lose its own identity. Both versions need consistent, corresponding links.

Google’s localized-version documentation explains the relationship between these alternatives. In my workflow, validation of generated files helps identify incorrect translation links before publication.

The sitemap should also reflect what is publicly available. Drafts stay out of normal publication, and a preview should not be treated as the final address.

Requesting indexing does not prove the outcome

Search Console has different stages that can look like one when you focus only on a success message:

Evidence	What it establishes
Accepted request	The request was received.
Page already indexed	A version of the page exists in the index.
New crawl	Google fetched the page again.
Displayed search result	You can observe how it appeared for that query.

A crawl after an edit does not, by itself, demonstrate that the new description was adopted in the result. It does not guarantee a position for a keyword either. Google explicitly notes that requesting another crawl does not guarantee immediate inclusion or inclusion in the index.

The project includes a routine that reads indexing status for the main pages. It tracks changes and failures; it does not submit a new request or automatically track every future article. The monitored set needs review as the website grows.

RSS is another presentation of the same content

RSS lets people follow publications through a feed reader. They subscribe to an address and receive items without visiting the home page to check for something new.

The general Portuguese feed is at /pt/blog/index.xml; English is at /blog/index.xml. Topic and section pages can also have their own feeds. The scope needs to match the page: someone subscribing to a topic expects articles about that topic.

Identification happens in two layers. HTML advertises the feed through a discovery link, and the XML itself identifies its title, language, link, and self URL. A Portuguese page advertising the English feed would be wrong even if both files were valid XML.

The public English RSS page presents the feed address for that language. Readers subscribe to this URL in their feed application.

View the full-size screenshot

What the feed review needed to check

The template starts with eligible publications and applies the section or topic scope before the fifty-item limit. A less frequent topic therefore does not disappear simply because the fifty newest articles overall cover other subjects.

Drafts, samples, and unlisted content are excluded, as are future publication dates. In production, the filter also excludes content marked noindex. That needs checking in the generated XML as well as in the template.

Within an item, relative images and links need to keep working outside the website. An address relying on the current page can resolve incorrectly in a feed reader. Feed content resolves those references against the article’s URL and includes a cover when available.

Dates have separate meanings too. pubDate records publication and preserves the real offset, such as -0300. When revising a published article, I set lastmod to the date of that change:

# Example of a revision after publication.
date: 2026-10-19T09:00:00-03:00
lastmod: 2026-10-20T10:30:00-03:00

The channel’s lastBuildDate uses the latest modification date among its included items. In this project, editing a file without setting lastmod does not automatically turn the commit date into an editorial date.

Keep a routine I can repeat

Before publishing, I review the title and description, translation, links between parts, and cover metadata. After building, I check URLs, feeds, and which pages entered the publication. Once the version reaches the host, I check the served files.

If I started again, I would organize design and architecture earlier, separating each technology and its purpose. Reviewing SEO and RSS reinforced that lesson: each output has its own job, but all of them need to tell the same story about the content.

The website will keep changing. I want these decisions recorded so I can return to them when a tool, integration, or my own idea of a blog changes.

Building my blog, part 4: uploading images to S3 from Finder

Mon, 19 Oct 2026 04:15:50 -0300

Select an image, right-click, and receive a URL ready for the article. That was the convenience I wanted in my blogging routine. Automating AWS took the most work after the design.

The path began with an upload helper and became a Finder Quick Action. The successful case was easy to describe. The work appeared in the next questions: what happens when the session expires, when I abandon login, or when the upload fails?

Pages on Hostinger, images on S3

S3 stores objects: in this case, image files. Pages remain on Hostinger. Markdown contains the file’s public URL, and the browser retrieves the image from that address.

This separates image uploads from the website build. Adding a file to the repository does not execute an AWS upload. Some local assets also travel with the build; new editorial images use the S3 workflow.

A published image URL needs to work after my session ends. That is why the article does not use a temporary signed URL. The image prefix has public read access configured, while writing requires authentication. The upload script does not make any arbitrary private bucket public.

What I mean by image versions

Each upload receives a new name containing the year, month, a normalized name, and an identifier. An illustrative path would be:

images/2026/10/my-cover-unique-identifier.webp

If I correct a cover, I upload another file and update the article’s reference. The earlier image remains available until it is removed. That helps prevent a URL with long-lived caching from unexpectedly representing different content.

This differs from S3 Versioning, which retains versions of the same object within the bucket. Here I am describing new keys and new URLs. Having two files does not establish that native versioning is enabled.

Git history records changes to the reference in an article. By itself, it is not a backup of external files. Preserving and recovering images also requires looking after their storage.

A dedicated upload identity

The shortcut uses an AWS CLI profile with temporary credentials for a dedicated user. It does not depend on a root session or store a permanent access key inside the project.

The account and permissions are prepared beforehand. The helper uses that existing destination; it does not provision an entire AWS environment. The AWS CLI’s local browser login renews authentication without putting a password or code in an article, script, or conversation.

In the configured project, installation of the Quick Action starts from the repository root:

python3 blog/scripts/install-finder-upload.py

This command belongs to the private repository and requires the environment described above. It is not a universal public installer for any AWS account. Reproducing the idea requires adapting the destination, profile, and permissions to your environment.

The Finder routine

With the action installed, I select the image and choose Quick Actions → Enviar imagem ao S3 — Figueirego. After uploading, the action copies the URL and shows a completion notification. I do not need to open Terminal for the normal routine.

If the session expired, the shortcut opens browser authentication and waits for completion. Once login is authorized, it continues uploading. Testing the full path through Finder was important: running the helper in Terminal alone would not demonstrate that notifications appeared through the macOS action.

We also checked the public URL and the received image. A completion message helps, but it does not replace checking that the correct file is accessible outside the AWS session.

The installed Finder action is available by right-clicking an image. The menu was opened for this screenshot without performing another upload; the custom action keeps its Portuguese name.

View the full-size screenshot

Cancellation is part of the interface

Waiting five minutes to discover that a login had been abandoned was a poor experience. The waiting step gained a window with Cancelar envio (Cancel upload), making it possible to explicitly end that attempt.

Situation	Expected behavior
Valid session	Upload, copy the URL, and announce completion.
Expired session	Open login and continue after authentication.
Cancellation while waiting for login	Notify, do not upload the image, and preserve clipboard contents.
Another attempt after cancellation	Allow the workflow to start again.

Closing the browser tab alone is not equivalent to pressing the cancellation button. And that button cancels the authentication wait; it does not promise to interrupt an upload that has already started.

We tested the waiting step first with simulated AWS behavior and then with real login. The checks answer different questions: simulation helps control the scenario; the real test confirms the integration that will be used.

From an image in Finder to a copied URL. Cancelling sign-in stops the flow before uploading.

Open the full-size diagram

What still requires care

I do not automatically remove an old image just because I uploaded another one. A draft, another article, or a feed already received by a reader may still refer to it. Cleanup needs to account for those references.

If the upload succeeds but copying to the clipboard fails, that does not undo the uploaded object either. Distinguishing an upload failure from failure in the final convenience step avoids unnecessary repeat uploads.

Automation shortened the routine. The lesson was to give cancellation and recovery proper attention too: a tool that is simple to use should explain when it finished, when it failed, and what happened to the file.

Building my blog, part 3: from Markdown to publication

Mon, 19 Oct 2026 04:15:50 -0300

Saving an article in the editor does not mean it is published. The text still needs review, page generation, checks, and delivery to the host. After that, I need to open the public address and see what readers received.

That distinction became important when integrating the blog and portfolio. The first version had a separate blog workflow. Today, both come from the same repository and are delivered by the Next.js application on Hostinger. The old subdomain is no longer the destination.

An article starts with text and metadata

I write in Markdown. Before the body, a block called front matter describes how the article should be presented. This is a reduced example, not a file ready to publish:

---
title: "How I organized my blog"
date: 2026-10-19T09:00:00-03:00
draft: true
author: "Matheus Figueirêdo"
translationKey: how-i-organized-my-blog
description: "The decisions behind content, navigation, and publishing."
tags: ["Hugo", "publishing"]
---

The date needs to match the actual publication. draft: true keeps the article out of the public build. In the translation, the title, description, topics, and body change; the translationKey stays the same.

A cover can be added later. When present, it needs a URL, alternative text, and dimensions matching the file. The article should remain readable without relying on an image to communicate its subject.

Two previews for different questions

To review the writing alone, I can use Hugo’s server. These commands start at the repository root and assume the project’s pinned Hugo extended version is installed:

cd blog
hugo server --buildDrafts --bind 127.0.0.1

The option includes drafts in the local preview. It is useful for checking text, the table of contents, and translation. To assess integration with the portfolio, I use the complete project in another terminal:

cd client
npm ci
npm run dev

This path requires Node.js 24.12.0 or later and Hugo extended 0.167.0 in the environment. The development script builds the blog at startup. After editing Markdown, I need to rebuild that part with node scripts/build-blog.mjs --preview and reload the page. This does not replace the dedicated Hugo server’s file watching, and the regular integrated build still excludes drafts.

The commands depend on helpers in this private repository. For another project, the transferable idea is to keep a quick content preview and another one that exercises the complete integration.

The tested version is the one promoted

The current workflow is:

reviewed files → dev → main
 ↓
 tests and integrated build
 ↓
 approved SHA → production
 ↓
 Hostinger
 ↓
 public website checks

A SHA identifies a commit. Using it during promotion connects the tested version with the version sent for publication. CI should not approve one commit and silently promote a different one that arrived later.

The central verification command runs from client/:

node scripts/verify-release.mjs --production

It combines type checking, linting, formatting, tests, the Next.js build with Hugo, and checks of the generated files. I use --dry-run to list the steps without executing them. Neither option pushes code to GitHub on its own.

After checks pass on main, automation promotes the approved commit to production. Hostinger follows that branch. If main advanced during the run, the new version needs its own verification. Promotion should not overwrite history with a force push.

Review, test, deploy and verify: the four stages in this website’s delivery flow.

Open the full-size diagram

Check three separate results

A green check reports verification. The Hostinger deployment reports whether the host could build and start the corresponding version. Opening public pages shows what is actually delivered.

That is why checks include both languages, article links, images, RSS, and the route back to the rest of the website. I also need to inspect the deployment SHA. An HTTP 200 response does not demonstrate that every page component worked.

Content requires an additional check: a draft must not appear in search, the sitemap, or a feed. A preview that includes drafts cannot be copied to production as though it were the public build.

Actual deployment detail from October 19, 2026, for the initial release of this series with its covers. The Portuguese control panel identifies the deployed commit.

View the full-size screenshot

Most-read lists also go through publication

GoatCounter provides visit statistics. A GitHub job queries those data and writes a snapshot to blog/data/popular.json. The build incorporates the result and serves a public file at /blog/popular.json.

The browser can refresh the lists from that file without receiving the GoatCounter API token. Collection has a daily schedule and recovery attempts. Scheduled times depend on providers; they are not a guarantee of an update at an exact second.

Week and month represent the previous seven and thirty complete days in UTC. Translations of the same article are aggregated by editorial identity. These are recorded visits, not unique people across languages or evidence that someone finished reading.

When collection fails, the workflow preserves the previous snapshot rather than publishing invented numbers. A valid update still has to pass verification and reach the host. Monitoring the public JSON helps detect the difference between collecting data and publishing them.

This routine is part of maintaining the site. Automation helps, but the result that matters remains the correct content at the address someone opens.

Building my blog, part 2: designing for clarity

Mon, 19 Oct 2026 04:15:50 -0300

The old terminal made sense to me, but it could ask too much of a visitor. Someone trying to learn about my work should not have to discover a command to find information. When adapting that area into a desktop, I wanted a more familiar language: open, explore, and close windows.

That did not solve the entire design. A desktop can also be confusing if everything depends on it. The website has dedicated pages for my background, projects, writing, and contact information; the interactive area is another way to explore. Conventional navigation remains available.

Getting this combination right was the hardest part of building the site. I wanted it to reflect me and help people understand what they were seeing. Its appearance needed to support that reading.

One reference for presentation, another for construction

With Zeno Rocha, I was interested in how he presents himself and gives his work visibility while keeping navigation intuitive. With Akita, the reference was mainly how he built his blog and the ideas around it. These were not two interfaces I intended to combine literally.

Through experiments with Claude, Antigravity, and then Codex with skills, I refined a direction that needed to fit the rest of my website. An interesting visual result could still have poor spacing, too much information in one place, or unclear interaction.

This was particularly noticeable with article covers. I wanted to retain the title, summary, author, date, reading time, and topics. When those elements were too close together, a large image did not compensate for the missing hierarchy. The gradient also needed revision: a transition that seemed acceptable in dark mode could form a heavy band in light mode.

Give each area a purpose

Featured articles present a selection of up to three pieces. Recent articles show the latest publications and can repeat a featured item. The Archive provides a way to explore more content and filter it.

Topics appear as small labels without a hashtag symbol. A label communicates a category; its appearance should still suggest that it is clickable. Similarly, a return link should explain its destination. A link promising to return to the Archive needs to go there.

These details can look minor in isolation. Together, they determine whether someone can predict the next step. I began looking at each element’s purpose as well as its position in a screenshot.

The published Archive in English, captured on October 19, 2026. Search, filters, and topics each serve a different navigation task.

View the full-size screenshot

Motion should follow the action

Featured images appear in grayscale on devices with a mouse and gain color on hover. The first transition felt too abrupt. We adjusted it to give the change time to register, with a slight enlargement of the image.

The table of contents needed similar attention. Clicking from the first topic to the last should not make the indicator compete for attention with every intermediate section during scrolling. Navigation began treating that movement as an action with a chosen destination.

These effects need alternatives. A phone does not have a reliable equivalent of mouse hover. Keyboard focus should appear without depending on a slow animation. For people who request reduced motion in their system settings, movement and transitions should be reduced or removed. The preference is read through the prefers-reduced-motion media query.

The goal is not to make visitors wait for an effect before using the site. Motion should explain what is changing and let navigation continue.

An actual screenshot of the English reading view. The table of contents keeps the selected section visible beside the text.

View the full-size screenshot

Reading in Portuguese or English

The Portuguese blog lives under /pt/blog/; the English version is under /blog/. Each article has one file per language. Both share a translationKey:

# In both files; the title and body are translated.
translationKey: building-blog-reading

The language selector opens the corresponding version when one exists. It does not automatically translate the text. Summaries, labels, image alternative text, and links between parts of a series also need review.

Search uses a local index containing text, titles, and other editorial fields. It helps find a word inside an article; Archive filters help narrow a collection by criteria. Those are related tasks, but they are not identical.

Real comments and the limits of testing

I kept the existing Disqus integration. Reaction buttons that only stored a choice in the browser did not provide a real interaction with me, so that proposal was left out.

Loading comments showed why an attractive screenshot does not prove something works. We had to review the domain authorized in Disqus and test automatic loading. Tool interference and changing browser tabs also affected some checks. Diagnosis needed to distinguish a service failure, website configuration, and a problem in the test itself.

In production, comments attempt to load automatically. The retry button is a recovery path for failures. Production integration is disabled in previews so experiments do not mix with real discussions.

Today, I would review a page by following its tasks: find an article, change language, use the table of contents, return to the listing, and locate another subject. I would repeat that with a keyboard, light and dark themes, and a phone-sized viewport. Emulation helps identify layout problems, but it is not the same as testing a physical device. That use is what shows whether the design is doing its job.

Building my blog, part 1: from landing page to website

Mon, 19 Oct 2026 04:15:50 -0300

I already had a website project. It was a landing page with an idea I still wanted to keep, but it needed more room. I decided to reuse that foundation, divide the content into sections, and improve how I presented my work and the things I wanted to write about.

One of the most visible changes was turning a terminal experience into a desktop. The terminal spoke a language closely associated with programming. I wanted people to explore without knowing commands. Windows and icons seemed like a more familiar starting point, although the result still had to work in practice and on a phone.

The blog became part of that same effort. My concern about combining the two was confusing the navigation and failing to explain what each area offered. That is why this series starts with how the project is organized. The code came with decisions about communication.

The actual portfolio desktop: windows and folders provide an alternative way to explore while conventional navigation remains available.

View the full-size screenshot

References with different roles

Akita’s blog helped me think about building a blog and the routine of publishing. Zeno Rocha’s website was a reference for presentation: showing your work while keeping exploration intuitive.

I used these references to study what I could improve, reuse, or discard. I had an idea of my own to preserve and needed to understand which solutions would help express it. Getting the design to convey that identity turned out to be the hardest part.

AI tools were part of that investigation. I relied more on Codex for information and examining the project, and mainly on Claude and Antigravity for design. Then I returned to Codex with skills to separate and explore each concept. That division describes my process, not a rule about which tool everyone should use.

Where the website ends and the blog begins

Today, the portfolio uses Next.js, React, and TypeScript. Articles live in Markdown files and Hugo generates their pages. Hextra provides the theme foundation, with customizations in the project files.

Hugo is a generator: it reads the text and metadata and produces HTML, CSS, JavaScript, and indexes. Next.js brings that output together with the portfolio pages. Hostinger runs the Next.js application and serves everything under the same domain.

blog/content/ → Hugo → blog pages, search, and feeds
 ↓
 client/public/blog/
 client/public/pt/blog/
 ↓
 Next.js + portfolio pages → Hostinger

This corrects a description of the first version, when the blog was separate. The current website has a Next.js server in production; Hugo runs only while generating the files. Articles do not need a custom editing API or a database query to assemble their content for each visit.

Markdown passes through Hugo; generated files are integrated into Next.js and served by Hostinger.

Open the full-size diagram

Each technology needs a clear job

Component	Responsibility in this project
Markdown	Text, summary, date, language, and other editorial metadata.
Hugo and Hextra	Blog generation and the layout foundation.
Next.js	Portfolio pages and integrated delivery.
GitHub and Actions	Code and content history, tests, and release preparation.
Hostinger	Building and running the published version.
Amazon S3	Storing images uploaded separately.
Disqus	Discussions and comment moderation.
GoatCounter	Visit statistics used by the most-read lists.

I did not add a database just to store articles. I also kept image storage outside Hugo’s responsibilities. That separation helps locate problems: an unavailable image, a missing article, and comments that fail to load may have different causes.

Organization visible in the files

The main structure looks like this:

client/ Next.js application
blog/content/pt/ Portuguese content
blog/content/en/ English content
blog/layouts/ custom layouts
blog/assets/ styles and interactions
blog/themes/hextra/ base theme
blog/scripts/ publishing and image helpers
.github/workflows/ checks and integrated automation

Customizations live outside the theme directory. That makes an upgrade easier to review without mixing every local change into Hextra’s original code. An upgrade still needs testing; the folder structure does not guarantee compatibility.

The active repository is private. Published output, including articles, images, and scripts delivered to the browser, is public. Readers do not need repository access to use the website, but the commands in this series are examples from my project, not a public package ready to clone.

What I would organize before starting

If I started today, I would look more carefully at design and architecture before implementing. I would separate responsibilities, each area’s purpose, and the role of the technologies. I discovered some of that organization while building.

For a similar project, I would first write down the visitor’s path: where they understand who I am, find my projects, and read my articles. Then I would map an article’s journey to publication. Those two maps help reveal which parts need to communicate and which can remain independent.

In the next part, I cover what took the most iteration: making that organization visible in the interface without requiring visitors to understand the project’s architecture.