FAQ
The ten things that almost always explain "why did it do that?"
The language switch is missing on a page
Correct behaviour. The switch only renders when the same page exists in the other language. A post without a translation, or a tag that only appears in one language, gets no toggle.
Categories are matched by name, with a small alias table for translations that are
not literal (Setup ↔ 配置, Design ↔ 设计). Add to src/data/taxonomy.ts when you
need another pair.
A category page shows the wrong image, or a letter
The card cover comes from src/data/taxonomy.ts first, then from the newest post in
that category. If neither exists you get the first letter as a placeholder. Add the
cover to the map to pin it:
export const categoryMeta = {
Tech: { cover: '/img/tech.jpg' },
};My title reads “Hello — inspos — inspos”
Base.astro appends the site name to whatever title you pass. Pass the short
title only (Hello), not Hello — inspos.
The build fails but npm run dev works
npm run build runs astro check before building; the dev server does not. The most
common error is an implicit any in a component prop or a generated page:
error ts(7006): Parameter 'x' implicitly has an 'any' type.Annotate it ((x: string) => …) and rebuild. If you would rather ship without the
gate, call npx astro build directly — but then type errors reach production.
A new docs page does not appear in the sidebar
Docs are grouped by their folder: getting-started/, configuration/, content/,
reference/. A page in any other folder is built but never linked, because the
sidebar only knows the sections listed in src/lib/docs.ts. Put the file in an
existing section, or add the section there.
Search does not find a post I just added
The search index is generated by Pagefind at build time (scripts/build.mjs).
Run npm run build again; npm run dev does not write an index.
Images return 404
Content images must live under public/ and be referenced from the site root:
/img/hello.jpg, not ../assets/hello.jpg. Builds copy public/ as-is.
A zh-Hant page shows simplified characters
zh-Hant reuses the posts-zh/ collection and converts the interface strings, not
your prose. If a phrase stays simplified, it is in the content, not the UI — write
the traditional text in the post itself, or add a dictionary entry in
src/lib/trad.ts.
My draft shows up locally but not online
By design. draft: true posts are visible in dev and excluded from the build.
Set draft: false and a date that is not in the future before deploying.
Which file do I edit: site.config.yaml or src/?
site.config.yaml for anything a reader sees as text, links, colours or feature
switches. src/ only when you are changing the theme itself — layouts, components,
styles. If a prop is already config-driven, editing src/ means the next theme update
overwrites your change.
Still stuck
Run npm run seo against dist/ — it reports missing meta tags, duplicate titles,
non-reciprocal hreflang and thin pages, which is usually where a “weird” page starts.