monitoring

Installing Astro on macOS — Part 1 of Building an Obsidian-Powered Website Platform

Modern websites have become strangely overcomplicated.

Many traditional CMS platforms begin as simple publishing systems and gradually evolve into sprawling collections of plugins, databases, builders, integrations, tracking scripts, and background services quietly consuming resources somewhere in the dark.

For many technical websites, that complexity simply is not necessary.

This series documents the creation of a lightweight publishing platform built around two tools that complement each other exceptionally well:

• Obsidian for operational knowledge, research, planning, and long-term documentation
• Astro for the public-facing publishing layer

The overall philosophy is straightforward:

Build → Document → Publish

Everything begins inside the vault.

The website simply becomes the presentation layer.

This approach works particularly well for:

• technical blogs
• monitoring systems
• dashboards
• SDR projects
• weather telemetry
• Raspberry Pi systems
• experimental engineering
• long-term research archives
• data-driven websites

Rather than forcing everything through a conventional CMS, the system separates operational work from public publishing.

In practice, that separation becomes one of the biggest advantages.

Why Astro and Obsidian Should Remain Separate

One of the most common mistakes when building modern publishing systems is trying to combine the website and the knowledge system into a single directory structure.

Avoid doing that.

Your Obsidian vault is not the website.

It is the workshop.

It contains:

• research
• project notes
• article drafts
• experiments
• telemetry observations
• diagrams
• planning systems
• AI workflows
• documentation
• the inevitable pile of “temporary” notes that somehow survive indefinitely

The Astro project, meanwhile, is purely the publishing and presentation layer.

It handles:

• layouts
• navigation
• styling
• routing
• SEO
• deployment
• rendering content into an actual website

Keeping the two systems separate avoids several long-term headaches:

• plugin conflicts
• bloated repositories
• enormous vault sizes
• accidental corruption
• deployment chaos
• duplicated files appearing mysteriously after sync operations

A sensible structure might look like this:

~/Projects/my-astro-site

for the website itself, and:

~/Documents/MyObsidianVault

for the operational vault.

Simple systems generally survive longest.

That rule applies surprisingly often in both software and RF engineering.

Step 1 — Open Terminal

On macOS:

• Press Cmd + Space
• Type Terminal
• Press Enter

You are now staring into the traditional black rectangle where most modern infrastructure still somehow begins.

Step 2 — Check Whether Node.js Is Installed

Astro requires Node.js.

Check whether it is already installed:

node -v

If installed correctly, you should see something similar to:

v22.3.0

If instead you see:

command not found

then install Node.js using Homebrew:

brew install node

Once complete, verify again:

node -v

Realistically, a fair amount of modern web development eventually becomes:

• checking versions
• updating dependencies
• wondering why something worked perfectly yesterday but refuses to function today

Best to accept that early.

Step 3 — Create a Dedicated Projects Folder

Create a clean location for development work:

mkdir -p ~/Projects
cd ~/Projects

This keeps website projects separate from documents, downloads, screenshots, and whatever collection of experimental files currently occupies the desktop.

Step 4 — Create the Astro Project

Now generate the Astro site itself.

Run:

npm create astro@latest

Astro will guide you through several setup questions.

Use the following options:

The important part here is choosing the minimal template.

Avoid beginning with every possible feature enabled.

Most technical websites evolve gradually anyway. The architecture becomes clearer once real content, telemetry, dashboards, and systems begin flowing through it.

Step 5 — Enter the Project Folder

Once setup finishes:

cd my-astro-site

You are now inside the Astro project itself.

Step 6 — Start the Development Server

Launch Astro:

npm run dev

You should see output resembling:

localhost:4321

This means the local development server is running correctly.

Step 7 — Open the Site in Your Browser

Open:

http://localhost:4321

If the Astro starter page appears:

everything is functioning correctly.

Which, in technical projects, is always worth appreciating briefly before changing something else and breaking it again.

What You Have at This Point

You now have:

• a modern static website framework
• a lightweight development environment
• Git-enabled version control
• a clean publishing foundation
• separation between operational knowledge and public presentation

More importantly, you now have the beginnings of a proper modern publishing platform.

One where:

• Obsidian manages knowledge
• Astro handles presentation
• Markdown becomes the content engine
• dashboards and telemetry integrate naturally
• the infrastructure remains lightweight and portable

This overall approach creates a far more flexible and maintainable system than relying on a large monolithic CMS packed with features you may never actually need.

What Comes Next

In Part 2, the focus shifts towards structuring Astro properly for long-term use.

That includes:

• removing the starter clutter
• building a clean folder architecture
• installing Tailwind CSS
• creating reusable layouts
• preparing Markdown collections
• organising assets and content properly
• preparing the system for publishing directly from the vault

The interesting part begins once the platform stops looking like a generic starter template and starts behaving like a real operational publishing system.