Folder Structure

Folder Structure

When you first open the Astro Docus project, you will see dozens of files and folders. It looks intimidating, but every single item has a clear purpose.

This page explains what each folder does, why it exists, and when you will actually touch it. By the end, you will know exactly where to go for any change you want to make.

---

The Big Picture

Astro Docus is organized around three ideas:

1. Config files (root) — the brain of the project.
2. Static assets (public/) — files served as-is to the browser.
3. Source code (src/) — everything Astro processes and builds.

Here is the top-level view:

astrodocus/
├── .npmrc
├── astro.config.mjs
├── astrodocumentationwebsite.jpg
├── package.json
├── README.md
├── tsconfig.json
├── public/
└── src/

Everything else lives inside public/ or src/.

---

Root Files

These files sit at the very top of the project. They control how the project is installed, built, and configured.

File	Purpose	Do you edit it?
.npmrc	npm configuration (registry, install behavior)	Rarely
astro.config.mjs	Main Astro + Starlight configuration	✅ Yes
astrodocumentationwebsite.jpg	Preview image used in README	Optional
package.json	Project metadata + dependency list	Occasionally
README.md	Project description shown on GitHub / Gumroad	Optional
tsconfig.json	TypeScript configuration	No

astro.config.mjs

The main brain of the project. This is where you set:

• Site URL
• Adapter (Cloudflare, Vercel, Netlify, etc.)
• Site title, description, logo
• Sidebar structure
• Social links
• Table of contents levels

👉 Full breakdown in: Configuration

package.json

Lists every library the project depends on. When you run npm install, npm reads this file and downloads the right versions.

You will only edit this if you want to:

• Add a new library
• Change the project name
• Add custom scripts

tsconfig.json

TypeScript configuration. Astro uses TypeScript for type safety, even if you write plain JavaScript.

Do not edit unless you know what you are doing.

.npmrc

Controls how npm installs packages. Astro Docus ships with a preset that ensures consistent installs across machines.

Do not edit unless you have a specific reason.

---

public/ Folder

Files inside public/ are copied to the final build as-is. Astro does not process them — no minification, no transformation, no hashing.

Use public/ for:

• Favicon
• robots.txt
• sitemap.xml
• Static images you reference by URL
• Verification files (like Google Search Console HTML)

public/
├── favicon.svg
├── google7205e8d81ab78b75.html
├── robots.txt
├── sitemap.xml
├── startup.avif
├── img/
└── src/

Key files

File	Purpose
favicon.svg	The little icon next to the browser tab
robots.txt	Tells search engines what to crawl
sitemap.xml	Lists all pages for search engines
google7205e8d81ab78b75.html	Google Search Console verification
startup.avif	Static hero image used on landing page

public/img/

Small icons used in the landing page:

• data.svg
• deploy.svg
• install.svg
• start.svg

Note: The public/src/assets/ folder inside public/ is a mirror of the real src/assets/. It exists because some landing page sections reference images by absolute URL. You usually do not need to touch it.

---

src/ Folder

This is where the real work happens. Astro reads everything in src/, processes it, and builds the final site.

src/
├── env.d.ts
├── assets/
├── content/
├── data/
├── design/
├── pages/
├── styles/
└── widget/

src/env.d.ts

A tiny TypeScript file that tells the editor what types are available. Do not edit.

---

src/assets/

Images and icons used inside components. Unlike public/, files here are processed by Astro — they get hashed, optimized, and cached.

Contains dozens of files, including:

• astrologos.png — the logo referenced in astro.config.mjs
• article.svg, data.svg, deploy.svg — icons used in widgets
• cloudflare.svg, vercel.svg, netlify.svg — hosting provider logos
• astro.svg, astro-light.svg, astrodark.svg — Astro branding
• themes/ — preview images for theme cards

When to use src/assets/: When you want Astro to optimize or hash the image, or when you reference it from a component.

When to use public/: When you need a stable, predictable URL (favicon, robots.txt).

---

src/content/

This is where all your documentation lives. It uses Astro’s Content Collections system.

src/content/
├── config.ts
└── docs/
    ├── index.mdx
    ├── plan.mdx
    ├── cms/
    │   └── cloudcannon.md
    └── getstart/
        ├── article.md
        └── index.mdx

config.ts

Defines the schema for your content collections — what fields each page must have (title, description, etc.).

You edit this when you want to add new frontmatter fields.

docs/

Every file in here becomes a page on your documentation site.

File path	URL
docs/index.mdx	/
docs/getstart/index.mdx	/getstart/
docs/getstart/article.md	/getstart/article/
docs/cms/cloudcannon.md	/cms/cloudcannon/

This is the folder you will edit the most. Every new documentation page goes here.

Supported formats:

• .md — plain Markdown
• .mdx — Markdown with JSX (for interactive components)

---

src/data/

Stores JSON files that feed dynamic content into the site. This is why Astro Docus is called “JSON-driven.”

src/data/
├── home.json
├── configuration/
│   ├── blog/
│   │   └── blogpage.json
│   └── home/
│       └── homepage.json
├── index_page/
│   ├── cms.json
│   ├── folder.json
│   ├── getstart.json
│   ├── hosting.json
│   └── services.json
├── plan/
│   └── data.json
└── pricing/
    └── pricing.json

File	Feeds
home.json	The main landing page content
configuration/home/homepage.json	Homepage section config
configuration/blog/blogpage.json	Blog listing configuration
index_page/*.json	Card grids for CMS, folder, getstart, hosting, services
plan/data.json	Plan comparison table
pricing/pricing.json	Pricing page data

When to edit: When you want to change text, prices, or card content without touching components.

---

src/design/

Reusable page-level layouts. These wrap content and control overall structure.

src/design/
├── about.astro
├── base.astro
├── default.astro
├── PostSummary.astro
├── tags.astro
└── blog/
    ├── blog.astro
    ├── blogList.astro
    └── blogpost.astro

File	Purpose
base.astro	Base layout for all pages
default.astro	Default layout used by most pages
about.astro	About page layout
PostSummary.astro	Blog post summary card
tags.astro	Tag listing layout
blog/blog.astro	Blog homepage layout
blog/blogList.astro	Blog list layout
blog/blogpost.astro	Individual blog post layout

When to edit: When you want to change the structure of an entire page type.

---

src/pages/

Every file in src/pages/ becomes a route on your site. Astro’s file-based routing means the filename determines the URL.

src/pages/
├── rss.xml.js
├── blog/
│   ├── artcilepage-astro.md
│   ├── blog-detail.md
│   └── [...page].astro
├── categories/
│   ├── index.astro
│   └── [category].astro
└── tags/
    ├── index.astro
    └── [tag].astro

File	URL
rss.xml.js	/rss.xml — RSS feed
blog/artcilepage-astro.md	/blog/artcilepage-astro/
blog/[...page].astro	Paginated blog listing (/blog/, /blog/2/, …)
categories/index.astro	/categories/
categories/[category].astro	/categories/web/, /categories/dev/, etc.
tags/index.astro	/tags/
tags/[tag].astro	/tags/astro/, /tags/seo/, etc.

Note: Documentation pages are not in src/pages/ — they are auto-routed from src/content/docs/ by Starlight.

When to edit: When you want to add a brand-new page type or customize routing.

---

src/styles/

All CSS for the project.

src/styles/
├── base.css
├── bs.css
├── color.js
├── default.css
├── doc.css
└── index_page.css

File	Purpose
base.css	Referenced by astro.config.mjs as customCss. Main override file
bs.css	Additional styles
color.js	Color tokens
default.css	Default theme styles
doc.css	Documentation-specific styles
index_page.css	Landing page styles

The one you will edit most: base.css — it is loaded last and overrides everything else.

---

src/widget/

Reusable UI components. These are the building blocks of your pages.

src/widget/
├── BlogPost.astro
├── Features.astro
├── Header.astro
├── Help.astro
├── Intro.astro
├── Pagination.astro
├── Resource.astro
├── Services.astro
├── Tech.astro
├── blog/
│   ├── Footer.astro
│   ├── Footere.astro
│   ├── Nav.astro
│   └── Nave.astro
├── index_page/
│   ├── Footer.astro
│   ├── getstart.astro
│   └── Nav.astro
└── plan/
    └── Header.astro

Widget	Used for
Header.astro	Site header
Features.astro	Feature grid section
Intro.astro	Intro / hero section
Services.astro	Services section
BlogPost.astro	Blog post card
Pagination.astro	Page navigation
Resource.astro	Resource link block
Tech.astro	Tech stack display
Help.astro	Help / support block
blog/Footer.astro	Footer for blog pages
blog/Nav.astro	Nav for blog pages
index_page/Footer.astro	Footer for landing page
index_page/Nav.astro	Nav for landing page
plan/Header.astro	Header for plan / pricing page

When to edit: When you want to change how a section looks or behaves across multiple pages.

---

Which Folder Should I Use?

Here is a quick decision table:

I want to…	Go to
Add a new documentation page	src/content/docs/
Change the sidebar order	astro.config.mjs
Change the site title or logo	astro.config.mjs
Change colors or fonts	src/styles/base.css
Change homepage text	src/data/home.json
Change pricing numbers	src/data/pricing/pricing.json
Change a blog post	src/pages/blog/
Add a new component	src/widget/
Add a favicon	public/favicon.svg
Add a static image	public/
Add an optimized image	src/assets/

---

Common Pitfalls for Beginners

Mistake	Why it breaks	Fix
Editing public/src/assets/ instead of src/assets/	The mirror is not the source of truth	Always edit src/assets/
Renaming files in src/pages/	Changes URLs, breaks links	Use redirects or update all links
Adding .md file without frontmatter	Page fails to render	Add title and description at the top
Editing config.ts without matching frontmatter	Build error	Keep schema and frontmatter in sync
Editing tsconfig.json	Breaks TypeScript	Leave it alone

---

Quick Summary

Root files        → configuration and metadata
public/           → static files served as-is
src/assets/       → images processed by Astro
src/content/docs/ → YOUR DOCUMENTATION (most important)
src/data/         → JSON content for landing, blog, pricing
src/design/       → page layouts
src/pages/        → routes (blog, tags, categories, RSS)
src/styles/       → CSS (edit base.css most often)
src/widget/       → reusable UI components

Now that you understand the layout, you are ready to run the project.

👉 Continue to: Installation