Project Structure

Project Structure

This guide explains how ForgeDocs is organized. If you understand the folder structure, you can find and edit any file quickly.

ForgeDocs follows the standard Astro project layout, with a few additions for JSON-driven content.

Top-Level Folders

forgedocs/
├── public/
├── src/
├── astro.config.mjs
├── package.json
├── content.config.ts
└── tsconfig.json

public/

Static files that are served as-is. Anything in public/ is available at the root URL.

Common files:

• public/logo.svg — site logo
• public/favicon.svg — browser favicon
• public/apple-touch-icon.png — iOS home screen icon
• public/admin/ — Decap CMS admin panel
• public/uploads/ — media uploaded via Decap CMS

Rule: Never put source code or page content here. Only static assets.

src/

All your source code lives here.

src/
├── components/
├── content/
├── data/
├── layouts/
├── pages/
└── styles/

src/components/

Reusable UI components.

src/components/
├── custom/
│   ├── Footer.astro
│   ├── Header.astro
│   ├── Hero.astro
│   ├── PageFrame.astro
│   ├── PageTitle.astro
│   ├── Pagination.astro
│   ├── Sidebar.astro
│   └── TableOfContents.astro
├── layout/
│   └── Navbar.astro
└── starlight/
    └── Search.astro

custom/ — Overrides for Starlight components. Edit these to change how docs look.

layout/ — Site-wide layout components. Navbar.astro is used on the landing page, blog, and static pages.

starlight/ — Starlight-specific overrides.

src/content/

All content lives here, organized by collection.

src/content/
├── blog/
│   ├── first-post.md
│   └── second-post.md
├── docs/
│   ├── introduction.md
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── run-project.md
│   │   └── ...
│   └── developer-guide/
│       ├── project-structure.md
│       └── ...
└── pages/
    ├── about.md
    ├── faq.md
    ├── terms.md
    └── privacy.md

blog/ — Blog posts. Each .md file is a post.

docs/ — Documentation pages. Folders become sidebar groups.

pages/ — Static pages (About, FAQ, Terms, Privacy). Rendered dynamically at /{filename}.

src/data/

JSON files that drive the site content.

src/data/
├── blog.json
├── contact.json
├── faq.json
├── features.json
├── footer.json
├── home.json
├── navbar.json
├── seo.json
└── site.json

home.json — Landing page content (hero, features, pricing, CTA)

navbar.json — Navigation links and brand

footer.json — Footer columns, social links, copyright

seo.json — Site-wide SEO metadata

site.json — Site name, version, tagline

features.json — Features page content

contact.json — Contact page content and form config

faq.json — FAQ content

blog.json — Blog text labels (titles, pagination, etc.)

src/layouts/

Reusable page layouts.

src/layouts/
└── BaseLayout.astro

BaseLayout.astro — The root layout for all non-Starlight pages. Handles:

• HTML head (meta tags, fonts, theme script)
• Navbar
• Footer
• Skip link

Every page (index.astro, blog/*, features.astro, etc.) wraps its content in <BaseLayout>.

src/pages/

File-based routing. Every file becomes a URL.

src/pages/
├── index.astro              → /
├── about.astro              → /about
├── contact.astro            → /contact
├── features.astro           → /features
├── [page].astro             → /{slug} (dynamic static pages)
└── blog/
    ├── index.astro          → /blog
    ├── [...slug].astro      → /blog/{slug}
    ├── tags.astro           → /blog/tags
    ├── tag/
    │   └── [tag].astro      → /blog/tag/{tag}
    └── page/
        └── [page].astro     → /blog/page/{n}

**[page].astro** — Dynamic route that renders static pages from src/content/pages/`.

src/styles/

CSS files.

src/styles/
└── landing.css

landing.css — All custom styles for the landing page, blog, static pages, and docs.

Configuration Files

astro.config.mjs

Main Astro configuration:

• Site URL
• Integrations (Preact, Sitemap, Starlight)
• Starlight config (title, sidebar, components)
• Vite config (path aliases)

content.config.ts

Content collection definitions:

• docs — Starlight docs
• blog — Blog posts
• pages — Static pages

package.json

Project metadata and scripts:

• npm run dev — Start dev server
• npm run build — Build for production
• npm run preview — Preview production build

tsconfig.json

TypeScript configuration. Includes path alias @/* → src/*.

Path Aliases

ForgeDocs uses the @ alias for imports:

import BaseLayout from '@/layouts/BaseLayout.astro';
import Navbar from '@/components/layout/Navbar.astro';

@ maps to src/. Configured in astro.config.mjs:

vite: {
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
},

Where to Edit What

I want to change…	Edit this file
Landing page hero	src/data/home.json
Navigation links	src/data/navbar.json
Footer links	src/data/footer.json
Site title & description	src/data/seo.json
Blog post	src/content/blog/*.md
Docs page	src/content/docs/**/*.md
About page	src/content/pages/about.md
FAQ page	src/content/pages/faq.md
Pricing	src/data/home.json (pricing.plans)
Contact form config	src/data/contact.json
Colors	src/styles/landing.css (:root variables)
Fonts	src/styles/landing.css (@import at top)
Starlight sidebar	astro.config.mjs (sidebar array)
Starlight components	src/components/custom/*.astro

The JSON-Driven Approach

ForgeDocs uses JSON for all site-wide content:

Why JSON?

• Easy to edit — no code required
• Easy to translate — swap JSON files for multi-language
• Easy for Decap CMS — collections map directly to JSON files
• Easy to version — Git tracks every change

What’s in JSON vs Markdown?

Content type	Format
Landing page sections	JSON
Navigation, footer	JSON
Site metadata, SEO	JSON
Blog posts	Markdown
Docs pages	Markdown
Static pages	Markdown

Rule of thumb: Fixed UI text goes in JSON. Content that grows over time (posts, docs) goes in Markdown.

What’s Next

Now that you know the structure, learn to update content:

→ Update JSON Data

→ Update Pages

→ Others

Need Help?

If you’re stuck:

• Check the FAQ
• Email creativebydre@gmail.com
• For custom work, hire me on Fiverr