User Guide 3: Enable and Customize Optional Features

Check the defaults before changing anything

This guide covers the accompanying 0.8.3 starter. Merge all TypeScript snippets into the defineThemeConfig({...}) object in src/site.config.ts. Configure only what you want to change.

1. Enable the music player

Put your audio at public/music/my-song.mp3 (create the directory if necessary), then add:

theme: {
  music: {
    enabled: true,
    tracks: [
      { title: 'My Song', artist: 'Artist Name', src: '/music/my-song.mp3' },
    ],
  },
},

The URL omits public. Each track requires title and src; artist is optional. Add more objects to tracks for more songs. Direct HTTPS audio URLs also work; local disk paths and music-platform sharing pages are not audio URLs. Avoid spaces and backslashes, and prefer simple filenames. No songs are bundled.

An empty playlist hides the player. With music enabled, invalid titles or URL formats cause configuration errors. The player mounts on pages using the shared theme layout; there is no per-page visibility switch. It sits at the lower left on desktop. On mobile, each page starts collapsed; expanding it temporarily hides back-to-top.

On the first visit, audio loads only after clicking PLAY. The tab session remembers the track, position and volume. If playback was active, navigating, reloading or returning with Back/Forward attempts to resume at the saved position; manual pause stays paused. A short gap is expected, not seamless playback. If the browser blocks automatic playback, click PLAY to continue. A removed track is not replaced automatically. Without storage, manual playback still works but session resume is unavailable. First check that /music/my-song.mp3 is accessible. When a track ends, the next starts automatically; after the last, playback returns to the first. Set enabled: false to disable the player.

Playback downloads the complete track into a browser Blob before starting, so seeking does not require HTTP Range support. Large files or slow connections increase startup time and memory use. Pause/resume reuses the loaded track; changing tracks releases it. Navigation loads the track again (the browser HTTP cache may help). External audio hosts must allow cross-origin fetch (CORS); putting files in public/music/ avoids this requirement.

2. Enable Giscus comments

Use the Giscus setup page: prepare a public GitHub repository, enable Discussions, install the Giscus app, and select a category. Copy the actual repository/category IDs from its generated configuration:

theme: {
  comments: {
    enabled: true,
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
    mapping: 'pathname',
    lang: '',
  },
},

Replace both REPLACE_WITH_... values, and use your actual category name. Fill in the theme configuration only; do not paste the full Giscus script into each post.

Comments appear on article pages. Missing core repo/category fields prevent rendering; placeholders do not make a working configuration. lang: '' follows the article language (zh maps to zh-CN); the default is fixed to en.

Keep mapping: 'pathname' to associate discussions with article paths. specific requires a nonempty term; number requires a positive integer as a string in number. Invalid or missing parameters for these modes throw errors.

Check the bottom of a post. If comments are absent, check IDs, repository permissions, connectivity, and browser blocking. Optional fields such as inputPosition, theme, and reactionsEnabled can retain defaults. strict and reactionsEnabled take strings '0' / '1'.

3. Replace About content

About body paragraphs and the signature preserve line breaks in configuration strings: \n starts a new line and \n\n leaves a blank line. Long sentences still wrap. This is plain text, not Markdown or HTML; do not insert <br>.

About is enabled by default. Configure its content per language without editing the page template:

i18n: {
  locales: {
    en: {
      about: {
        metaLine: '$ profile booted | mode: builder',
        sections: {
          who: 'Introduce yourself here.',
          what: 'Describe what you build.',
          ethos: ['Keep learning.', 'Build useful things.'],
          now: 'What you are working on now.',
          contactLead: 'Get in touch.',
          signature: '> Your signature',
        },
        contact: {
          email: 'you@example.com',
          githubUrl: 'https://github.com/yourname',
          githubLabel: 'GitHub',
        },
      },
    },
  },
},

This changes only English About content; fill in other locales separately, as nothing is automatically translated. sidebar, labels, modals, and effects also support overrides. Start with the body and contact details. About tool windows are theme demonstrations; writing their text does not connect a real AI service.

Visit /en/about/ to check the body, email, and GitHub links. Set theme.enableAboutPage: false to hide the navigation item and stop generating About routes. Rebuild after changing it.

4. Adjust post counts and pagination

You may set only the first two counts; add pagination when you want a fixed pagination appearance:

theme: {
  homeLatestCount: 3,
  blogPageSize: 9,
  pagination: {
    windowSize: 7,
    showJumpThreshold: 12,
    jump: { enabled: true, enterToGo: true },
    style: { enabled: true, mode: 'fixed', variants: 9, fixedVariant: 1 },
  },
},

homeLatestCount controls recent posts on the homepage. blogPageSize controls posts per blog page and is also used by tag post lists. Use reasonable positive integers.

windowSize controls the page-number window, clamped to 5–21, not the number of posts per page. The jump input appears only when jump.enabled is true and total pages exceed showJumpThreshold (over 12 by default). enterToGo controls jumping with Enter.

Style modes are fixed, sequential, and random. The example fixes variant 1. Default random selects a stable variant from language, path, page information, and related inputs; it does not reshuffle on every refresh. style.enabled: false uses the basic variant, without disabling pagination. Check the list footer once you have enough posts.

5. Disable enhancements you do not need

These are available off switches, not a recommendation to disable everything. Keep only fields you want to change:

theme: {
  enableAboutPage: false,
  effects: { enableRedQueen: false },
  search: { enabled: false },
  toc: { enabled: false },
  tags: { enabled: false },
  socialImage: { enabled: false },
},

enableRedQueen controls only the article Red Queen monitor, not the entire AI theme or all effects. toc is a site default that a post’s toc: true can override. Disabling socialImage leaves manual ogImage working. Search and tag switches affect both their entries and generated output. Existing layouts determine the four page atmospheres; there is no global selector that switches the whole site among the four themes.

6. Add languages and adjust the homepage URL

For example, add French:

i18n: {
  locales: {
    fr: {
      meta: { label: 'Français', hreflang: 'fr', ogLocale: 'fr_FR', enabled: true, fallback: ['en'] },
      site: { hero: 'Bienvenue sur mon blog.' },
      messages: { nav: { home: 'Accueil' }, siteDescription: 'Mes notes et projets.' },
    },
  },
},

Then create content with npm run new-post -- french-note --locales fr. Provide interface text, a homepage introduction, About, and post translations yourself. fallback supplies missing configuration/text; it neither translates posts nor inserts other languages’ posts into a list. The default locale is added to the fallback chain when needed.

Change meta.label to rename a language in the menu; for example, zh defaults to “简体中文”. hreflang / ogLocale describe language metadata. Changing the displayed name does not change the locale code or URL.

The default i18n.routing.defaultLocalePrefix: 'always' redirects / to the default-language homepage. 'never' serves that homepage at / and redirects /<default-locale>/ back to /. This affects only the default homepage, not blog paths: /en/blog/ does not become /blog/.

7. Merge settings and verify

For example, combine the post count and music in one theme object:

theme: {
  homeLatestCount: 5,
  music: {
    enabled: true,
    tracks: [{ title: 'My Song', src: '/music/my-song.mp3' }],
  },
},

Keep existing settings such as theme.comments in that same object. Do not overwrite your configuration with a whole example. Arrays replace previous arrays, so retain existing tracks or social links when adding entries.

Check the feature in development, then run npm run check and npm run build. Test search with npm run preview after building. Use npm run doctor when diagnosing project or upgrade problems; it performs broader checks. Deploy the new output to publish changes.

8. Show or hide footer credits

The footer displays the current build year and your site.title. By default it also links to the theme and Astro: © 2026 My Blog · Theme by Anglefeint · Built with Astro. The year is generated during the build, not hard-coded.

To hide both technical credits, merge this setting into src/site.config.ts:

export const THEME_CONFIG = defineThemeConfig({
  theme: {
    footer: { showCredits: false },
  },
});

Set showCredits: true to restore them. Hiding credits removes both links; it keeps the copyright line. An optional site.tagline adds your own plain text independently of this switch. Its default is empty; the former default Built with Astro. is treated as the built-in credit to avoid duplication. No All rights reserved text is added.

Automatic cards use a bundled code-rain, terminal and neon-network background, with your own site name, title and author. The small Theme by Anglefeint credit at the bottom right follows theme.footer.showCredits (default true); set it to false to hide both footer credits and this image credit. Rebuild and redeploy after changing it. Custom ogImage files are never modified. The artwork works offline and adds no browser JavaScript.

The public demo uses its own name, domain and translated introduction. A fresh starter keeps generic defaults, and you still configure your site only in src/site.config.ts. If you upgrade an older starter, use the matching configuration files described in the upgrade guide; updating only the npm package does not add this option to old adapters.

In this series

• User Guide 1: Set Up Your Blog
• User Guide 2: Write and Organize Content
• User Guide 3: Enable and Customize Optional Features

Mathematical formulas

Markdown and MDX articles support LaTeX-style math globally by default. Write $C_{saved}$ inline or put a formula between separate $$ lines. No per-post flag or extra plugin installation is needed.

Inline: $C_{saved}$

$$
\frac{a}{b}
$$

Disable with theme: { math: { enabled: false } } in src/site.config.ts. Escape literal dollars as \$ when ambiguous; code spans and fenced code remain literal. Disabling math restores normal MDX rules, including JavaScript expressions in braces.

Rendering happens at build time with local KaTeX styles/fonts and accessible MathML, without a browser math engine. Long display formulas scroll horizontally. Invalid formulas stop the build with a source/error message. Keep titles and descriptions plain text; formulas are excluded from search indexing. Supported math is KaTeX syntax, not complete LaTeX documents.

Older projects need the one-time starter/configuration migration described in the upgrade guide; updating only the theme package does not wire the Markdown processor.

$C_{saved}$