ZeroOne — English

Dockerize an Astro Static Site: Build dist, Serve It with Caddy

Sat, 01 Aug 2026 00:00:00 GMT

An Astro static site does not need Node.js at runtime. Its production artifact is the generated dist/ directory, so a container can build the site with Node in one stage and serve only that output in the final stage. That boundary keeps build dependencies out of the web-server image and makes a failed deployment easier to diagnose.

This guide targets the primary question behind “Dockerize an Astro static site”: how to build dist reproducibly, serve it from a small web-server image, and verify that the container is returning the generated site.

Use a two-stage Dockerfile

Astro's deployment guide identifies astro build (or the package-script equivalent) as the build command and dist as the publish directory. Docker multi-stage builds let the final image copy just that artifact instead of carrying the package manager, source files, and node_modules into production.

For a pnpm project, add this Dockerfile at the repository root:

FROM node:22-slim AS build
WORKDIR /app

# Copy dependency metadata first so this layer can be cached.
COPY package.json pnpm-lock.yaml ./
RUN npm install --global pnpm@9.14.4
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

FROM caddy:2-alpine
COPY --from=build /app/dist /usr/share/caddy

EXPOSE 80

The order is deliberate. A content or component change does not invalidate the dependency-install layer as long as package.json and pnpm-lock.yaml remain unchanged. The final caddy stage receives only /app/dist; it has no project source or Node package tree to execute.

Use the Node and pnpm versions your repository supports rather than copying these numbers blindly. In this site, the package manifest currently declares pnpm 9.14.4 and Astro 5.12.8, so the build-stage command should match that lockfile contract.

Keep the Docker build context small

A .dockerignore controls what Docker sends to the builder. At minimum, exclude local dependencies and output that the container will regenerate:

node_modules
.astro
dist
.git

Add project-specific generated folders as needed. Do not add a blanket .env* rule without first checking whether your static build requires non-secret, build-time public values. Secrets should not be baked into a static site image: values exposed to client-side JavaScript become public in the generated output.

Docker's documentation recommends multi-stage builds to separate build-time and runtime dependencies, and .dockerignore keeps unnecessary local files out of the build context. Those are separate safeguards: the first keeps the final image focused, while the second reduces what is available during the build.

Build and verify the container locally

From the repository root, build the final stage and map its HTTP port:

docker build -t astro-static-site .
docker run --rm --publish 8080:80 astro-static-site

In another terminal, confirm that the web server is returning the generated HTML:

curl --head http://localhost:8080/

Then open http://localhost:8080/ and test one non-homepage route. If the homepage works but a page with a trailing slash returns 404, inspect the corresponding path in dist/ before changing the web-server configuration. With Astro's usual static output, a route such as /about/ should result in a matching generated directory and index.html.

For a production check, run the same build command outside Docker first. This is especially useful for content collections, image transforms, and search-index generation because it tells you whether the failure belongs to Astro or to the container build.

pnpm build
test -f dist/index.html

If your site has language-specific output, test one of those paths too. Build an Astro Multilingual Blog Without Migrating Existing URLs includes concrete output checks for /en/ routes.

Do not use this pattern for on-demand routes

This Dockerfile is for a static Astro deployment. It is not a substitute for an adapter when the site uses on-demand rendering, server endpoints, sessions, or other server-side behavior. Astro's deployment documentation calls for the appropriate adapter in that case; the runtime image must start the adapter's server instead of serving a fixed dist/ directory.

That distinction also narrows debugging:

Symptom	Check first
`pnpm build` fails	Dependencies, content schema, or Astro configuration
Docker build fails at `pnpm install`	Lockfile, package-manager version, or network access to the registry
Container starts but returns 404	The copied `dist/` path and the server's document root
A dynamic endpoint is missing	Whether the project needs an Astro adapter rather than static serving

The practical rule is simple: build the static artifact once, copy that artifact into the final image, and verify the generated paths before treating the issue as a hosting problem.

FAQ

Q: Do I need Node.js in the final Docker image for a static Astro site?

A: No. A static Astro build produces files in dist/, which a web server can serve directly. Keep Node.js in the build stage unless your project uses on-demand rendering through an adapter.

Q: Why copy package files before the rest of the Astro project?

A: Docker caches layers. Copying package.json and the lockfile before application files allows the dependency-install layer to be reused when only content or source files change.

Q: Can I use Nginx instead of Caddy?

A: Yes. The relevant boundary is the same: copy the completed dist/ directory into a static web-server image and ensure that the image's document root matches the copied location. Use the server image and configuration your platform supports.

References:

Astro: Deploy your Astro site

Docker: Multi-stage builds

Docker: Building best practices

Caddy Docker image

Build an Astro Multilingual Blog Without Migrating Existing URLs

Fri, 31 Jul 2026 00:00:00 GMT

Adding a second language to an established Astro blog is not mainly a translation problem. The risky part is changing URLs that search engines, readers, and external links already know. This guide shows how to add an English section under /en/ while every existing default-language URL stays where it is.

The central rule is simple: treat locale as content data and URL policy, not as a string inferred late in rendering.

Start with the URL contract

Suppose an existing Traditional Chinese article is already published at:

/posts/astro-sitemap/

Moving it to /zh-tw/posts/astro-sitemap/ would create a migration project: redirects, canonical changes, sitemap churn, and a period in which crawlers reconcile old and new URLs. None of that is necessary just to publish English content.

Astro supports an unprefixed default locale and prefixed secondary locales. The relevant configuration is:

// astro.config.mjs
export default defineConfig({
  site: "https://example.com/",
  trailingSlash: "always",
  i18n: {
    defaultLocale: "zh-TW",
    locales: ["zh-TW", "en"],
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: false,
    },
  },
});

With this policy, the observable route contract becomes:

Content	Repository entry slug	Public URL
Existing default-language post	`astro-sitemap`	`/posts/astro-sitemap/`
New English post	`en/pagefind-multilingual-search-astro`	`/en/posts/pagefind-multilingual-search-astro/`

The en/ segment in the content collection keeps source files organized. It must not leak into the public slug, or the site will produce /en/posts/en/....

Put locale rules in one module

Route files, post cards, related posts, RSS, and structured data all need the same mapping. A small locale module prevents each caller from inventing its own version.

export const DEFAULT_LOCALE = "zh-TW" as const;
export const SUPPORTED_LOCALES = [DEFAULT_LOCALE, "en"] as const;
export type Locale = (typeof SUPPORTED_LOCALES)[number];

export function normalizeLocale(value?: string | null): Locale {
  if (!value?.trim()) return DEFAULT_LOCALE;
  if (value === "en") return "en";
  if (value === "zh-TW" || value === "zh_TW") return "zh-TW";
  throw new Error(`Unsupported locale: ${value}`);
}

export function getPublicPostSlug(slug: string, locale: Locale): string {
  if (locale === "en") {
    if (!slug.startsWith("en/")) {
      throw new Error(`English post must live below en/: ${slug}`);
    }
    return slug.slice(3);
  }

  if (slug.startsWith("en/")) {
    throw new Error(`Default-language post cannot use en/: ${slug}`);
  }
  return slug;
}

export function getPostPath(slug: string, locale: Locale): string {
  const prefix = locale === "en" ? "/en" : "";
  return `${prefix}/posts/${getPublicPostSlug(slug, locale)}/`;
}

Throwing on unknown locales is intentional. A silent fallback can publish a third language into the wrong index or create a canonical URL that does not match the route.

Filter content before sorting it

A multilingual homepage is only one visible part of the system. Previous/next navigation, category counts, tag counts, and related-post scoring can all cross language boundaries if filtering happens after those values are calculated.

Filter the collection first:

async function getSortedPosts(locale: Locale = DEFAULT_LOCALE) {
  const posts = await getCollection("posts", ({ data }) => !data.draft);

  const localizedPosts = posts.filter(
    (post) => normalizeLocale(post.data.lang) === locale,
  );

  return localizedPosts.sort(
    (a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
  );
}

Only after this step should you assign previous and next posts or calculate related content. Keep the locale argument defaulted to the original language so unchanged callers preserve their behavior.

Generate explicit English routes

Astro file-based routes make the public boundary clear. Keep the original list route at src/pages/[...page].astro, then add an English list route at src/pages/en/[...page].astro.

---
import type { GetStaticPaths } from "astro";
import { getSortedPosts } from "../../utils/content-utils";

export const getStaticPaths = (async ({ paginate }) => {
  const posts = await getSortedPosts("en");
  return paginate(posts, { pageSize: 10 });
}) satisfies GetStaticPaths;
---

The English article route performs the same locale-specific query and removes the repository prefix when producing route parameters:

return englishPosts.map((entry) => ({
  params: { slug: getPublicPostSlug(entry.slug, "en") },
  props: { entry },
}));

Pass lang="en" from this route into the shared layout and UI components. Do not ask components to inspect window.location or browser preferences. Explicit props also work during static rendering and make missing translations easier to detect.

Keep feeds and metadata locale-specific

Create /en/rss.xml from getSortedPosts("en"); keep /rss.xml on the default query. Every feed item link should use the same getPostPath mapping as article cards and Schema.org data.

Each page also needs an absolute self-canonical. An English article should resolve to:

<link rel="canonical" href="https://example.com/en/posts/example-slug/">

Do not add hreflang merely because two pages discuss Astro. It describes localized alternatives of the same page. Independent English topics should remain self-canonical without an alternate pair. The decision rules are covered in Hreflang for Independent Multilingual Content.

Verify the generated site, not only TypeScript

Static-site bugs often appear in output paths or HTML rather than in type checking. After pnpm check, run the production build and inspect the artifacts:

pnpm build

test -f dist/index.html
test -f dist/en/index.html
test -f dist/rss.xml
test -f dist/en/rss.xml

rg '/en/posts/en/' dist
rg '<html lang="en"' dist/en
rg 'rel="canonical"' dist/en/posts

The first rg command should return no matches. Also inspect the sitemap and confirm that old default-language paths are unchanged.

Pagefind can use the same <html lang> boundary to separate search indexes. Pagefind Multilingual Search in Astro shows how to validate that part of the build.

The practical takeaway is to preserve public URLs first, then make locale explicit at every content and URL boundary. Once routes, queries, metadata, and feeds share that contract, English posts can be independent without destabilizing the existing site.

FAQ

Q: Can I add English pages without moving existing Astro URLs?

A: Yes. Keep the established default-language routes unprefixed and add English routes under /en/. The important part is to make locale explicit in content queries, URL helpers, metadata, feeds, and related-content calculations so the two sections remain separate.

Q: Why does an English Astro post sometimes become `/en/posts/en/...`?

A: This happens when the content entry slug already contains the repository-only en/ prefix and the route builder adds another English prefix without removing it. Convert the entry slug to a public slug before composing the route, then verify that the production output contains no /en/posts/en/ paths.

Q: Do all English and Traditional Chinese posts need hreflang links?

A: No. Add hreflang only when the URLs are equivalent localized versions of the same article. Independent articles should remain self-canonical even when they share tags or discuss the same framework.

References:

Astro internationalization routing

Astro i18n API reference

Hreflang for Independent Multilingual Content: When Pages Are Not Translations

Fri, 31 Jul 2026 00:00:00 GMT

An English article and a Traditional Chinese article can cover the same technology without being localized versions of the same page. Connecting them with hreflang anyway sends a stronger equivalence signal than the content supports.

For a multilingual technical blog with independently planned articles, the safe default is a self-canonical page with no hreflang. Add reciprocal alternates only when the two URLs genuinely represent the same article for different language audiences.

Canonical and hreflang answer different questions

A canonical link identifies the preferred URL for the current page:

<link
  rel="canonical"
  href="https://example.com/en/posts/pagefind-multilingual-search-astro/"
>

An hreflang alternate identifies another localized version of the same content:

<link
  rel="alternate"
  hreflang="zh-Hant"
  href="https://example.com/posts/pagefind-multilingual-search-astro/"
>
<link
  rel="alternate"
  hreflang="en"
  href="https://example.com/en/posts/pagefind-multilingual-search-astro/"
>

Google Search Central describes hreflang as a way to identify localized variations of a page. It also expects every version to list the other versions, including itself. A one-way link is not a complete relationship.

The canonical on each localized page should normally point to that page itself. Do not canonicalize an English translation to the Traditional Chinese original; doing so conflicts with the intent to index both language versions.

Decide whether two articles are equivalents

Use content intent, not shared tags, to make the decision.

Relationship	Self-canonical	Reciprocal hreflang
Direct translation with the same examples and purpose	Yes	Yes
Localized adaptation with the same reader task and equivalent main content	Yes	Yes
Two tutorials about Astro with different problems	Yes	No
English article inspired by a shorter Chinese note	Yes	No
Only one language version exists	Yes	No

For example, an English guide about preserving legacy URLs and a Chinese post about generating an Astro sitemap both belong to an Astro/SEO cluster. They are useful internal links, but they are not language alternatives. Each should remain self-canonical without an hreflang connection.

Represent translation as optional content data

Folder names and matching slugs are weak evidence of equivalence. Use an explicit optional key in the content schema:

const postsCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    lang: z.enum(["en", "zh-TW", "zh_TW", ""]).optional(),
    translationKey: z.string().trim().min(1).optional(),
  }),
});

Independent articles omit translationKey. A verified pair receives the same value:

# Traditional Chinese article
lang: zh-TW
translationKey: astro-i18n-routing

# English article
lang: en
translationKey: astro-i18n-routing

This model makes the editorial decision visible and reviewable. It also allows translated titles and different slugs without relying on filename equality.

Build alternates only for complete pairs

Group posts by non-empty translationKey, then require one unambiguous entry for each supported locale.

type Locale = "zh-TW" | "en";

for (const post of posts) {
  const key = post.data.translationKey?.trim();
  if (!key) continue;

  const locale = normalizeLocale(post.data.lang);
  const group = groups.get(key) ?? new Map<Locale, Post>();

  if (group.has(locale)) {
    throw new Error(`Duplicate translation key: ${key} (${locale})`);
  }

  group.set(locale, post);
  groups.set(key, group);
}

When a group has both zh-TW and en, create two alternates and pass them into the page layout. When only one side exists, emit nothing. This avoids publishing a relation to a missing URL.

The resulting Astro layout can render absolute URLs:

{alternates.map((alternate) => (
  <link
    rel="alternate"
    hreflang={alternate.hreflang}
    href={new URL(alternate.path, Astro.site).href}
  />
))}

Fail the build when the same locale uses one translation key twice. Choosing the first match would make the output depend on collection order and could connect the wrong article.

Keep independent English articles unpaired

For an English-first experiment, it is acceptable for every initial article to have no equivalent Chinese page. Give each English URL:

an absolute self-canonical containing /en/posts/;
html lang="en";
BlogPosting.inLanguage set to en;
its own English title, description, and body;
no article-level hreflang until an equivalent page exists.

These technical boundaries work alongside the URL and query design in Build an Astro Multilingual Blog Without Migrating Existing URLs. If the site uses Pagefind, the same root language value can also keep multilingual search results separated.

Verify the generated HTML

Check output files after the production build. Source components cannot prove which conditional tags were rendered.

pnpm build

rg 'rel="canonical"' dist/en/posts
rg 'hreflang=' dist/en/posts
rg '"inLanguage":"en"' dist/en/posts
rg '/en/posts/en/' dist

For a pilot containing only independent English articles, the hreflang search should return no matches. The double-prefix search should also be empty.

If you later add a translation pair, inspect both generated pages and verify that:

both pages remain self-canonical;
both list the English and Traditional Chinese alternates;
alternate URLs are absolute and return successful pages;
no third page shares the key in either locale.

The editorial test comes before the markup test: if two articles do not solve the same reader problem with equivalent main content, do not pair them. A shared topic is an internal-link relationship, not automatically a language-alternate relationship.

FAQ

Q: Does every page on a multilingual site need hreflang?

A: No. A page needs hreflang only when another URL is an equivalent localized version for a different language or region. A multilingual site can contain many independent self-canonical pages with no alternate relationship.

Q: Should an English translation canonicalize to the original article?

A: Normally, no. If both localized pages are intended to be indexed, each should use a self-canonical URL and list the reciprocal language alternates. Canonicalizing the English page to the original sends a conflicting consolidation signal.

Q: Should I publish hreflang when only one side of a translation pair exists?

A: Wait until both localized URLs exist and can reference each other. An incomplete one-way relationship does not represent a complete alternate set, so the safer output is no article-level hreflang until the pair is ready.

References:

Google Search Central: Tell Google about localized versions of your page

Pagefind Multilingual Search in Astro: Keep Language Results Separate

Fri, 31 Jul 2026 00:00:00 GMT

A single search box can quietly break the experience of a multilingual blog. An English query may return Traditional Chinese articles, category counts may imply content that is not visible, and a translated placeholder can hide the fact that the underlying index is still mixed.

Pagefind has a simpler boundary available: the lang attribute on each generated HTML document. In an Astro static build, that lets one Pagefind build produce language-specific indexes without running a second search service.

How Pagefind chooses a language index

Pagefind's multilingual documentation describes two matching steps:

During indexing, Pagefind reads the <html lang> value and indexes each detected language independently.
In the browser, Pagefind reads the current page's language and loads the matching index.

That means these pages belong to different search indexes:

<!-- Existing Traditional Chinese page -->
<html lang="zh-TW">

<!-- English section -->
<html lang="en">

You do not need to model language as a custom Pagefind filter for this behavior. You also should not pass --force-language, because that option deliberately opts out of multilingual indexing and creates one language index for the build.

Make Astro render the canonical locale

The language boundary should come from the route's content query, not from browser detection. Define the supported values once:

export const SUPPORTED_LOCALES = ["zh-TW", "en"] as const;
export type Locale = (typeof SUPPORTED_LOCALES)[number];

Then pass the route locale into the root layout:

---
interface Props {
  lang?: "zh-TW" | "en";
}

const { lang = "zh-TW" } = Astro.props;
---

<html lang={lang}>
  <slot />
</html>

The default-language route can keep its existing URL and default prop. The /en/ list and /en/posts/.../ routes must pass lang="en" explicitly.

This approach matters for static generation. There is no browser request language when Astro writes files into dist/, so client-side locale detection cannot determine which Pagefind index a document should enter.

Keep content discovery separated too

Pagefind only controls search. It does not prevent a mixed homepage or cross-language related posts. Before rendering either locale, filter the content collection by the same canonical locale used by the layout.

const englishPosts = allPosts.filter(
  (post) => normalizeLocale(post.data.lang) === "en",
);

Apply that filter before sorting, pagination, previous/next assignment, tag aggregation, and related-post scoring. This gives the search index and visible navigation the same language boundary.

For a complete route and content mapping, see Build an Astro Multilingual Blog Without Migrating Existing URLs.

Localize the search interface with a prop

Pagefind can select an index from the document language, but your own Svelte or Astro search controls still need localized labels. Pass the locale into the search island instead of deriving it from the URL:

<script lang="ts">
  let { lang = "zh-TW" }: { lang?: "zh-TW" | "en" } = $props();

  const copy = lang === "en"
    ? {
        placeholder: "Search articles",
        empty: "No matching articles",
      }
    : {
        placeholder: translatedSearchPlaceholder,
        empty: translatedEmptyState,
      };
</script>

<input aria-label={copy.placeholder} placeholder={copy.placeholder} />

When the island initializes Pagefind on an English document, the client library sees lang="en" on the root element. If a single-page navigation system replaces the document content, verify that it also updates the root language or reinitializes Pagefind when the language changes. Pagefind's API documentation notes that dynamically changing page language requires reinitialization.

Validate the production indexes

Development-mode mock search results do not prove that the production index is separated. Run the full build, then inspect Pagefind's output.

pnpm build

find dist/pagefind -maxdepth 2 -type f | sort
rg 'lang="en"' dist/en/index.html
rg 'lang="zh-TW"' dist/index.html

Pagefind's build log should report both detected languages. The generated index filenames include language-specific metadata; exact hashed names can change between builds, so assertions should inspect content or use Pagefind's API rather than hard-code a hash.

For a browser-level check, open /en/, search for a distinctive English phrase from an English article, and confirm that the returned URLs begin with /en/posts/. Then open / and search for a distinctive Traditional Chinese phrase. The result sets should remain in their own locale.

You can also use the Pagefind JavaScript API from a small verification script or browser console:

const search = await pagefind.search("multilingual index");
const results = await Promise.all(search.results.map((item) => item.data()));

console.table(results.map((item) => ({
  url: item.url,
  title: item.meta.title,
})));

Run that code from the locale whose index you want to test. Pagefind initializes against the current document language.

Diagnose a mixed-language result

If an English page returns Traditional Chinese results, check these in order:

Inspect the generated English HTML, not the Astro source, and confirm <html lang="en">.
Confirm the English article itself has lang: en and was generated below /en/posts/.
Check that Pagefind was not built with --force-language or PAGEFIND_FORCE_LANGUAGE.
Clear stale static assets and browser caches after rebuilding.
If navigation changes languages without a full page load, reinitialize Pagefind after the root lang value changes.

The important distinction is that localized UI and localized search are separate concerns. Translate the controls with locale props, but let a correct <html lang> value define Pagefind's index boundary.

FAQ

Q: Does Pagefind automatically create separate language indexes?

A: Pagefind separates detected languages during one indexing run when the generated HTML documents have accurate lang attributes. In the browser, it uses the current document language to select the matching index, so the production HTML is the boundary to verify.

Q: Should I use `--force-language` for a multilingual Pagefind site?

A: No. --force-language deliberately forces the build into one language index, which bypasses Pagefind's multilingual separation. Let each generated page declare its actual language instead.

Q: Why does an English Pagefind search return pages in another language?

A: Start by inspecting the generated English page for <html lang="en">. Then check for --force-language, stale Pagefind assets, and client-side navigation that changes page content without updating the root language or reinitializing Pagefind.

References:

Pagefind multilingual search

Pagefind JavaScript API

Pagefind CLI configuration options

ZeroOne — English

Dockerize an Astro Static Site: Build dist, Serve It with Caddy

Use a two-stage Dockerfile

Keep the Docker build context small

Build and verify the container locally

Do not use this pattern for on-demand routes

FAQ

Q: Do I need Node.js in the final Docker image for a static Astro site?

Q: Why copy package files before the rest of the Astro project?

Q: Can I use Nginx instead of Caddy?

Build an Astro Multilingual Blog Without Migrating Existing URLs

Start with the URL contract

Put locale rules in one module

Filter content before sorting it

Generate explicit English routes

Keep feeds and metadata locale-specific

Verify the generated site, not only TypeScript

FAQ

Q: Can I add English pages without moving existing Astro URLs?

Q: Why does an English Astro post sometimes become /en/posts/en/...?

Q: Do all English and Traditional Chinese posts need hreflang links?

Hreflang for Independent Multilingual Content: When Pages Are Not Translations

Canonical and hreflang answer different questions

Decide whether two articles are equivalents

Represent translation as optional content data

Build alternates only for complete pairs

Keep independent English articles unpaired

Verify the generated HTML

FAQ

Q: Does every page on a multilingual site need hreflang?

Q: Should an English translation canonicalize to the original article?

Q: Should I publish hreflang when only one side of a translation pair exists?

Pagefind Multilingual Search in Astro: Keep Language Results Separate

How Pagefind chooses a language index

Make Astro render the canonical locale

Keep content discovery separated too

Localize the search interface with a prop

Validate the production indexes

Diagnose a mixed-language result

FAQ

Q: Does Pagefind automatically create separate language indexes?

Q: Should I use --force-language for a multilingual Pagefind site?

Q: Why does an English Pagefind search return pages in another language?

Q: Why does an English Astro post sometimes become `/en/posts/en/...`?

Q: Should I use `--force-language` for a multilingual Pagefind site?