pluginSsg

The required plugin for outputting pages as static HTML. It generates HTML from JSX, TSX, Markdown, and MDX, and outputs CSS, JavaScript, and images referenced by pages.

It also includes the former features of pluginMdx(), pluginBundle(), and pluginEntry().

See Getting started for setup and File-based routing for creating pages. This page covers settings and public API contracts.

Table of Contents

Options

Defaults
pluginSsg({
  src: ["src/pages/**/*.{tsx,jsx,mdx,md}"],
  srcBases: ["src/pages"],
  layout: "src/layouts/index.{tsx,jsx}",
  mdx: {
    frontmatter: {
      name: "metadata",
    },
    remarkPlugins: [],
    rehypePlugins: [],
  },
  bundle: {
    outName: "bundle",
  },
  removeImagePreload: true,
})

src

  • Type: string[]
  • Default: ["src/pages/**/*.{tsx,jsx,mdx,md}"]

Specify page templates as project-root-relative globs. Vite's glob import loads matching files. Legacy paths with a leading slash are treated as the same locations.

srcBases

  • Type: string[]
  • Default: ["src/pages"]

Specify directories relative to the project root to remove from the start of page file paths when determining URLs. For example, with srcBases: ["src/pages"], removing src/pages and the extension from src/pages/about.tsx produces /about. Legacy paths with a leading slash are treated as the same locations.

layout

  • Type: string
  • Default: "src/layouts/index.{tsx,jsx}"

Specify the component wrapping all page templates relative to the project root. Vite's glob import loads matching files and the first file found is used. Legacy paths with a leading slash are treated as the same locations.

mdx

  • Type: false | (MdxCompileOptions & { frontmatter?: false | { name?: string } })
  • Default: { frontmatter: { name: "metadata" }, remarkPlugins: [], rehypePlugins: [] }

MDX and Markdown conversion settings. YAML and TOML frontmatter become an MDX export named by frontmatter.name; set frontmatter: false to disable only frontmatter conversion. Enclose YAML with --- and TOML with +++. MDX as a whole is enabled by default; set mdx: false to disable it. If src is omitted, disabling MDX also limits default discovery to JSX and TSX.

bundle

  • Type: { outName: string }
  • Default: { outName: "bundle" }

Bundles CSS imported by pages and layouts and outputs referenced images. outName is the base name for the bundled CSS file, without an extension. For example, outName: "site" produces assets/site-[hash].css with the default output settings. With CSS Modules, the generated HTML and CSS use the same class names.

removeImagePreload

  • Type: boolean
  • Default: true

Removes link[rel="preload"][as="image"] from React renderer output before composing the Head API. This applies to development and builds, regular pages, and static Island rendering. client:only content is not statically rendered. Set false to preserve renderer output.

This setting does not distinguish automatically generated and handwritten elements. Image preloads written directly in regular JSX, including a Layout's <head>, are also removed. Use the Head API to preserve explicit preloads. Resource hints for other types, such as fonts, are unchanged.

Page

Default discovery uses src/pages/**/*.{tsx,jsx,mdx,md}. JSX and TSX files default-export a component. Markdown and MDX content becomes the page.

metadata is read as page data, and pages with draft: true are excluded from production builds. Markdown and MDX frontmatter becomes metadata by default. If you change the export name, also export it as metadata to pass it as page data.

Static data and route generation

Return { props } or an array of { paths, props } from getStaticData(). paths has keys matching dynamic file name parameters and string values.

Page modules and fetching functions run during development, builds, check, and regular inspect. They do not run for each request after publishing. See Page generation from APIs for examples.

Layout

The default file is src/layouts/index.{tsx,jsx}. Its default-exported component receives page data and children. Use metadata and getStaticData() to provide shared data.

If the root returns html, the layout's html, head, and body are used. Otherwise, a default structure wraps it. The default language is en; change it through the layout's html or Head.htmlAttributes.

Layouts in directories do not automatically nest. See Layouts for examples.

Import from minista/head to add head elements from pages and components. See Head for usage.

FieldPurpose
childrenElements such as title, meta, link, script, and style
htmlAttributesAttributes of the html element
bodyAttributesAttributes of the body element
Child element keyReplace an element with the later one sharing its key

Head is applied after the layout and takes priority for duplicate title, charset, and viewport elements. Missing charset and viewport values are supplied by default and placed at the start of the head in that order.

Public assets

Reference public/logo.svg as /logo.svg in JSX or MDX. At build time, pluginSsg() identifies existing public files and automatically applies Vite's base to reference URLs. No additional option is needed. Changes to publicDir and publicDir: false are supported.

baseindex.htmldemos/index.html
//logo.svg/logo.svg
/test//test/logo.svg/test/logo.svg
./ or an empty stringlogo.svg../logo.svg
https://cdn.example.com/https://cdn.example.com/logo.svghttps://cdn.example.com/logo.svg

The following HTML elements and attributes are adjusted. In each case, base is applied when a URL starts with / and points to an existing public file.

HTML elementURL attributeExample use
imgsrc, srcsetImages and size variants
sourcesrc, srcsetVideo, audio, and image sources
linkhref, imagesrcsetCSS, favicons, and image preloads
scriptsrcLoading JavaScript
videosrc, posterVideos and poster images
audio, tracksrcLoading audio and subtitles
SVG image, usehref, xlink:hrefImage and symbol references
objectdataEmbedding external files
embed, inputsrcExternal files and image buttons
ahrefLinks to public files such as PDFs
Supported metacontentOGP images and similar resources; see below

Supported meta elements have a property of og:image, og:image:url, og:image:secure_url, og:audio, og:audio:secure_url, og:video, or og:video:secure_url. A name of twitter:image, msapplication-TileImage, msapplication-square70x70logo, msapplication-square150x150logo, msapplication-wide310x150logo, msapplication-square310x310logo, or msapplication-config is also supported.

Regular url() references in style attributes and <style> are also supported. Query strings and fragments such as /logo.svg?v=1#mark, and srcset descriptors such as 1x and 640w, are preserved.

The following references are not automatically adjusted.

  • External URLs, data URLs, fragment-only references such as #icon, and relative URLs such as ./logo.svg
  • Regular page links and custom data attributes
  • URLs inside public CSS, JavaScript, JSON, and other files. The files themselves are copied unchanged.
  • URLs with CSS escapes, @import strings, and image-set() strings in style attributes or <style>
  • URLs constructed by JavaScript in the browser
  • References inside Islands, including client:only fallbacks

Islands need to use the same URLs in static HTML and the initial browser render. Prepare URLs that include base and pass them as props, for example, to keep both renders consistent.

HTML assets

CSS, JavaScript, and images referenced through HTML attributes are included in builds. See CSS, JS, and TS entries for setup examples.

SSG also continues to output CSS and images referenced through imports in page and Layout modules.

Supported elements and attributes

When bundling source files inside the project root as entries, collection and rewriting are limited to the following targets. For public files, see "Public assets" above.

ElementAttributeValue handling
linkhrefSingle URL; not limited by rel
scriptsrcSingle URL
imgsrcSingle URL
img, sourcesrcsetEach candidate URL; preserves 1x and 640w
SVG usehrefSingle URL; preserves the symbol fragment

Only project-root-relative references starting with / are collected, and only actual files inside the root are bundled. References such as https://, //cdn.example.com/, data:, #icon, and ./image.png are unchanged. Commas inside single URLs and data URLs in srcset are preserved. Place whitespace between srcset URLs and descriptors.

meta[content], video[poster], a[href], source[src], SVG image[href] and use[xlink:href], and identically named attributes on arbitrary elements are excluded. For example, <meta property="og:image" content="/src/image.png" /> alone does not output the image. Use an image URL imported through SSG or a public asset URL for these attributes.

Vite copies public/public.svg referenced as /public.svg, and SSG applies base to its reference URL. References with no actual file in either the root or public are left unchanged without missing-file diagnostics. Avoid placing files for the same URL in both the project root and public, because Entry bundles the root file.

/src/app.ts?v=1#start bundles src/app.ts and preserves ?v=1#start in the output URL. The query is not passed as a Vite module transformation directive such as ?raw or ?url. Output URLs follow Vite's base, supporting /site/, absolute CDN URLs, and page-relative URLs with ./ or an empty string. Do not add base to the input /src/… path.

CSS imported by an entry is inserted only into pages referencing that entry. A stylesheet with the same URL is not inserted again, including when multiple entries share CSS. Stylesheet URLs with different queries or fragments are treated separately.

Public types

Import Metadata, PageProps, LayoutProps, StaticData, and GetStaticData from minista/types. Pages and layouts receive fields such as url, title, and draft. Layouts also receive children.

See TypeScript for custom field types and module augmentation. Adding types alone does not generate HTML elements.