﻿---
title: "User Guide 8: Publish the Blog on Your Own Domain"
description: "Static deployment, domains and environment overrides, build/image files, search and public exports, plus optional GA4."
url: "https://demo.anglefeint.com/en/blog/starter-guide-deployment/"
language: "en"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-13T00:00:00.000Z"
---

# User Guide 8: Publish the Blog on Your Own Domain

This is part 8 of 8. [See the full tutorial sequence](https://demo.anglefeint.com/en/blog/starter-guide-1-configure-your-site/#tutorial-order) · [Look up configuration fields](https://demo.anglefeint.com/en/blog/config-reference/).

Once the blog works locally, publication involves three tasks: confirm the final domain, generate all static files, and have hosting serve them at that domain. The theme does not buy domains, change DNS or log in to hosting for you.

The starter builds a static website by default. Production needs neither a persistent Node.js service nor an SSR adapter for these pages. This guide assumes npm and default output `dist/`.

## 1\. Confirm the public address

Prepare a domain you control, such as `https://blog.example.com`. Merge into existing top-level `site` in `src/site.config.ts`:

```ts
site: {
  url: 'https://blog.example.com',
},
```

Use the final public address, not localhost, an article URL or a hosting dashboard URL. Retain the other site settings.

This value generates canonical URLs, RSS, sitemap, sharing images and public content links. It neither changes the local dev address nor automatically points an unbound domain at your website.

### Check old environment overrides

`PUBLIC_SITE_URL` in `.env`, applicable `.env.*` files or hosting build settings overrides the configuration. If changing site.url leaves the old domain, inspect all these locations. Ordinary dev uses development mode and build uses production; custom `--mode` also reads its corresponding files, so checking only `.env` is insufficient.

Remove unnecessary overrides and use site.url, or set correct values in each build environment. Rebuild after changes rather than manually editing one URL in old output.

### Deploy at the domain root

The theme currently assumes a domain root such as `https://blog.example.com/`. Subdirectories such as `https://example.com/my-blog/` require further adaptation. Astro base alone does not establish compatibility for every page/resource.

Choose hosting that serves a root website, static directory index.html files and direct subpage URLs. With GitHub Pages, prefer its site-domain/custom-domain setup. A generic project-subdirectory tutorial does not prove that deployment mode is supported here. See [Astro deployment documentation](https://docs.astro.build/en/guides/deploy/) and its hosting guides.

## 2\. Prepare all required source files

Deploy your own blog project and the branch holding your actual content, rather than treating the theme maintainer demo as a personal blog. Include project configuration, content, dependency manifests and resources.

After adding or replacing local covers or fragment images, normal dev, build and doctor prepare responsive files automatically. Commit these source files:

*   Articles, fragments, custom pages and `src/site.config.ts`.
*   Referenced originals, public images, icons and required music/resources.
*   Used originals in `src/assets/blog/covers/originals/`. Keeping manifest.json and generated/ in Git is recommended for reuse; missing derivatives are generated automatically.
*   `package.json`, `package-lock.json` and original Astro/hosting configuration.

Originals may also live beside articles or in public; commit those locations too. See [images](https://demo.anglefeint.com/en/blog/starter-guide-images/) for preparation details.

Normal dev, build and doctor runs, including CI, reuse correct responsive files and automatically prepare missing, stale or modified derivatives. Commit the original images and content. Committing `src/assets/blog/covers/manifest.json` and `generated/` allows reuse across checkouts, but these generated files are not a prerequisite for automatic preparation. Missing originals, unsafe paths and invalid image inputs still fail validation. This does not depend on deployment-platform image caches. Explicit `prepare-covers --check` and configuration sync remain read-only.

**Version note:** Automatic image preparation during normal builds and CI doctor runs requires 0.36.2 or later. With 0.36.1, first run dev or `prepare-covers` to prepare derivatives. Explicit `prepare-covers --check` and configuration sync remain read-only.

Git-based deployment does not require committing node\_modules, `.astro` or dist; the platform installs dependencies and builds output. Do not upload local dependencies as a static website. If environment files are not committed, configure necessary variables on the platform. PUBLIC\_ values are public site information, not a place for secrets.

## 3\. Check and preview actual build output locally

Stop dev with Ctrl+C, confirm the terminal is at the project root, then run:

```bash
npm run doctor
npm run preview
```

Open preview’s printed address. Check home, posts, images, language menu and article search, plus entries for newly enabled languages/pages. External services such as comments require actual browser connectivity; a passing build cannot prove remote permissions.

The commands have different responsibilities:

| Command | Responsibility |
| --- | --- |
| `npm run dev` | Local development and related image preparation; no built full-text index. |
| `npm run doctor` | Image preparation (including CI), Astro checks and build; About runtime configuration checked when enabled. |
| `npm run check` | Calls the same doctor in the current starter; do not run both consecutively. |
| `npm run build` | Prepares/reuses responsive images and builds the site. |
| `npm run preview` | Serves existing dist without building or publishing. |

Fix any error before deployment. Do not publish leftover dist after failure. doctor already produces a build, so immediately repeating check/build is unnecessary. Stop preview with Ctrl+C.

## 4\. Deploy the entire static output

You can connect Git for hosted builds or upload a local build manually. Both serve equivalent static output.

### Option 1: Build from Git on the host

Connect your repository and configure:

| Setting | Current starter value |
| --- | --- |
| Build branch | The branch where you maintain blog content. |
| Project root | Directory containing the blog’s package.json, not necessarily repository root. |
| Node.js | Meets project/dependency requirements; current starter specifies 22.12.0 or newer. |
| Installation | npm projects can use `npm ci`, requiring committed package-lock.json matching package.json. |
| Build command | `npm run build` |
| Output directory | `dist`, relative to project root. |

If hosting already installs dependencies, do not add a duplicate install command. If a full script is required, install before build. Do not stack doctor, check and build. Automatic derivative preparation cannot recover originals omitted from Git.

Use the platform’s actual framework preset, branch and installation controls. Choose static output. npm run dev and npm run preview are not production startup commands.

### Option 2: Upload a local build

After local doctor succeeds, upload all `dist/` contents to the site’s document root. Select dist if asked for an output directory; upload files inside it if asked for website files. Do not add an extra dist path layer.

Include `_astro/`, `_blog-covers/`, `_social/`, search indexes and every other generated file in addition to HTML. Underscore directories are not disposable temporary files; omitting them breaks styles, scripts, images or search.

Use complete deployment/replacement when republishing. Merely overlaying new files can retain deleted posts, old pages and disabled languages. Deleting local Markdown does not delete previously uploaded HTML automatically.

## 5\. Connect the domain on the host, then configure DNS

Add the custom domain on the hosting platform. Use the actual records it supplies in your domain’s DNS management. Apex/subdomain record types and targets may differ; do not copy an example IP.

Wait for domain validation and HTTPS certificate readiness, then open the public address. If using apex, www or other alternative hosts, select a primary address, redirect alternatives at the host and set site.url to the primary.

Canonical metadata is not an HTTP redirect. site.url does not perform DNS changes, certificate issuance or multi-domain redirects. Hosting/domain settings handle those. Rebuild and redeploy after changing the primary domain, updating any old environment override too.

## 6\. Check published pages and public output

Open a direct article URL through the public domain and refresh it. Navigation from home alone does not prove direct paths work. Check images, code styles, language switching and search. Features tested only in dev must also be checked in the built site.

The theme already supplies these static outputs; do not install duplicate integrations:

| Example address | Purpose |
| --- | --- |
| `/robots.txt` | Crawl rules and sitemap address, not access control. |
| `/sitemap-index.xml` | Sitemap entry; links should use the public domain. |
| `/zh/rss.xml` | Chinese article feed; replace zh for other enabled languages. |
| `/llms.txt` | Main AI-readable index. |
| `/zh/llms.txt`, `/zh/llms-full.txt` | Language index/full-text bundle when exportable content exists. |
| `/zh/blog/my-first-post/index.md` | Public article Markdown; replace the example slug. |
| `/zh/fragments/index.md`, `/zh/about/index.md` | Public content when pages are enabled and satisfy export conditions. |

Sitemap article dates use updatedDate, then pubDate, without inventing a new date per build. Disabled languages/pages need not have exports. Article search: false is not privacy and does not suppress other public output.

AI exports contain public articles and enabled Fragments/About. Comments and decorative tools are excluded. Actual noindex or off-site-canonical pages are excluded. A user file conflicting with a generated path stops the build instead of being overwritten. Rebuilt export files and discovery links must be deployed together.

Metadata and text improve discovery/readability but do not guarantee indexing, AI citations or traffic.

### Hosting response headers

The build merges `X-Robots-Tag: noindex` for `/:locale/terminal/*` into dist/\_headers, preserving rules without changing source public/\_headers. Compatible hosts apply that file; others need equivalent header configuration.

Astro preview does not simulate hosting \_headers. Check the actual production response to verify headers rather than only the file’s existence. This rule does not require a Node server.

See [environment priority](https://demo.anglefeint.com/en/blog/config-site-chrome/#environment) and [public supplement fields](https://demo.anglefeint.com/en/blog/config-analytics-ai/#supplement) for exact definitions.

## 7\. Optionally add AI-readable context

Normal publication needs no extra configuration. To explain the site or link resources, merge at the top level:

```ts
aiReadableContent: {
  notes: 'This site records my learning and may be revised.',
  links: [{ label: 'Project home', href: 'https://example.com/project' }],
},
```

notes accepts Markdown; links require label and href. Use public HTTP(S) URLs. Relative targets, including root paths, resolve against the site address. This is public site context, not replacement article text or an article privacy restriction.

Use `i18n.locales.<locale>.aiReadableContent` for language overrides. For example, provide Chinese notes without extra links:

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容是作者自己的学习笔记。',
        links: [],
      },
    },
  },
},
```

Omitted fields inherit global values. notes: ‘’ or links: \[\] explicitly hides that part. Supplements enter relevant indexes, full-text bundles and article Markdown. Only enter information you intend to publish, and rebuild after changes.

## 8\. Optionally enable GA4 analytics

Google analytics scripts are off by default. Obtain the G- Measurement ID from your Google Analytics web data stream; see [Google’s instructions](https://support.google.com/analytics/answer/9539598). The theme only accepts G- IDs, not numeric property IDs, GTM container IDs or other identifiers.

Merge at the top level alongside site:

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
},
```

Replace the placeholder with your real ID; an empty string disables it. Invalid formatting causes configuration errors. One ID can cover every language, distinguished by URL paths. Do not paste a separate script per atmosphere/language.

The loader appears only in production builds with an ID, not dev. It skips reporting on localhost, its subdomains and loopback addresses. LAN IPs or remote preview domains can report; not all previews are excluded.

After redeployment, visit the public address and check GA4 realtime reports. Script blocking, networks and analytics settings affect results. Avoid installing the same analytics through manual code, GTM or another tool as well. No consent-management UI is bundled; add a suitable solution if needed.

## 9\. Troubleshoot deployment

| Symptom | Check first |
| --- | --- |
| npm ci fails | Node/dependency requirements and a committed package-lock consistent with package.json. |
| Image missing/stale/modified | Build repairs derivatives; check committed originals, safe paths and valid inputs if it fails. |
| Build succeeds but pages return 404 | Output directory, branch, root/index support and unsupported subpath deployment. |
| Home works but article refresh returns 404 | Real static subpaths, full output publication and accidental SPA fallbacks. |
| Missing styles, images or search | Full dist deployment, resource directories and path rewriting. |
| Canonical/RSS still uses example domain | site.url, PUBLIC\_SITE\_URL, dotenv mode and a new build/deployment. |
| Configuration changes not live | Correct project/branch/latest commit, not only local edits. |
| Deleted post remains reachable | Stale output/cache; check full replacement and hosting caches. |
| No GA4 data | Real G- ID, production build, nonlocal address and script blocking. |

For routine updates: edit/prepare locally → check/preview → commit sources → build/deploy. See [installation](https://demo.anglefeint.com/en/blog/starter-guide-1-configure-your-site/) for upgrades and [languages](https://demo.anglefeint.com/en/blog/starter-guide-languages/) for language paths.

## Tutorial navigation and configuration reference

This completes first publication. Return to the relevant tutorial or dictionary for later changes.

[Previous: make the blog available in more languages](https://demo.anglefeint.com/en/blog/starter-guide-languages/) · [All eight tutorials](https://demo.anglefeint.com/en/blog/starter-guide-1-configure-your-site/#tutorial-order).

Related fields: [domain and environment overrides](https://demo.anglefeint.com/en/blog/config-site-chrome/), [GA4 and AI-readable context](https://demo.anglefeint.com/en/blog/config-analytics-ai/), [search resources](https://demo.anglefeint.com/en/blog/config-search/). Full paths, defaults and limits are in the [reference index](https://demo.anglefeint.com/en/blog/config-reference/).
