Project Structure

PaperHouse is organized into clear folders so you always know where to edit. This page explains what every folder does and when to touch it.

Top-level overview

paperhouse-theme/
├── public/
├── src/
│   ├── components/
│   ├── content/
│   ├── data/
│   ├── layouts/
│   ├── pages/
│   └── styles/
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── README.md

public/ — static files

The public/ folder holds files served exactly as-is. Nothing is processed, compiled, or optimized.

Use public/ for:

• Favicon — favicon.svg
• Logo mark — astro.svg
• OG images — social share previews at /og/*.jpg
• Robots file — robots.txt
• Static PDFs — résumés, press kits
• Self-hosted fonts — if you prefer not to use Google Fonts

Any file in public/ is accessible at the root URL.

• public/favicon.svg → https://your-site.com/favicon.svg
• public/og/cover.jpg → https://your-site.com/og/cover.jpg

Never put page content or source code in public/. It is only for static assets.

src/components/ — reusable UI

components/
├── BentoCard.astro        Reusable bento grid card
├── home/                  Home page sections
│   ├── Hero.astro         Hero block
│   ├── Marquee.astro      Infinite ticker
│   ├── WhySells.astro     Feature + image block
│   ├── Journal.astro      Latest posts preview
│   └── CTA.astro          Final call-to-action
└── partials/              Global site chunks
    ├── Navbar.astro       Top navigation
    ├── MobileDrawer.astro Mobile menu drawer
    └── Footer.astro       Site footer

When to edit:

• Navbar, footer, mobile menu → partials/
• Home page hero, marquee, CTA → home/
• Bento card appearance → BentoCard.astro

src/content/ — markdown content

Every piece of content lives here as markdown.

content/
├── blog/        Journal posts
├── contact/     Contact page data
├── docs/        Documentation
├── pages/       Static pages (about, order)
└── works/       Case studies

Markdown files have two parts:

1. Frontmatter — metadata between --- fences at the top
2. Body — regular markdown content below

Each folder has its own schema in src/content.config.ts.

When to edit:

• Add a work → works/your-project.md
• Publish a post → blog/your-post.md
• Create an about page → pages/about.md
• Update contact info → contact/contact.md

src/data/ — JSON configuration

All site-wide configuration lives in JSON. This is how PaperHouse stays free of hardcoded text.

data/
├── site.json       Brand, nav, footer, SEO
├── home.json       Home page copy
├── work.json       Works page labels
├── blog.json       Blog page labels
├── category.json   Category page labels
├── tag.json        Tag page labels
└── docs.json       Docs sidebar structure

When to edit:

• Change brand name or nav links → site.json
• Rewrite home hero → home.json
• Rename labels → work.json, blog.json
• Add a docs section → docs.json

src/layouts/ — page wrapper

Base.astro is the root layout. Every page wraps itself in <Base>.

It handles:

• HTML <head> — meta tags, OG, Twitter, canonical
• Navbar and mobile drawer
• Main content slot
• Footer
• Mobile menu script

You rarely edit this file.

src/pages/ — routes

Astro uses file-based routing. Every file in pages/ becomes a route.

pages/
├── index.astro          → /
├── [slug].astro         → /about, /order, /faq
├── contact.astro        → /contact
├── 404.astro            → error page
├── blog/
│   ├── index.astro      → /blog
│   └── [...slug].astro  → /blog/post-name
├── category/
│   ├── index.astro      → /category
│   └── [cat].astro      → /category/branding
├── docs/
│   ├── index.astro      → /docs
│   └── [...slug].astro  → /docs/getting-started
├── tag/
│   ├── index.astro      → /tag
│   └── [tag].astro      → /tag/typography
└── works/
    ├── index.astro      → /works
    └── [...slug].astro  → /works/project-name

When to edit:

• Adding a whole new section → add a folder
• Custom layout for one page → add a .astro file

src/styles/ — global CSS

styles/
└── globals.css

Contains:

• Google Fonts import
• Tailwind import
• @theme block (colors, fonts, radii)
• Global element styles
• .bento card class
• Stabilo highlight classes

When to edit:

• Change brand colors → edit @theme colors
• Change fonts → edit @theme fonts
• Add a global class → add it here

Config files

File	Purpose
astro.config.mjs	Site URL, integrations, Vite plugins
package.json	Dependencies and npm scripts
tsconfig.json	TypeScript settings
README.md	Quick-start guide

The three rules of PaperHouse

1. Content in content/.
Never hardcode text in a .astro file.

2. Config in data/.
Brand names, nav labels, footers, SEO titles — all JSON.

3. Layout in layouts/ and pages/.
Templates are the only place for HTML structure and Tailwind classes.