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 sets the default language for Shiso’s interface and date formatting. On multilingual sites, the current page’s language takes precedence. This also applies to standalone pages with a language and updates when readers switch languages:

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

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

Interface translations#

Shiso includes English (en), Spanish (es), French (fr), German (de), Japanese (ja), Simplified Chinese (zh-Hans), and Traditional Chinese (zh-Hant). These dictionaries cover navigation, search, feedback, copy controls, accessibility text, and generated API reference labels.

Use translations in shiso.config.ts to override individual labels or add another language. Keys are checked by TypeScript and validated when Shiso loads the config. Locale tags are canonicalized, so fr-ca becomes fr-CA.

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

export default defineConfig({
  locale: 'fr-FR',
  translations: {
    fr: {
      nextPage: 'Continuer',
      previousPage: 'Retour',
    },
    'fr-CA': {
      searchPlaceholder: 'Rechercher dans la documentation...',
    },
    nl: {
      nextPage: 'Volgende',
      previousPage: 'Vorige',
    },
  },
});

Each label falls back from the exact locale to its script (when applicable), then its base language, then English. At each level, your overrides take precedence over Shiso’s dictionary. For Chinese, Shiso infers the script when omitted: zh-TW, zh-HK, and zh-MO use Traditional Chinese; zh-CN, zh-SG, and zh use Simplified Chinese. An explicit script always wins. Unsupported languages and missing keys fall back to English.

Import ThemeLabels or Translations from @umami/shiso/config for separately maintained dictionaries. ThemeLabels describes a complete dictionary; Translations accepts partial dictionaries keyed by locale. When translating viewNamedImage or apiExampleResponse, preserve the {alt} or {status} placeholder respectively.

Shiso translates its built-in defaults. Your page content, navigation titles, and explicit docs.json text (such as search.prompt, edit-link labels, and feedback messages) remain under your control and take precedence.

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.