Every step is an edit to site.config.ts or one command. Keep the order: the URL scheme before
the content, site.url before the build. The Quickstart and pnpm dev
come first.
-
Name it.
site.config.ts site: {name: 'Acme Directory',tagline: 'The best widgets, ranked',description: 'A curated directory of widgets, compared on price and features.', // max 160 charsurl: 'https://acme.com', // https, no trailing slashcontactEmail: 'hello@acme.com',locale: 'en', // html lang, feed language, date formattingkind: 'software', // software | service | business},businessneedsaddressandtelephonecustom fields on the listing, else it emits Organization. -
Give it its URLs and its noun.
site.config.ts routes: {listingBase: 'widgets', // /widgets/<slug>/ and /widgets/page/2/categoryBase: 'categories', // /categories/<slug>/tagBase: 'tags', // /tags/<slug>/listingNoun: { singular: 'widget', plural: 'widgets' },},The three bases must differ, and none may be reserved (
blog,search,admin):site.config.ts › routes.listingBase: "blog" is a reserved path segment. -
Categories and tags.
site.config.ts categories: [{ slug: 'blue', name: 'Blue', description: 'Widgets that are blue.', icon: 'palette', order: 1 },{ slug: 'fast', name: 'Fast', description: 'Widgets that are quick.', icon: 'zap', order: 2 },],tags: [{ slug: 'open-source', name: 'Open source', description: 'Source available.' },],iconis a lucide icon name;defineSiteConfig()merges it intotheme.icons, so never add one there yourself;src/icons/holds your own SVGs.An unknown tag is dropped; an unknown category stops the build:
listings › my-widget: unknown tag(s) "beta" filtered (slug "my-widget"; not in site.config.ts tags)listings › my-widget: unknown category "green" (slug "my-widget"); categories in site.config.ts: blue, fast
-
Tiers.
site.config.ts tiers: [{ id: 'free', name: 'Free', description: 'Reviewed in order, listed for free.', kind: 'queue', priceCents: 0, currency: 'usd', enabled: true },],One enabled tier is required (
at least one tier is required). A priced tier (kind: 'express', or'featured'withfeaturedDays) needsfeatures.payments: trueandproviders.payment: 'stripe':tiers[1].priceCents: must be 0 when features.payments is false. -
Validate.
Terminal pnpm check:configA failure names every field path at once:
site.config.ts is invalid (2 issues):site.config.ts › site.description: must be at most 160 characters (home meta description)site.config.ts › routes.tagBase: must differ from routes.categoryBase ("categories")Success:
site.config.ts OK — Acme Directory (https://acme.com); <n> categories, <n> tags, <n> tiers (<n> enabled), <n> pSEO templates, preset "default", <n> iconslistings: <n> (the local database); logos optimised from R2 (+1 webp each)budget: <n> listings × <n> files + 3000 overhead ≈ <n> / 20000 files (free plan, <n>%) — okheadroom: up to ~<n> listings before the 90% limit on the free plan -
Replace the demo content.
Terminal pnpm content:reset --yesWithout
--yesit only prints what it would delete. With it, it deletes the seeded listings from the local database and their logos from the local bucket (one object at a time — a few minutes for the demo), and the demo posts insrc/content/blog/bar the kept fixture:reset: deleted the seeded listings from the local databasereset: deleting <n> seeded logos from the <bucket> bucket (local)reset: deleted <n> of <n>blog: removed <n> posts, wrote src/content/blog/hello-world.mdblog: kept src/content/blog/unpublished-draft.md (starter fixture, draft: true — delete it if you do not want it)reset: kept src/content/pseo/example-override.mdnext: pnpm listings:import <file.csv|file.json> --local — or tsx scripts/content.ts use ai-tools --yes to put the demo data backThen bring your listings in:
Terminal pnpm listings:import widgets.csv --dry-run # every bad row in one pass; writes nothingpnpm listings:import widgets.csv --localCSV or JSON, columns on Listings and datasets; an unknown category is a hard error here too.
pnpm content:use indie-tools --yesseeds another sample dataset instead and prints thecategoriesandtagsblocks to paste intosite.config.ts, which it never edits. The real database takes the same commands with--remoteonce it exists — Go live. -
Brand it.
What Where What to do Favicon and header logo public/favicon.svgoverwrite it; site.logo: '/favicon.svg'sets header and JSON-LD logo, omit for text-onlySocial-share image public/og-default.pngpnpm og:defaultregenerates it fromsite.name,site.tagline,site.descriptionAbout page src/pages/about.astrorewrite the demo’s editorial policy Handles seo.twitterHandle,site.socialtwitter:site, footer X and GitHub links,sameAs— all still sayzerodirsFooter: Terms and Privacy appear once
legal.termsUrlandlegal.privacyUrlare set;site.builtWith: falseremoves Built with ZeroDirs.
-
Switch things on or off.
features.Default Demo What it adds Page submissionsfalsetrueSubmit link; needs D1 Submissions accountsfalsetrueemail and password or Google sign-in; /dashboard/; bookmarksSubmitter accounts paymentsfalsetrueStripe Checkout; two secrets Plans and payments newsletter'off''d1'footer form; 'embed'rendersnewsletter.embedHtml,'d1'stores in D1Newsletter blogtruetrue/blog/,/blog/rss.xml, Blog navBlog and feeds searchtruetrue/search/; index exists only afterpnpm buildSearch clicks'off''ping'/out/<id>/;'ping'beacon,'redirect'redirectClick tracking relatedLinkstruetruerelated list on detail pages Programmatic SEO pseotruetruepages from pseo.templatesProgrammatic SEO honeypottruetruehidden field on both forms; filled = dropped silently Submissions Ads are not a flag: each ad placement is a boolean in the
adsblock — Ads and sponsors. Give the house ad inads.topBanneryour own text andurl, orenabled: false. -
Pick a theme.
theme: { preset: 'warm' }— presets aredefault,warm,mono;darkModeissystem,lightordark;theme.tokensoverrides colours, radii and fonts — Theming. -
Set
site.urlto the real domain, and build.Terminal pnpm check:config && pnpm buildsite.urlis baked into canonicals, the sitemap, both feeds and the absoluteog:imageURLs.pnpm cf:setuprefuses to run while it still saysdemo.zerodirs.comorexample.com. Read these lines:routes: <n> directory pages (<n> listings, <n> index pages, <n> category pages, <n> tag pages, <n> pseo, <n> noindex) → node_modules/.cache/zerodirs/routes.json (<n> routes incl. static pages)pseo: generated <n> (dropped by minItems <n>, truncated <n>)sitemap: <n> urls in <n> chunks (listings=<n>, taxonomy=<n>, pseo=<n>, blog=<n>, pages=<n>); dropped <n> (search/noindex/disallow/file); pseo slugs: <n>budget: <n> files / 20000 (<n>%) — free plan, okzero-js: <n> content pages, 0 islands, 0 external scripts — okseo-report: scanned <n> pages; <n> listings; <n> noindex; pseo <n> pages (best-category-for-tag=<n>, name-alternatives=<n>)seo-report: inbound links per listing: min <n>; orphans (fewer than 2 inbound): 0 [strictLinks=on]
Verify
Section titled “Verify”pnpm preview serves the build. Open these on the URL it prints:
| Open | You should see | |
|---|---|---|
| The home page | / |
your name, tagline and category chips |
| A category | /categories/<slug>/ |
its listings and its icon |
| A listing | /widgets/<slug>/ |
an initial-letter tile until it has a logo |
| Robots | /robots.txt |
User-agent: *, Disallow: lines, Sitemap: https://acme.com/sitemap-index.xml |
| The sitemap | /sitemap-index.xml |
sitemap-listings-0.xml, sitemap-taxonomy-0.xml, sitemap-blog-0.xml, sitemap-pages-0.xml, plus sitemap-pseo-0.xml once a generated page exists — each on your site.url |
Worth knowing
Section titled “Worth knowing”- Decide the route bases before you import: changing one later rewrites every canonical, sitemap entry and OG image URL, and the old pages stop existing.
- The demo listings and blog posts describe real products — not yours to republish; the
dataset’s
logos/holds generic initial-letter tiles. - A flag without the thing it needs buys a route that answers 503.
/admin/lists what is missing:Missing secret STRIPE_SECRET_KEY — run: wrangler secret put STRIPE_SECRET_KEY (local: add to .env). Paid tiers cannot complete a checkout. budgetandzero-jsmust end inok;check:configwarns above 80% of the plan and exits 1 above 90%. Withseo.strictLinks: truean orphan listing fails the build — the build report.- An unused tag gets no page; a category always gets one,
noindexbelowseo.noindexBelowlistings. pnpm og:default --checkexits 1 when the image is stale — put it in CI.
Configuration
Section titled “Configuration”site, routes, categories, tags, tiers, features, ads, legal, theme, seo,
budget — Configuration reference, Cost and limits.
- site.config.ts
Directorypublic/
- favicon.svg
- og-default.png
Directoryseed/datasets/ the sample datasets
- …
Directorysrc/
Directorycontent/
Directoryblog/
- …
Directoryicons/
- …
Directorypages/
- about.astro