Skip to content

IntegrationOptions

Jump to bottom
yCENzh edited this page Sep 19, 2026 · 1 revision

Integration options

Everything the integration accepts:

import { defineConfig } from "astro/config";
import shirones from "shirones";

export default defineConfig({
  integrations: [
    shirones({
      paths: { root: "shirones" },
      components: {},
      fonts: { subset: true },
      pagefind: true,
      bundledIntegrations: true,
      injectRoutes: true,
      excludeRoutes: [],
    }),
  ],
});

Every key is optional. The defaults are the values above.

paths

Where your content and config live, relative to the project root.

shirones({
  paths: {
    root: "shirones",   // container for config and content
    config: "shirones/config",
    data: "shirones/config/data",
    content: "shirones/content",
  },
})

root is shorthand: setting it relocates config, data and content together. Setting any of the three individually overrides just that one.

If you move content, update the base paths in src/content.config.ts to match — the collection loaders are separate from the integration's path resolution, and a mismatch produces a warning rather than an error:

[WARN] [glob-loader] The `base` path ... does not exist

Astro logs that and builds the site with the collection silently empty, which is easy to miss.

Absolute paths work too.

components

The explicit override map. Keys are package-relative component paths without an extension; values are project-relative paths.

shirones({
  components: {
    "atoms/blog/PostCard": "./src/components/MyPostCard.astro",
    "layouts/Layout": "./src/layouts/SiteLayout.astro",
  },
})

Only needed when mirroring the theme's directory structure is inconvenient. Mirroring is the usual route — see Overriding components.

A value pointing at a missing file throws at config time.

fonts

shirones({
  fonts: {
    subset: true,
    extraCharacters: "→✓✗",
  },
})

subset turns build-time font subsetting on or off. It defaults to command === "build", so astro build subsets and astro dev does not.

It is combined with fontConfig.subsetting.enable, not a fallback for it — both have to hold. Setting enable: true in your font config and leaving fonts alone still gives you unsubsetted fonts in dev. That asymmetry is deliberate: subsetting scans your content and runs subset-font, which you do not want on every dev server start.

extraCharacters adds glyphs to the subset that your content does not contain but your site renders anyway — icons inserted by client-side scripts, characters that only appear in a dynamically-built string. Anything the charset scan cannot see goes here.

The full subsetting pipeline is described in Fonts.

pagefind

shirones({ pagefind: false })

Defaults to true. After astro build, the integration indexes dist/ and writes dist/pagefind/.

Turn it off if you index separately, or if you do not want search. Failures are warnings rather than errors — a build that cannot produce a search index still produces a site:

[WARN] skipped Pagefind indexing: <reason>. Set `pagefind: false` to silence this warning.

bundledIntegrations

shirones({ bundledIntegrations: false })

Defaults to true, which registers the integrations the theme needs so that a fresh project only has to list shirones():

  • @swup/astro — page transitions
  • astro-icon — icon sets
  • astro-expressive-code — code blocks, with the collapsible-sections and line-numbers plugins
  • @astrojs/svelte — with vitePreprocess configured for the theme's Stylus component styles
  • @astrojs/sitemap — filtered through your sitemapFilter config
  • @astrojs/mdx
  • oddmisc/astro — only when Umami is configured

Set it to false when you want to register these yourself, which is what you would do to pass options the theme does not expose. You then own getting them right; the theme's components assume they are present.

injectRoutes

shirones({ injectRoutes: false })

Defaults to true, which registers the theme's pages with Astro. Your project has no src/pages/ directory, so this is where /archive, /tags, /friends and the rest come from.

Turn it off if you are supplying your own page tree. You will need to cover everything the theme's pages do.

excludeRoutes

shirones({ excludeRoutes: ["/anime", "/devices"] })

Drops specific injected routes. Useful for pages whose data you do not maintain — the anime and devices pages are the usual candidates.

Patterns match the route, with or without the leading slash: "/anime" and "anime" both work. Dropping a route does not remove the config module behind it; animeConfig.ts is still read, the page just is not registered.

The injected routes are:

/404                    /[...page]              /[...permalink]
/about/                 /albums/                /albums/[id]/
/anime/                 /archive/               /atom/
/atom.xml               /categories/            /compass/
/devices/               /friends/               /games/
/llms.txt               /llms-full.txt          /moments/
/posts/[...slug]/       /projects/              /robots.txt
/rss/                   /rss.xml                /series/
/series/[slug]/         /skills/                /tags/
/timeline/

Twenty-eight routes, collected by walking the package's src/pages/ at config time. The homepage is served by the [...page] catch-all, which also handles paginated list pages — there is no separate index.astro.

What you cannot configure here

trailingSlash is forced to "always", and image.endpoint.route is set alongside it. The two are coupled: Astro appends a trailing slash to the image endpoint route during config resolution, and a /_image route that does not match the policy 404s in dev. Setting either yourself has no effect.

site and base come from shirones/config/siteConfig.ts, not from this file. That keeps them next to the rest of your site identity, and lets the integration apply them consistently.

Next

Clone this wiki locally