Figueirego Blog – Next.js

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 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.