Engineering
How we built the Porta blog
Why the Porta blog runs on MDX in the repository, a typed registry and static pages, and what we watch for in SEO: hreflang, lastmod, RSS and structured data.
October 26, 2026 · 5 min read
We wanted a blog that answers the real questions people have when looking for a home in Costa Rica, and that helps Porta show up when someone asks Google or an AI assistant. That gave us three requirements: every article must arrive complete in the server HTML, it must exist in Spanish and English without sending search engines contradictory signals, and publishing an article must be as reviewable as any code change.
Content in the repository, not in a CMS
We weighed a headless CMS (Sanity, Payload, Contentful) against files in the repository itself. We are a small team, and today the people who write are the same people who code, so a CMS meant one more service, authentication, webhooks and a preview flow to maintain, for a number of non-technical editors that is currently zero.
We chose MDX with @next/mdx, the route Next.js documents for the App Router. Each article lives in src/content/<section>/<slug>/<locale>.mdx, so the Spanish version and its translation sit in the same folder and a code review shows both together. If people outside the engineering team start writing one day, the content is already separate, and moving it to a CMS is a matter of moving files.
A registry for everything that is not prose
The MDX holds only the text. Everything else lives in a typed TypeScript registry: the slug, the section, the category, the publication and update dates, the available locales, the title and description per locale, the related articles and the call to action. It is the same pattern our help center already used.
The reason is practical. The sitemap, the RSS feed, the indexes and each page's metadata all need to know which articles exist without compiling any of them. A TypeScript file with no client dependencies can be imported from all of those places. Tests compare the registry with the content folder in both directions, so an unregistered article, or a registry entry with no article, fails the continuous-integration tests before it reaches production.
The server builds the complete page
Every article is rendered on the server and arrives complete in the HTML, the same for people and for crawlers; the body is a Server Component, so it adds almost no JavaScript to the browser. The registry fixes which slugs exist in each locale: a slug that is not registered in a locale returns a 404 instead of showing another language's text under the wrong URL.
The routes declare generateStaticParams and dynamicParams = false, and every article comes out of the build as static HTML that regenerates hourly. That was not free: the site's shared layout used to read the user's session on the server, and a single request read in that layout makes every page below it render on each visit. We moved the session and the maintenance notice to the browser, and since then the blog, the help center and the product pages are served from Next's cache in a few milliseconds.
The table of contents and the reading time are not typed by hand. They are derived from the MDX itself: the second-level headings form the table of contents, with the same ids rehype-slug gives them in the HTML, because both run github-slugger over the same text. The reading time counts words at 200 per minute, the same figure the help center uses. We have already seen hand-typed reading times end up saying different things in different places, and we did not want a repeat.
SEO: what we do and what we avoid on purpose
- Structured data. Each guide publishes
BlogPostingand each technical noteTechArticle, with dates, language, image and aBreadcrumbList. The author is the organization, not an invented person: Google's guidance asks for real authorship, and we prefer an honest team byline. - hreflang from the registry. The site's static pages always declare Spanish, English and
x-default. An article may exist in a single locale, so its alternates are computed from the registry and never point at a translation that does not exist. - An honest
lastmod. The article sitemap uses the date the content last changed, not the build time. Google ignoreslastmodonce it finds it unreliable, and that discount applies to the whole site, including the real dates on property listings. - Categories without thin content. A category stays
noindex, followand out of the sitemap until it holds five articles. Both decisions read the same function, so we never submit a URL that asks not to be indexed. - A social image per article. Each article has its own 1200×630 card rendered on the server with
ImageResponse, using the same Figtree font as our social media pieces. - RSS per locale. Each section publishes its feed at
/es/<section>/rss.xmland/en/<section>/rss.xml, linked from the<head>of the indexes, the categories and the articles.
What we have not done yet
There are no author pages, because today we sign as a team. There is no pagination either: with a few dozen articles, one page per index is more useful than several nearly empty ones. Both have a place in the design, and we will add them when the content justifies it.
If you are curious how we solve other problems, such as showing prices in two currencies without them changing from one screen to the next, follow this blog or subscribe to the feed.
Written by the Porta team with the help of artificial intelligence tools and checked against the sources cited in the text. If you spot an outdated figure, write to us from the Help Center.
Related articles
Engineering
Prices in colones and dollars, no surprises
How Porta shows prices in colones or dollars at the Central Bank rate: server-side conversion, filters across currencies and a first render that never guesses.
October 26, 2026 · 4 min read