Blog Workflow Part 1: Project Structure

July 18, 2026

This is Part 1 of a 3-part series documenting the blog workflow. This part covers the project structure, template architecture, and semantic HTML structure.

Project Structure

brennan.casa/
├── src/                          # Source directory (input for 11ty)
│   ├── _data/                    # Global data files
│   │   └── metadata.json         # Site metadata (title, description, URL)
│   ├── _includes/                # Reusable template components
│   │   ├── layouts/              # Page layout templates
│   │   │   ├── base.njk          # Base HTML layout
│   │   │   └── post.njk          # Blog post/note layout
│   │   └── partials/             # Reusable partials
│   │       ├── head.njk          # HTML head (meta tags, CSS, RSS)
│   │       ├── header.njk        # Site header with logo and nav
│   │       ├── nav.njk           # Navigation menu
│   │       └── footer.njk        # Site footer
│   ├── bookmarks/                # Bookmarks section
│   │   └── index.njk             # Bookmarks listing page
│   ├── css/                      # Stylesheets
│   │   └── styles.css            # Main stylesheet
│   ├── favicon/                  # Favicon files (copied to output)
│   ├── notes/                    # Notes section 
│   │   ├── index.njk             # Notes listing page
│   │   └── *.md                  # Individual note files
│   ├── posts/                    # Posts section
│   │   └── *.md                  # Individual post files
│   ├── feed.njk                  # RSS feed template
│   └── index.njk                 # Homepage
├── _site/                        # Generated output (gitignored)
├── .eleventy.js                  # 11ty configuration
├── package.json                  # Node.js dependencies and scripts
└── .gitignore                    # Git ignore rules

Template Architecture & Modularization

The site uses a hierarchical layout system with Nunjucks templates:

base.njk: The main layout that provides the HTML structure
- Includes partials/head.njk for the <head> section
- Includes partials/header.njk for the site header
- Includes partials/footer.njk for the site footer
- Renders {{ content | safe }} for the main content area
post.njk: Extends base.njk for blog posts and notes
- Sets layout: layouts/base.njk in frontmatter
- Adds article wrapper with title and date
- Renders the Markdown content

Partials are reusable components included across multiple pages:

head.njk: Meta tags, CSS links, favicon links, RSS feed, Open Graph and Twitter card metadata
header.njk: Site logo, title, and navigation
nav.njk: Navigation menu (Bookmarks, Notes, RSS, brennan.day)
footer.njk: Copyright and license information

Content is organized into two main collections:

Posts: Located in src/posts/, accessed via collections.posts
Notes: Located in src/notes/, accessed via collections.notes

Semantic HTML Structure

Layout Elements:

<div class="wrapper">: Container for header, main, and footer
<main>: Primary content area (page-specific content)
<header>: Site header with logo and navigation
<nav>: Navigation menu with unordered list of links
<footer>: Site footer with copyright and license info

Content Elements:

<article>: Self-contained content (blog posts, notes)
<h1>: Main heading (article title, site title in header)
<h2>: Section headings (in index pages)
<p>: Paragraphs
<small>: Smaller text (dates, footer license info)
<ul>: Unordered lists (navigation, content listings)
<li>: List items
<a>: Hyperlinks
<img>: Images with alt text for accessibility

Semantic Benefits: Screen readers can navigate by semantic elements. And the clear document structure helps maintainability for future development.

Markdown to HTML Example

Here's how a simple Markdown file transforms into semantic HTML through the 11ty build process:

Input: Markdown File (`src/notes/example.md`)

---
layout: layouts/post.njk
title: Example Note
date: 2026-07-19
tags: [note]
---

This is a sample note to demonstrate the semantic HTML structure.

## Key Points

- First important point
- Second important point
- Third important point

The site uses semantic elements for better accessibility.

Output: Generated HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Example Note</title>
    <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
    <div class="wrapper">
        <header>
            <div class="header-content">
                <a href="https://brennan.casa">
                    <img src="/favicon/android-chrome-512x512.png" alt="brennan.casa logo" class="site-logo">
                    <h1>brennan.casa</h1>
                </a>
            </div>
            <nav>
                <ul>
                    <li><a href="/bookmarks/">Bookmarks</a></li>
                    <li><a href="/notes/">Notes</a></li>
                    <li><a href="/feed.xml">RSS</a></li>
                </ul>
            </nav>
        </header>
        <main>
            <article>
                <h1>Example Note</h1>
                <p><small>July 19, 2026</small></p>
                <p>This is a sample note to demonstrate the semantic HTML structure.</p>
                <h2>Key Points</h2>
                <ul>
                    <li>First important point</li>
                    <li>Second important point</li>
                    <li>Third important point</li>
                </ul>
                <p>The site uses semantic elements for better accessibility.</p>
            </article>
        </main>
        <footer>
            <p>&copy; 2026 brennan.casa</p>
        </footer>
    </div>
</body>
</html>

Next Steps

Continue to Part 2: Build Process & Deployment to learn about the build process, deployment workflow, and server configuration.