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:

ts
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:

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