Astro from Zero: A Complete Beginner's Guide

Version: 15 September 2026

If you are new to Astro and see files like:

index.astro
[...slug].astro
src/pages/
src/content/
src/components/
src/layouts/

it is normal to feel confused at first.

The core idea is not complicated. Start by understanding:

How Astro turns a folder of files into pages in the browser.

Once that is clear, index.astro, [...slug].astro, Markdown, layouts, and components become much easier to follow.

1. What Astro is in one sentence

Astro is a tool that turns your content, templates, and code into HTML pages.

For example:

src/pages/about.astro  →  /about

The browser receives mostly HTML, CSS, and only the JavaScript that is actually needed.

Your source files
       │
       ▼
     Astro
       │
       ▼
HTML / CSS / JavaScript
       │
       ▼
   Browser

Astro is not the browser. It is the build step that prepares the site.

2. The main parts of an Astro project

my-site/
├── public/
├── src/
│   ├── pages/
│   ├── components/
│   ├── layouts/
│   ├── content/
│   └── styles/
├── astro.config.mjs
├── package.json
└── tsconfig.json

Location	Role
`src/pages/`	Defines URLs
`src/content/`	Article content
`src/components/`	Reusable UI pieces
`src/layouts/`	Shared page shells
`src/styles/`	CSS
`public/`	Static files (images, favicon)
`astro.config.mjs`	Site-wide Astro settings

The most important folder to understand first is src/pages/.

3. `src/pages`: how URLs are created

Astro uses file-based routing:

The folder and file structure under src/pages usually determines the URL.

src/pages/index.astro   → /
src/pages/about.astro   → /about
src/pages/en/index.astro → /en/
src/pages/en/home-lab/firewall.astro → /en/home-lab/firewall

Unlike Angular, you often do not need a separate routes config file. The file location is the route.

4. Why `index.astro` matters

index.astro is the homepage of that folder:

src/pages/index.astro        → /
src/pages/en/index.astro     → /en/
src/pages/en/home-lab/index.astro → /en/home-lab/

5. What is inside a `.astro` file?

---
const name = "Harry";
---

<h1>Hello {name}</h1>

The top --- block: imports, data, build-time logic
Below: HTML template

6. `components`: reusable Lego blocks

Instead of copying the same header into every page, create Header.astro once and import it everywhere.

Change the header once → every page updates.

7. `layouts`: the shared page frame

A layout wraps the common structure:

Header
Main content
Footer

Example: a ContentLayout.astro can wrap every article page in a custom Astro site.

8. What is `<slot />`?

<slot /> is the insertion point for content passed into a layout.

Think of it as: “put the page body here.”

9. Why Markdown suits blogs

Markdown focuses on content, not layout. Perfect for blogs, tutorials, and technical notes.

10. `src/content` vs `src/pages`

	`src/content`	`src/pages`
Role	Article data	Routing and page assembly
Example	`home-lab/firewall.md`	`en/[...slug].astro`

src/content does not automatically create URLs by itself.

11. The most important rule

Content is the article. Pages are the URL.

Markdown Content → Astro Route → Layout → HTML → Browser

12. What is a dynamic route?

Instead of creating one .astro file per article, use one template for many URLs.

13. What is `[slug].astro`?

Handles one variable segment:

/products/apple
/products/orange

14. What is `[...slug].astro`?

Handles multiple path segments:

/en/home-lab
/en/home-lab/firewall
/en/home-lab/network/vlan

This is a common pattern in plain Astro sites: one catch-all route file can serve many nested article URLs.

15. Why does `getStaticPaths()` exist?

For static sites, Astro must know every URL at build time.

getStaticPaths() returns the list of slugs to pre-render.

16. How a Markdown file becomes a URL

In a plain Astro site:

firewall.md
    │ read frontmatter: slug = home-lab/firewall
    ▼
[...slug].astro
    │ apply ContentLayout
    ▼
/en/home-lab/firewall

Markdown does not create its own URL. The route reads it and builds the page.

17. Plain Astro vs Astro + Starlight

Many Astro tutorials teach the plain Astro approach:

Markdown
    ↓
Content Collection
    ↓
[...slug].astro
    ↓
getStaticPaths()
    ↓
Layout
    ↓
Page

That works well when you want full control over routing, layouts, sidebars, and language switching.

Astro + Starlight is a documentation-focused layer on top of Astro. You write Markdown in src/content/docs/ and Starlight provides the docs shell:

Markdown
    ↓
src/content/docs/
    ↓
Starlight
    ↓
Sidebar + TOC + Search + Page

	Plain Astro	Astro + Starlight
Routing	You build `[...slug].astro` and `getStaticPaths()`	File paths under `src/content/docs/` become URLs
Sidebar	Custom component or config	Built-in sidebar from folders and frontmatter
On this page	Custom or manual	Automatic from headings
Search	You add it (e.g. Pagefind)	Built-in via Pagefind
i18n	Custom pairing logic	Built-in locale folders (`en/`, `zh/`)

Both are valid. Plain Astro teaches how routing works. Starlight is ideal when you want a docs-style site without rebuilding navigation, TOC, and search yourself.

18. Applied to harrylo.com today

The current harrylo.com technical site uses Astro + Starlight, not custom [...slug].astro routing.

/en/                          → English home
/zh/                          → Chinese home
/en/astro/astro-from-zero/    → This guide (English)
/zh/astro/astro-from-zero/    → This guide (Chinese)

Content lives here:

src/content/docs/
├── en/
│   ├── index.md
│   └── astro/
│       └── astro-from-zero.md
└── zh/
    ├── index.md
    └── astro/
        └── astro-from-zero.md

Add a new page by adding matching Markdown files under en/ and zh/ with the same relative path. No new .astro route file is required.

An older prototype of this site used plain Astro with src/pages/en/[...slug].astro and custom layouts. That approach is still useful to understand, but it is not how this Starlight site is built.

19. How English and Chinese pages are paired

In Starlight, each language has its own folder with matching relative paths:

src/content/docs/en/astro/astro-from-zero.md
src/content/docs/zh/astro/astro-from-zero.md

The language switch keeps the same path and swaps the locale prefix:

/en/astro/astro-from-zero/  ↔  /zh/astro/astro-from-zero/

You do not need custom id or slug frontmatter fields for pairing—folder structure does the work.

20. How to add a new article

Create English Markdown under src/content/docs/en/...
Create Chinese Markdown under src/content/docs/zh/... with the same relative path
Add Starlight frontmatter (title, description, optional sidebar label/order)
Run npm run dev or npm run build

Starlight picks up new files and updates the sidebar automatically.

21. Where do images go?

public/images/astro/example.webp

In Markdown:

![Alt text](/images/astro/example.webp)

22. What happens during `npm run build`

Read config → Read content → Generate routes → Render → Output to dist/

src/ is for development. dist/ is what gets deployed.

Search indexing (Pagefind) also runs during the production build.

23. Astro vs Angular

	Angular	Astro
Best for	Applications, dashboards, SPAs	Content sites, blogs, docs
Default model	Client-side app	Build-time HTML

Astro sends less JavaScript to the browser by default.

24. Common beginner mistakes

Assuming Markdown in src/content always gets a URL automatically — something must map content to routes (your own routes in plain Astro, or Starlight for docs)
Creating one .astro file per article in plain Astro — [...slug].astro is often better
Confusing [...slug].astro with a single article — it is a template
Confusing index.astro with [...slug].astro — index is the folder homepage
Mixing up plain Astro patterns with Starlight — in Starlight, docs URLs come from src/content/docs/ paths, not custom slug frontmatter

25. The big picture

Plain Astro:

Markdown Content (src/content/)
       │
       ▼
Dynamic Route ([...slug].astro)
       │
       ▼
Layout (ContentLayout)
       │
       ▼
HTML → Browser

This site (Starlight):

Markdown (src/content/docs/)
       │
       ▼
Starlight (routing + docs layout)
       │
       ▼
HTML → Browser

26. Ten rules to remember

Astro builds source files into a website.
src/pages defines URLs in plain Astro; Starlight docs use src/content/docs/.
index.astro is a folder homepage.
.astro files combine logic and HTML.
Components are reusable UI blocks.
Layouts are shared page frames (or Starlight’s built-in docs layout).
<slot /> is where page content goes in custom layouts.
src/content or src/content/docs holds article data.
[...slug].astro handles many article URLs with one template in plain Astro.
Content is the article. Routes (or Starlight paths) are the URL.

27. What to learn next

Trace this article on the live site:

src/content/docs/en/astro/astro-from-zero.md
       │
       ▼
Starlight docs routing
       │
       ▼
Sidebar + On this page + article body
       │
       ▼
/en/astro/astro-from-zero/

When you can follow that path once, Astro and Starlight stop feeling abstract.

Quick quiz

Q1. src/pages/zh/index.astro maps to which URL? → /zh/

Q2. Is [...slug].astro one article or a template? → A template

Q3. In Starlight, where does this guide’s Markdown file live? → src/content/docs/en/astro/astro-from-zero.md

Q4. What URL does that file produce? → /en/astro/astro-from-zero/

Q5. Which rule matters most? → Content is the article. Routes are the URL.

Conclusion

Astro looks complex because many concepts appear at once. Follow one thread:

Where is the article?
What creates the URL?
What controls the layout?
How does Astro build?

Put each piece in the right place and the system becomes clear:

Content + Routing + Layout = Website

For harrylo.com today, Starlight handles most of the docs shell so you can focus on writing Markdown.