How I built and organized my blog with Astro JS

Introduction 👋

To provide some context, in 2022, I used Hugo as the static site generator for my blog.

In 2023, I conducted a technological review of various static site generators. This led me to adopt Astro, and I wrote an article about it.

In this blog post, I’ll show you how I organized my code and share my workflows.

From Hugo to Astro 💫

I chose to migrate from Hugo to Astro to gain more control over my blog.

While Hugo is excellent for websites with extensive content like documentation, my needs were different: I wanted to build a comfortable site that reflected my personality.

I preferred Astro for several reasons:

Hugo’s syntax can be cumbersome: I found the syntax of shortcodes to be quite awkward, especially for generating diagrams. I prefer not to use custom syntax for my needs, as it would make migrating from Hugo more difficult in the future, requiring me to rewrite my content.
Astro is built with JavaScript and Vite: I am very familiar with these mature, highly customizable technologies that have a large community. Astro also supports TypeScript, a tool I love! This gives me 100% control over how my blog is built, aligning perfectly with the Astro philosophy.

Folder structure 🛠️

Let’s dive into my code organization 😮 ! The structure I use looks like this:

.
├── .astro/
├── .git/
├── dist/
├── node_modules/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── content/
│   ├── functions/
│   ├── pages/
│   ├── plugins/
│   └── env.d.ts
├── .env
├── .env.example
├── .gitignore
├── .prettierignore
├── .prettierrc.mjs
├── Makefile
├── README.md
├── astro.config.ts
├── package-lock.json
├── package.json
├── tailwind.config.cjs
└── tsconfig.json

Public directory (`./public/`)

This directory contains all the files I want to push to the server without any processing.

.
├── .htaccess
├── robots.txt
└── pdf/

Assets (`./src/assets/`) 🖼️

This directory contains all the compiled assets, such as images and icons.

.
└── img/
    ├── hero.svg
    ├── icon.png
    ├── icon.svg
    ├── profile.jpg
    └── icons/

Components (`./src/components/`) 🧩

This directory contains all the components of the website.

I use atomic design to organize my components.

.
└── components/
    ├── atoms/
    ├── molecules/
    ├── organisms/
    ├── templates/
    └── index.ts

This is why I don’t have a ./src/layouts/ directory, even though it is recommended in the documentation. Instead, all my layouts are in the ./src/components/templates/ directory.

You’ll also notice an index.ts file, which I use to re-export all the components. And I avoid using export default to keep the variable names clean.

I style my components with TailwindCSS.

I don’t have CSS files to build my blog. Everything is managed with TailwindCSS, and I am very happy with it! The documentation recommends having a ./src/styles/ directory, but I don’t need it.

Note: to use components with dark mode, I have configured Tailwind like this:

/** @type {import('tailwindcss').Config} */
export default {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
  darkMode: "class",
  theme: {
    extend: {},
  },
  plugins: [
    require("@tailwindcss/typography"),
    require("@tailwindcss/aspect-ratio"),
    require("@tailwindcss/forms"),
  ],
};

Next, I add the dark class to the <html> element. This enables dark mode without needing any contexts or global variables (we reduce dependencies this way)!

Translations (I don’t have any specific directory 😋) 🈂️

To set up internationalization (i18n), I followed this recipe and used the Astro APIs directly.

I forced the URLs to include the language, like “/en/about-me”.

If users navigate to ”/”, they will be redirected to “/en/”.

To achieve this, I use this code:

---
import { getAbsoluteLocaleUrl } from "astro:i18n";

const url = getAbsoluteLocaleUrl("en");
---

<!doctype html>
<html lang="en">
  <head>
    <title>Redirection to {url}</title>
    <link rel="canonical" href={url} />
    <meta name="robots" content="noindex" />
    <meta charset="utf-8" />
    <meta http-equiv="refresh" content={`0; url=${url}`} />
  </head>
</html>

Note: Since I use Apache with a .htaccess file, I added a 301 redirect header like this:

<IfModule mod_rewrite.c>
    RewriteEngine On

    RedirectMatch 301 "^/$" "https://www.alexandre-hublau.com/en/"
</IfModule>

I don’t have a specific /i18n/ directory for translations. Instead, I use a function to print the correct translation like this:

---
const { translate } = useTranslation(Astro.currentLocale);
---
<div>
  {translate({en: "Hello !", fr: "Salut !", de: "Hallo !"})}
</div>

This approach avoids managing files with numerous key/value translations, as described here.

Content (`./src/content/`) 📝

This directory contains all the site’s content, stored as md or mdx files.

Astro natively manages content.

I use these conventions/tools:

Content files are named with a format like “2024-08-22-my-slug.md(x)”. Example:

.
├── 2021-09-25-technological-watch-react-js.mdx
├── 2021-10-12-technological-watch-alpine-js.md
├── 2021-10-15-technological-watch-ansible.mdx
├── 2021-10-31-code-share-docker-apache-mysql-php.md
├── 2021-11-21-technological-watch-cassandra.md
...

I use this file naming convention because it automatically sorts posts by date when I look in the file explorer, ensuring the newest content is always at the bottom. However, it has a drawback: releasing two articles on the same day can disrupt the order.

I use Expressive Code to render code blocks
I use Mermaid to render diagrams
Content is typed with TypeScript. You can generate types with Astro with the command: astro sync. You can find more information in the documentation

Everything is versioned with Git as part of the source code!

Functions (`./src/functions/`) ⚙️

All the functions are implemented in TypeScript, which provides strong typing to minimize errors and prevent bugs. Astro’s type-checking (astro check) generates reports for type errors, enhancing code reliability. Additionally, TypeScript can identify breaking changes introduced by package updates, ensuring smoother maintenance and updates.

This directory contains all functions shared across components. It is organized by type.

.
├── index.ts
├── date/
│   ├── calculateYearInterval/
│   │   ├── calculateYearInterval.test.ts
│   │   └── calculateYearInterval.ts
│   └── isDateWithinDays/
│       ├── isDateWithinDays.test.ts
│       └── isDateWithinDays.ts
├── hooks/
│   ├── useTranslation.test.ts
│   └── useTranslation.ts
├── post/
│   ├── calculateRecommendedPosts/
│   │   ├── calculateRecommendedPosts.test.ts
│   │   └── calculateRecommendedPosts.ts
│   └── generateSummary/
│       ├── generateSummary.test.ts
│       └── generateSummary.ts
└── string/
    ├── addNonBreakingSpacePunctuation/
    │   ├── addNonBreakingSpacePunctuation.test.ts
    │   └── addNonBreakingSpacePunctuation.ts
    ├── capitalize/
    │   ├── capitalize.test.ts
    │   └── capitalize.ts
    ├── extractUrlInfo/
    │   ├── extractDateFromFileName.test.ts
    │   ├── extractSlugFromFileName.ts
    │   └── extractUrlInfo.ts
    └── parseMarkdown/
        ├── parseMarkdown.test.ts
        └── parseMarkdown.ts

All the functions are paired with a corresponding test to ensure thorough testing and to prevent any missing tests. I use Vitest to run these tests.

You’ll also notice an index.ts file, which I use to re-export all the functions. And I avoid using export default to keep the variable names clean.

Pages (`./src/pages/`) 📑

This directory contains all the routes of my application. These files serve two main roles:

Prepare the routing using the getStaticPaths function.
Execute queries to fetch content, images, and translations (if needed).

.
├── index.astro
├── _routes.ts
├── de/
│   └── uber-mich.astro
├── en/
│   ├── 404.astro
│   ├── about-me.astro
│   ├── ui.astro
│   └── posts/
│       └── rss.xml.ts
├── fr/
│   ├── a-propos.astro
│   └── posts/
│       └── rss.xml.ts
└── [locale]/
    ├── index.astro
    └── posts/
        ├── it/
        │   ├── index.astro
        │   ├── [slug].astro
        │   └── tags/
        │       └── [tag].astro
        └── me/
            ├── index.astro
            └── [slug].astro

You can also notice a _routes.ts file. This file is not present in the dist folder. It simply re-exports the routes and connects similar pages together. This is particularly useful in the navbar for language switching. For example, if you are on the /en/about-me/ page and want to switch to French, this dictionary helps query the corresponding French page (in this case, /fr/a-propos/).

export type Language = "fr" | "en" | "de";

export const ROUTES = {
  rss: {
    fr: "/posts/rss.xml",
    en: "/posts/rss.xml",
  },
  about: {
    fr: "/a-propos/",
    en: "/about-me/",
    de: "/uber-mich/",
  },
  posts_it: {
    fr: "/posts/it/",
    en: "/posts/it/",
  },
  posts_me: {
    en: "/posts/me/",
  },
  welcome: {
    fr: "/",
    en: "/",
    de: "/",
  },
} as const;

Plugins 🔌

This directory contains the plugins and integrations I want to add. For example, I have a mermaid integration. You can find more information here.

Code Tools 🔧

I don’t use many code tools. I primarily use git to version the code and the blog content.

Node Packages 📦

Here is the list of the Node packages I use:

Astro Integration: astro, astro-expressive-code, @astrojs/alpinejs, @astrojs/check, @astrojs/markdown-remark, @astrojs/mdx, @astrojs/rss, @astrojs/sitemap, @astrojs/tailwind
TypeScript: typescript, @types/alpinejs, @types/node
TailwindCSS: tailwindcss, @tailwindcss/aspect-ratio, @tailwindcss/forms, @tailwindcss/typography, clsx
Alpine: alpinejs
Knip (detect unused code): knip
Mermaid (draw diagrams): mermaid, unist-util-visit
Prettier (format the code): prettier, prettier-plugin-astro, prettier-plugin-astro-organize-imports, prettier-plugin-tailwindcss
Vitest (run tests): vitest

TypeScript configuration 🇹🇸

Here is my TypeScript configuration:

{
  "extends": "astro/tsconfigs/strictest",
  "types": ["vite/client"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["dist", "public"]
}

I use the strictest configuration to adhere to good coding practices and avoid bugs.

I have to exclude the dist folder; otherwise, it crashes for some reason with Mermaid JS.

Prettier configuration ✨

/** @type {import("prettier").Config} */
export default {
  tailwindFunctions: ["clsx"],
  plugins: [
    "prettier-plugin-astro",
    "prettier-plugin-tailwindcss",
    "prettier-plugin-astro-organize-imports",
  ],
  overrides: [
    {
      files: "*.astro",
      options: {
        parser: "astro",
      },
    },
  ],
};

Workflows 🔀

In the package.json file, I have several scripts to handle the building of the site:

{
  // ...
  "scripts": {
    "disable_telemetry": "astro telemetry disable",
    "test": "vitest run",
    "check": "astro check",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "npm run check && npm run test && astro build",
    "preview": "astro preview",
    "astro": "astro",
    "prettify": "prettier --write './src/'",
    "knip": "knip"
  },
  // ...
}

In the Makefile, I have higher level helpers:

SHELL := /bin/bash
include .env

help:
  # ...

#-- update blog
npm_update: ## Update the node_modules
  # ...

commit_update_node_modules: ## Commit updated node_modules
  # ...

#-- stats
get_blog_size: ## Calculate the blog size
  # ...

logs: ## git logs
  # ...

#-- admin section
envoy: ## Build and deploy the application
  # ...
  @echo "Application deployed !"

Choices 💭

I want to depend to the less node packages as possible.

I am using Alpine integration to manage user interactions. Before, I used Svelte, but I got difficulties to manage translations, display resized images, and implementing Markdown syntax highlighting. With Alpine, I can use even in .astro file, so I can have the full Astro API.

To make my website look like an SPA, I can use the transition API: (https://astro.build/blog/future-of-astro-zero-js-view-transitions/)

No big framework is needed !

In the future: what’s next? ⏳

Looking ahead, I have several plans to evolve my website:

Design Improvements: I aim to enhance the design of my website.
Component UI Page: I have a UI page to check my components. I’m considering integrating it with StoryBook once an integration becomes available. The progress can be followed here.
Astro 5: with Astro 5 on the horizon, I’m excited to see how it evolves. Some file scripts might become obsolete, simplifying the code further?
Tailwind 4: the release of Tailwind 4 is also on the horizon.
Code Hike Compatibility: I’m hopeful that libraries like Code Hike will become compatible with Astro. You can read more about it here.

Let’s see what the future holds! 🔮