Buildando

What Buildando is

Wed, 22 Jul 2026 00:00:00 GMT

Buildando is a blog template: a ready starting point to publish your own blog in minutes and customize over time. It is what you are reading now — this site is both the blog and the template anyone can clone.

If you came for the template, start here and move on to Installing and customizing and Writing posts.

The idea in one sentence

Writing a post is creating a folder with a markdown file — everything else (SEO, feed, search, theme, languages) is already there, with no server at all.

No backend, on purpose

The blog is fully static: at build time everything the reader needs — pages, search, feeds, structured data — becomes files any host can serve. No database, no admin panel, no server to maintain. The two features that would normally need a backend are delegated:

Search is a static index of the posts, built at build time and run in the browser.
Comments are GitHub Discussions (or another provider) embedded on the page.

That keeps the site fast, cheap to host, and its content versioned in git — where text and code already feel at home.

What’s included

Markdown content, one post per folder, images alongside.
SEO by construction: title, description, canonical, Open Graph, Twitter Card, JSON-LD, sitemap.xml, robots.txt, and RSS on every page. Cover-less posts get an automatic branded social card.
Light/dark theme with a toggle, remembered across visits.
Multilingual with per-locale routes, a switcher, and hreflang — this post has a Portuguese version (switch it in the top corner).
Search (posts only): a live preview in a modal (press / or ⌘K) and, on Enter, a results page with the same cards as the feed. Plus a filter by category, tag, month on the home.
Optional share, newsletter, and analytics/ads with a consent banner.

Generic and contributable

Integrations (comments, search, analytics) sit behind ports with pluggable adapters: switching from giscus to another provider is a one-word config change. The goal is that you — or anyone — can adapt the template to your stack and contribute new adapters.

All identity (name, colors, socials, domain) lives in one file (src/config/site.ts), so a fork is editing that file and swapping the logo.

Who it’s for

For anyone who wants a fast, SEO-strong, low-maintenance blog without running a server — and likes writing markdown with content in git. If that’s you, next is install and customize.

Installing Buildando and customizing it

Tue, 21 Jul 2026 00:00:00 GMT

You have seen what Buildando is. Now let’s put yours online and make it look like you.

1. Get the template

The template lives at github.com/Buildando/template.buildando.com. There, click “Use this template” → Create a new repository (or fork it). Then clone your repository and install:

git clone https://github.com/YOUR-USER/YOUR-REPO.git
cd YOUR-REPO
npm install
npm run dev      # local server, with hot reload

Open http://localhost:4321 and the blog is already running. Requires Node 22+.

2. The single configuration surface

Almost everything that is “yours” lives in one file: src/config/site.ts. That is where you edit the name, domain, author, the skin (colors and fonts — see section 5), social links, navigation, languages, and the integrations (comments, search, analytics).

export const SITE = {
  name: "My Blog",
  url: "https://my-domain.com",
  author: "Your Name",
  // ...
};

Golden rule: if buildando, the domain, or the author shows up outside that file, it’s a bug. That is what makes forking so simple.

Swap the assets in public/ too: favicon.svg (the logo) and og-default.svg (the default social image).

3. The home intro (before the feed)

That block at the top of the home page — the title and welcome line, before the list of posts — is free-form markdown, one per language, in src/content/home/:

src/content/home/
  pt.md      ← the Portuguese hero
  en.md      ← the English hero

Edit en.md with whatever you want (title, paragraph, links) — the site’s CSS handles the looks. Without that file, the home falls back to the site name and description.

4. The “About the Author” page

The About page lives in src/pages/[lang]/about.astro. The text for each language sits right at the top of the file — replace it with yours. The menu link already points at it.

5. Visual identity (skins)

The blog’s looks — light/dark palettes, fonts, and reading width — are a skin: a preset of tokens in src/config/skins.ts. Switching identity is one line in site.ts:

export const ACTIVE_SKIN: SkinName = "editorial";

Seven of them ship ready:

terminal — the default: dark, blue accent, Inter + Space Grotesk
editorial — serif headings, warm paper, green accent
mono — monospaced headings, high contrast, amber accent
minimal — nearly monochrome, discreet lime accent
warmDev — the Solarized palette
brutalist — radical: hard borders, square corners, offset shadows, violet accent
berry — vibrant magenta/pink over a plum base, wider reading column; changes structure (the filter becomes a left sidebar on the home)

Each comes with light and dark (the theme button toggles). To craft your own, copy a preset in skins.ts and edit the values — it is plain CSS. A skin can even change structure, not just color: rules scoped by [data-skin="name"] in src/styles/skins.css — brutalist and berry are the examples. More in the Skins section of the README.

6. One language or several

The template ships bilingual (Portuguese and English), but that is configuration, not structure. The I18N block decides:

export const I18N = {
  defaultLocale: "pt",
  locales: [
    { code: "pt", label: "Português", htmlLang: "pt-BR", ogLocale: "pt_BR" },
    { code: "en", label: "English",   htmlLang: "en",    ogLocale: "en_US" },
  ],
} as const;

To keep a single language, delete the other line. The language switcher disappears from the header on its own, and URLs stay locale-prefixed (/en/...). Delete that language’s hero in src/content/home/ and the posts written in it too — a post whose lang: no longer exists fails the build, naming the post.

To add a language, add a line to locales and translate the strings in src/i18n/ui.ts. You do not have to guess what is missing: run npm test and config-integrity.test.ts lists exactly the keys the new language still owes.

Each post declares the language it is written in and links its translations — that belongs to writing posts. What matters here is that nothing forces you to translate everything: an untranslated post stays reachable under the other languages, with the interface translated and the body in its original language.

Three files and one field:

public/favicon.svg      ← header logo AND browser-tab icon
public/og-default.svg   ← social image for pages with none of their own
src/assets/author.jpg   ← the photo on the About page

The header logo comes from SITE.logo, which points at /favicon.svg — replace the file keeping the name, or change the field. Being SVG, it stays sharp at any size and weighs nothing.

Posts need no image: one without a cover automatically gets a social card generated at build, carrying your brand and the skin’s colors.

Two different blocks. SOCIAL is your own profiles, rendered as footer icons:

export const SOCIAL = [
  { label: "GitHub", href: "https://github.com/your-user", icon: "github" },
  { label: "LinkedIn", href: "https://linkedin.com/in/you", icon: "linkedin" },
] as const;

icon is a simple-icons slug. Ready to use: github, instagram, threads, x, tiktok, facebook, linkedin, youtube, telegram, whatsapp and rss. An unknown slug simply draws nothing — to add another, edit src/components/Icon.astro. An empty list means a footer without icons.

SHARE is a different thing: the share buttons at the foot of each post.

export const SHARE = {
  networks: ["x", "whatsapp", "telegram", "linkedin", "facebook"],
  copyLink: true,   // copy-link button
  native: true,     // the phone's own share sheet, where available
} as const;

9. Turning integrations on

Every integration is opt-in and empty means off: the template as you cloned it makes not one third-party request. Turn on only what you use — and each one you turn on changes what the privacy policy declares, on its own.

9.1 Comments with GitHub Discussions (giscus)

giscus renders a GitHub discussion inside the post. There is no database: the comments live on GitHub.

Create a public repository just for comments — say your-user/my-blog-comments. It has to be public, but the blog’s own repository can stay private: they are separate things, which is the reason to dedicate one.
In that repository, go to Settings → General → Features and tick Discussions.
Install the giscus app on it: github.com/apps/giscus.
Open giscus.app and enter owner/repository. The page checks the three prerequisites above and, if they hold, hands you repoId and categoryId — pick the Announcements category, which is announcement-only and stops anyone opening loose threads.
Paste into the GISCUS block:

export const GISCUS = {
  repo: "your-user/my-blog-comments",
  repoId: "R_kg...",
  category: "Announcements",
  categoryId: "DIC_kw...",
  mapping: "pathname",   // each post URL maps to a discussion
  theme: "site",
} as const;

mapping: "pathname" ties a post to its discussion by URL path. Which means renaming a post’s folder orphans its comments — the old discussion stays there, pointing at an address that no longer exists.

Leave theme: "site" so the comments follow the blog’s theme button. giscus’s own default, preferred_color_scheme, follows the operating system: a reader who puts the site in light mode while their OS is dark gets dark comments in the middle of a light page.

While repoId is empty the whole section is not rendered — no heading, no script, no request.

9.2 Google Analytics

Of the snippet Google hands you, the blog needs one thing: the measurement id.

In Google Analytics, create a GA4 property and a data stream for your domain. It gives you an id shaped G-XXXXXXXXXX.
Paste it into the config:

ANALYTICS.googleAnalytics = "G-XXXXXXXXXX";

Do not paste the <script>: the blog emits the very same gtag calls, only after consent. Turning GA on lights up three things at once:

the cookie banner starts appearing;
the privacy policy gains its Google Analytics section;
the footer gains Cookie preferences, for readers who change their mind.

So fill the CONSENT block along with it (section 9.5). To check it is right, read the published HTML: there must be no <script src="...googletagmanager..."> on the page — the address appears only inside the consent queue.

Plausible is the cookieless alternative: ANALYTICS.plausible = "your-domain.com". Setting no cookie, it triggers no banner.

Only worth doing once AdSense has approved your site — approval looks at volume and originality, and a fresh blog usually waits.

Three pieces, in three different places:

The publisher id, in the config:

ANALYTICS.adsense = "ca-pub-0000000000000000";

ads.txt, at the site root. Create public/ads.txt with the exact line AdSense gives you — everything in public/ lands at the domain root, which is where Google looks:

google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0

The formats, in the AdSense dashboard, under Ads → By site. Without that step the script loads and no ad appears — a symptom indistinguishable from a bug.

The account-verification meta tag needs no pasting: it is emitted from the publisher id. And since all advertising sits behind consent, readers who decline see no ads — correct behaviour, and less revenue than the dashboard projects.

Automatic formats let Google decide where to insert, including between paragraphs and pinned to the bottom. To decide yourself, place src/components/AdUnit.astro with a slot created in the dashboard — no page uses it by default.

First, a confusion that costs time: RSS does not send email. The feed is a file the site publishes; what reads it is a feed reader. Reaching an inbox takes a provider in between, and that provider is what turns “a new post is out” into a message.

Pick a provider with RSS-to-email. Mind the plan: several charge for precisely that automation, even with a handful of subscribers. Worth checking before signing up.

Create one list per language. The feed is per language, so a list fed from it is too — someone subscribing in English should not receive Portuguese posts.

Take the real form fields, not the iframe. This is where it is easy to go wrong: providers offer an iframe or a ready-made link, but what you need is the HTML form. If only the link exists, open the hosted form page and read its HTML — the three things that matter are there:

the action (where the form posts);
the name of the email field, often not email (Brevo uses EMAIL);
the hidden fields, including the anti-bot honeypot — a field that must be submitted empty.

Posting without them is the worst kind of failure: the provider accepts the request and subscribes nobody. The form looks like it works.

export const NEWSLETTER = {
  actionUrl: {
    pt: "https://provider.example/serve/AAA",
    en: "https://provider.example/serve/BBB",
  },
  emailField: "EMAIL",
  hiddenFields: {
    pt: { locale: "pt", email_address_check: "" },
    en: { locale: "en", email_address_check: "" },
  },
} as const;

A language with no endpoint simply shows no form — better no form than the wrong list.

Close the loop in the dashboard: create one RSS-to-email integration per list, pointing at the matching feed (/pt/rss.xml, /en/rss.xml). From then on, publishing a post sends the email by itself. Two things to watch on the first run: many providers pull several items at once and your feed already has posts — check how many it intends to send before letting it go; and there is usually a window of about an hour between publishing and sending.

With JavaScript the submission happens in the background and the reader stays on the page; without it, the form posts normally. No subscriber data touches your site.

This block turns nothing on — it governs what the others oblige:

export const CONSENT = {
  required: true,
  privacyUrl: "/privacy",
  contact: "privacy@your-domain.com",
} as const;

contact is the address the policy offers for data-subject requests. Create the mailbox before publishing: a policy pointing at an address that does not exist is worse than no address at all.

The privacy page assembles itself from the configuration. You neither write nor maintain that text: with Google Analytics on, its section appears; with a newsletter in that language, the newsletter section appears; with no ads, the sentence mentioning them goes away. And when nothing is on — no analytics, no ads, no comments embed, no signup form — there is no privacy page, no footer link and no banner: a blog that collects nothing has nothing to declare.

Do read the page once everything is configured. It describes what the site really does, but you are the one answering for the text.

9.6 Search

Nothing to configure beyond on or off: INTEGRATIONS.search = "pagefind" or "none". The index is built at build time, split by language, and runs in the browser — there is no search server to keep.

10. RSS

Nothing to configure: the feed is generated on its own, one per language, at /pt/rss.xml and /en/rss.xml. It is already announced in the <head> of every page, so feed readers find it by themselves, and there is an icon in the footer. Title, description and domain come from SITE — changing your identity in step 2 already fixes the feed.

Drafts never reach the feed.

11. Publishing

npm run build produces the static dist/ folder, which runs on any host: object storage, a CDN, a static host, or classic shared hosting.

The template ships no deploy workflow, deliberately: automation belongs to a concrete site, with its own host and credentials, and a workflow that cannot run is a red CI badge on every fork before it has decided anything. Once you have hosting, the Deploying section of the README covers the two transports that fit shared hosting — rsync over SSH and FTPS — with the traps of each.

Before publishing, npm test is worth the minute it takes: besides checking the build, it verifies that your configuration hangs together — a language without its translations, a skin that does not exist, consent switched off while analytics is on.

There you go — the skeleton is yours. The next step is the one that matters most: writing posts.

Writing posts in Buildando

Mon, 20 Jul 2026 00:00:00 GMT

With the blog installed and customized, writing is the easy part — and the reason the template exists.

A post is a folder

To publish, create a directory in src/content/posts/ with an index.md inside. Nothing else in the project changes.

src/content/posts/
  my-first-post/
    index.md      ← the content
    cover.png     ← images live next to the markdown

The folder name becomes the post’s address (its slug): my-first-post → /en/posts/my-first-post/.

The frontmatter

The block at the top of index.md describes the post. Three fields are required — the build fails and names the post and the field when one is missing:

---
title: "Post title"
description: "A one-sentence summary — it becomes the search snippet and the social preview."
publishDate: 2026-07-20
category: "Best Practices"
tags: [oo, testing]
cover: ./cover.png       # image colocated in the same folder (optional)
coverAlt: "Description of the cover"
draft: false             # true hides it from production
---

Your content in **markdown** here.

Everything else has a default. The full schema lives in src/content/config.ts.

Images

Put images in the post’s folder and reference them by relative path. At build time they are optimized and served in responsive sizes (WebP), with nothing for you to configure:

![A diagram](./diagram.png)

A nice detail: if you set no cover, the post automatically gets a branded social card, generated at build — so every post has a good image when shared, even when you draw none.

Drafts

draft: true keeps the post in the repository but out of production: it shows up only under npm run dev and is excluded from pages, listings, facets, sitemap, RSS, and search. Great for writing at your own pace before publishing.

Languages and translations

Every post declares its language with lang: and links its translations with translations::

lang: en
translations:
  pt: meu-primeiro-post   # the slug of the Portuguese version

The language switcher then goes straight to the translation. When there is none, it keeps you on the post and translates only the page’s interface.

What about CSS?

You need none. Markdown inherits the site’s typography — headings, lists, tables, quotes, and code blocks come out styled already. Write the way you think.

That’s it: delete the example posts, copy a folder as a base, and start writing.