Project settings

Most sites can use Shiso's default folder and URL structure. Create a shiso.config.ts file at the project root when you need to change where content lives, serve docs at a different path, or provide the site's public URL.

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  docsPrefix: '/docs',
  contentDir: 'content/docs',
  siteUrl: 'https://docs.example.com',
  locale: 'en-US',
});

The file is optional: when it does not exist, the defaults shown above apply. shiso.config.mjs and shiso.config.js also work if you prefer plain JavaScript; a bare export default { ... } object is fully supported without the defineConfig helper.

Documentation URL#

docsPrefix is the path that appears before every documentation page. It defaults to "/docs".

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  docsPrefix: '/help',
});

With this setting, the documentation home is /help and a page named installation is available at /help/installation.

Set docsPrefix to an empty string to serve documentation from the root of the site:

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  docsPrefix: '',
});

Content folder#

contentDir tells Shiso where to find your Markdown and MDX files, relative to the project root. It defaults to "content/docs".

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  contentDir: 'content/docs',
});

After changing this setting, move or create your pages in the matching folder and keep navigation page entries relative to that folder.

Production site URL#

siteUrl is the public origin of your deployed site. Do not include a trailing slash or the documentation prefix.

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  siteUrl: 'https://docs.example.com',
});

Set it before deploying so Shiso can generate canonical URLs, Open Graph URLs, structured data, sitemap.xml, and absolute links for AI actions.

Locale#

locale controls deterministic date formatting. Interface text such as menu, search, and table-of-contents labels is supplied by the active theme rather than configured as documentation content:

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  locale: 'fr-FR',
});

MDX plugins#

Extend the Markdown compiler with Unified remark or rehype plugins through mdx. Install plugins in your project, import them in shiso.config.ts, and add them in execution order:

import { defineConfig } from '@umami/shiso/config';
import rehypeKatex from 'rehype-katex';
import remarkMath from 'remark-math';

export default defineConfig({
  mdx: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

Remark plugins run after Shiso enables frontmatter and GFM, and before its code-title and table-of-contents transforms. Rehype plugins run before Shiso's syntax highlighting, zoomable images, heading IDs, and permalinks. Plugin hooks execute only at build time and are not included in the browser bundle.

Restart the development command after changing the plugin list so Vite can recreate the compiler pipeline.

How page names become URLs#

Every page named in navigation matches a .md or .mdx file in your content folder. With the default contentDir and docsPrefix:

The same mapping applies when you customize either setting; only the content folder and URL prefix change.

Migrating from $shiso#

Earlier Shiso versions read these settings from a $shiso key in docs.json. That key is no longer supported: move its fields into shiso.config.ts and delete it from docs.json. shiso check reports any docs.json that still contains $shiso.

// shiso.config.ts, replacing "$shiso": { "siteUrl": "..." } in docs.json
import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  siteUrl: 'https://docs.example.com',
});

Editor help and validation#

Keep the schema reference at the top of docs.json to get autocomplete, field descriptions, and inline validation in supported editors:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json"
}

Shiso checks docs.json and loads shiso.config.ts when it builds your site. To check both without running a full build, use:

pnpm check

Common mistakes#

• The page is named in navigation, but its file does not exist.
• The file exists, but it is not included in navigation.
• A nested page name does not match its folder structure.
• siteUrl includes /docs, another path, or a trailing slash.
• An mdx plugin is installed in a different workspace or cannot be imported.
• $shiso is still present in docs.json after upgrading.

See Troubleshooting for help with build and navigation errors.