Skip to content
Early bird + Black Friday · 73% off

Get ZeroDirs for $179 $49

Claim $49 deal

Make it yours

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.

  1. 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 chars
    url: 'https://acme.com', // https, no trailing slash
    contactEmail: 'hello@acme.com',
    locale: 'en', // html lang, feed language, date formatting
    kind: 'software', // software | service | business
    },

    business needs address and telephone custom fields on the listing, else it emits Organization.

  2. 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.

  3. 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.' },
    ],

    icon is a lucide icon name; defineSiteConfig() merges it into theme.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

    Listing index: category chips and listing cards

  4. 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' with featuredDays) needs features.payments: true and providers.payment: 'stripe': tiers[1].priceCents: must be 0 when features.payments is false.

  5. Validate.

    Terminal
    pnpm check:config

    A 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> icons
    listings: <n> (the local database); logos optimised from R2 (+1 webp each)
    budget: <n> listings × <n> files + 3000 overhead ≈ <n> / 20000 files (free plan, <n>%) — ok
    headroom: up to ~<n> listings before the 90% limit on the free plan
  6. Replace the demo content.

    Terminal
    pnpm content:reset --yes

    Without --yes it 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 in src/content/blog/ bar the kept fixture:

    reset: deleted the seeded listings from the local database
    reset: deleting <n> seeded logos from the <bucket> bucket (local)
    reset: deleted <n> of <n>
    blog: removed <n> posts, wrote src/content/blog/hello-world.md
    blog: 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.md
    next: pnpm listings:import <file.csv|file.json> --local — or tsx scripts/content.ts use ai-tools --yes to put the demo data back

    Then bring your listings in:

    Terminal
    pnpm listings:import widgets.csv --dry-run # every bad row in one pass; writes nothing
    pnpm listings:import widgets.csv --local

    CSV or JSON, columns on Listings and datasets; an unknown category is a hard error here too. pnpm content:use indie-tools --yes seeds another sample dataset instead and prints the categories and tags blocks to paste into site.config.ts, which it never edits. The real database takes the same commands with --remote once it exists — Go live.

  7. Brand it.

    What Where What to do
    Favicon and header logo public/favicon.svg overwrite it; site.logo: '/favicon.svg' sets header and JSON-LD logo, omit for text-only
    Social-share image public/og-default.png pnpm og:default regenerates it from site.name, site.tagline, site.description
    About page src/pages/about.astro rewrite the demo’s editorial policy
    Handles seo.twitterHandle, site.social twitter:site, footer X and GitHub links, sameAs — all still say zerodirs

    Footer: Terms and Privacy appear once legal.termsUrl and legal.privacyUrl are set; site.builtWith: false removes Built with ZeroDirs.

    The demo footer: link columns, newsletter form, Terms, Privacy and Built with ZeroDirs

  8. Switch things on or off.

    features. Default Demo What it adds Page
    submissions false true Submit link; needs D1 Submissions
    accounts false true email and password or Google sign-in; /dashboard/; bookmarks Submitter accounts
    payments false true Stripe Checkout; two secrets Plans and payments
    newsletter 'off' 'd1' footer form; 'embed' renders newsletter.embedHtml, 'd1' stores in D1 Newsletter
    blog true true /blog/, /blog/rss.xml, Blog nav Blog and feeds
    search true true /search/; index exists only after pnpm build Search
    clicks 'off' 'ping' /out/<id>/; 'ping' beacon, 'redirect' redirect Click tracking
    relatedLinks true true related list on detail pages Programmatic SEO
    pseo true true pages from pseo.templates Programmatic SEO
    honeypot true true hidden field on both forms; filled = dropped silently Submissions

    Ads are not a flag: each ad placement is a boolean in the ads block — Ads and sponsors. Give the house ad in ads.topBanner your own text and url, or enabled: false.

  9. Pick a theme.

    theme: { preset: 'warm' } — presets are default, warm, mono; darkMode is system, light or dark; theme.tokens overrides colours, radii and fonts — Theming.

  10. Set site.url to the real domain, and build.

    Terminal
    pnpm check:config && pnpm build

    site.url is baked into canonicals, the sitemap, both feeds and the absolute og:image URLs. pnpm cf:setup refuses to run while it still says demo.zerodirs.com or example.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, ok
    zero-js: <n> content pages, 0 islands, 0 external scripts — ok
    seo-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]

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
  • 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.
  • budget and zero-js must end in ok; check:config warns above 80% of the plan and exits 1 above 90%. With seo.strictLinks: true an orphan listing fails the build — the build report.
  • An unused tag gets no page; a category always gets one, noindex below seo.noindexBelow listings.
  • pnpm og:default --check exits 1 when the image is stale — put it in CI.

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