110 Pages, Zero Lines of Code: How My Site Was Built
The architecture deep dive: how Astro, MDX, and Tailwind CSS work together to turn 21 content files into 110 pages. Explained by a civil engineer.
110 Pages, Zero Lines of Code: How My Site Was Built
Part 5 of โA Civil Engineerโs Website Building Diary.โ This is the architecture deep dive.
Building a Website Like Building a Building
As a structural engineer, I found a surprising overlap between constructing buildings and constructing websites:
| Construction | Web Development |
|---|---|
| Blueprints | Tech stack (Astro/MDX/Tailwind) |
| Foundation | Project skeleton (directory structure) |
| Load-bearing structure | Layout system |
| Prefabricated parts | Components |
| Interior finish | CSS styling |
| Room zoning | Page routing |
| Plumbing & electrical | SEO infrastructure |
| Furniture | Content (articles/videos) |
This mental model made everything click for me.
The Tech Stack (In Plain English)
Astro 5.x โ The Foundation
Astro is a static site generator. It takes your content files and converts them into pure HTML pages. Why this matters: Googleโs crawlers love static HTML. It loads fast, is easy to parse, and ranks well.
Think of it as prefabricated construction โ all pages are manufactured in advance, ready to serve instantly.
MDX โ The Content Format
MDX = Markdown + Components. You write articles using simple Markdown syntax (# for headings, - for lists, ** for bold), but can also embed interactive modules like video players or newsletter signup forms.
All 9 blog articles and 12 video pages are MDX files. Writing them feels like writing notes, not code.
Tailwind CSS โ The Styling
A utility-first CSS framework with thousands of predefined style classes. Instead of writing custom CSS (which I canโt do), you add class names like text-blue-600 font-bold to elements. Cursor handles this entirely.
Project Structure
src/
โโโ components/ # 10 reusable UI modules
โ โโโ Header.astro
โ โโโ Footer.astro
โ โโโ Sidebar.astro
โ โโโ Newsletter.astro
โ โโโ Breadcrumb.astro
โ โโโ SEO.astro
โ โโโ ArticleCard.astro
โ โโโ VideoCard.astro
โ โโโ LatestVideos.astro
โ โโโ YouTubeEmbed.astro
โโโ config/ # Configuration
โ โโโ taxonomy.ts # 8 categories + 69 tags
โ โโโ youtube.ts # Channel settings
โโโ content/ # All content
โ โโโ blog/ # 9 articles (MDX)
โ โโโ videos/ # 12 video pages (MDX)
โ โโโ config.ts # Collection schemas
โโโ layouts/ # Page templates
โ โโโ BaseLayout.astro
โ โโโ BlogPost.astro
โโโ pages/ # Routes
โ โโโ index.astro
โ โโโ blog/
โ โโโ videos/
โ โโโ topic/
โ โโโ ... (about, privacy, etc.)
โโโ styles/global.css
โโโ utils/date.tsEvery folder has a clear, single responsibility. Like a well-organized blueprint.
10 Components = 10 Building Blocks
Components are reusable page modules โ designed once, used everywhere.
| Component | Purpose | Appears On |
|---|---|---|
| Header | Top navigation with logo | All pages |
| Footer | Copyright, links | All pages |
| Sidebar | Categories, recent content | Article/list pages |
| Newsletter | Kit email signup embed | Article/video bottoms |
| Breadcrumb | Navigation trail | All sub-pages |
| SEO | Meta tags, JSON-LD, Open Graph | All pages (invisible) |
| ArticleCard | Article preview card | List pages, homepage |
| VideoCard | Video thumbnail card | Video list, homepage |
| LatestVideos | Recent video list | Sidebar, homepage |
| YouTubeEmbed | YouTube iframe player | Video detail pages |
10 components. Infinite combinations. Every page on the site is assembled from these building blocks.
21 Files โ 110 Pages
Astroโs Content Collections feature is the magic multiplier.
I created 21 content files (9 blog + 12 video MDX files). Astro automatically generates:
| Page Type | Count | How Generated |
|---|---|---|
| Homepage | 1 | Manual |
| Blog articles | 9 | From blog/ MDX files |
| Blog list | 1 | Auto-generated |
| Blog tag pages | ~20 | Auto from tags |
| Video pages | 12 | From videos/ MDX files |
| Video list | 1 | Auto-generated |
| Video category/tag pages | ~50 | Auto from categories/tags |
| Topic hub pages | ~10 | Auto from taxonomy |
| Static pages | 4 | Manual (about, privacy, etc.) |
| Total | ~110 |
The content-to-page multiplication is powerful. Write 21 files, get 110 pages. Each with proper SEO, navigation, and structured data.
SEO Infrastructure
The invisible layer that makes Google happy:
Sitemap
Auto-generated at /sitemap.xml on every build. Submitted to Google Search Console. Lists every page on the site.
robots.txt
Directs search engine crawlers โ which pages to index, which to skip.
JSON-LD Structured Data
Every page includes structured data telling Google:
- Article pages: title, author, publish date, category
- Video pages: name, duration, thumbnail, upload date
- All pages: breadcrumb hierarchy
Open Graph Tags
Social sharing metadata โ when someone shares a link on Twitter or Facebook, it automatically displays the title, description, and preview image.
Key Design Decisions
Pure static mode. All pages pre-built as HTML. No server-side rendering needed. Hosted free on Cloudflare Pages. Fastest possible load times.
Strict taxonomy. 8 categories and 69 tags defined in taxonomy.ts with type checking. Prevents typos and inconsistencies. Like a materials specification document in construction โ every material is pre-defined.
Content-driven architecture. The site structure is determined by content, not by manual page creation. Add an article โ tag/category/list pages update automatically.
Summary for Non-Technical Readers
- Astro converts content into Google-friendly HTML pages
- MDX lets you write articles like notes
- Tailwind makes the site look professional
- 10 components combine like Lego to form all pages
- 21 content files automatically generate 110 pages
- SEO infrastructure helps Google find and understand your content
My role in all of this: describe โ choose โ verify โ adjust.
Code written by me: zero.
Next: How AI helped me write 9 SEO-optimized English articles (as someone who can barely write English).