@umami/shiso 1.4.0 → 1.6.0

package/src/lib/paths.ts

@@ -1,5 +1,4 @@
-import rawConfig from 'virtual:shiso-docs-config';
-import type { ShisoOptions } from '@/lib/types';
+import shiso from 'virtual:shiso-config';
 
 /**
  * All URL construction goes through this module.
@@ -14,10 +13,11 @@ import type { ShisoOptions } from '@/lib/types';
  * DOCS_PREFIX but not BASE_URL. React Router's `basename` adds BASE_URL, so
  * only code that bypasses the router (prerender output paths, canonical URLs,
  * raw <a href>) needs `toHref`.
+ *
+ * Values from `virtual:shiso-config` arrive with defaults applied and already
+ * normalized by scripts/load-shiso-config.mjs.
  */
 
-const shiso = ((rawConfig as { $shiso?: ShisoOptions }).$shiso || {}) as ShisoOptions;
-
 /** Strips trailing slashes; "/" and "" both normalize to "". */
 function normalizePrefix(value: string): string {
   const trimmed = value.trim().replace(/\/+$/, '');
@@ -31,13 +31,17 @@ function normalizePrefix(value: string): string {
 
 export const BASE_URL = normalizePrefix(import.meta.env?.BASE_URL || '/');
 
-export const DOCS_PREFIX = normalizePrefix(shiso.docsPrefix ?? '/docs');
+export const DOCS_PREFIX = shiso.docsPrefix;
 
 /** Content directory, relative to the project root, without leading/trailing slashes. */
-export const CONTENT_DIR = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+export const CONTENT_DIR = shiso.contentDir;
+
+/** Fixed root for standalone (non-docs) page files. Not configurable, so page
+ * slugs can never collide with the docs content tree. */
+export const PAGES_DIR = 'content/pages';
 
 /** Absolute origin used for canonical and og:url tags. Undefined when unconfigured. */
-export const SITE_URL = shiso.siteUrl?.replace(/\/+$/, '') || undefined;
+export const SITE_URL = shiso.siteUrl;
 
 /** Joins path segments with exactly one slash between them. */
 export function joinPath(...parts: (string | undefined)[]): string {

package/src/lib/site-config.ts

@@ -1,5 +1,6 @@
+import shisoConfig from 'virtual:shiso-config';
 import rawConfig from 'virtual:shiso-docs-config';
-import { resolveDocFile } from '@/lib/content';
+import { resolveDocFile, resolvePageFile } from '@/lib/content';
 import {
   assertDocsConfig,
   getDefaultScope,
@@ -8,8 +9,9 @@ import {
   normalizeDocsSite,
 } from '@/lib/docs-config';
 import { getTextDirection, resolveLocale } from '@/lib/locale';
-import { stripBase } from '@/lib/paths';
+import { DOCS_PREFIX, stripBase } from '@/lib/paths';
 import { resolveSiteModel } from '@/lib/site-model';
+import { getStandalonePageByPathname, normalizeStandalonePages } from '@/lib/standalone-pages';
 import type {
   DocsConfig,
   DocsScope,
@@ -18,6 +20,7 @@ import type {
   NormalizedDocsSite,
   RedirectRule,
   SeoConfig,
+  StandalonePage,
 } from '@/lib/types';
 
 assertDocsConfig(rawConfig, 'docs.json');
@@ -33,7 +36,22 @@ export const docsConfig: NormalizedDocsConfig = getDefaultScope(docsSite).docs;
 /** Landing page of the default scope: the site-wide "docs home" URL. */
 export const docsHomeUrl = getDefaultScope(docsSite).firstPageUrl;
 
-export const siteModel = resolveSiteModel(siteConfig, docsConfig);
+export const siteModel = resolveSiteModel(siteConfig, docsConfig, shisoConfig);
+
+/** Standalone pages declared with the top-level `pages` key, e.g. a home page. */
+export const standalonePages: StandalonePage[] = normalizeStandalonePages(
+  siteConfig,
+  resolvePageFile,
+  docsSite,
+  { docsPrefix: DOCS_PREFIX },
+);
+
+/** True when a standalone page owns "/", replacing the root docs redirect. */
+export const hasRootStandalonePage = standalonePages.some(page => page.path === '/');
+
+export function getStandalonePage(pathname: string): StandalonePage | null {
+  return getStandalonePageByPathname(standalonePages, stripBase(pathname));
+}
 
 /** Scope that owns the current pathname; the default scope for unknown paths. */
 export function getScopeByPathname(pathname: string): DocsScope {

package/src/lib/site-model.ts

@@ -12,6 +12,7 @@ import type {
   NormalizedLink,
   NormalizedNavbar,
   ResolvedContextualOption,
+  ResolvedShisoConfig,
   SiteModel,
   ThemeLabels,
 } from '@/lib/types';
@@ -90,7 +91,11 @@ function normalizeFooter(config: DocsConfig['footer']): NormalizedFooter | null
   return socials.length || links.length || attribution ? { socials, links, attribution } : null;
 }
 
-export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig): SiteModel {
+export function resolveSiteModel(
+  config: DocsConfig,
+  docs: NormalizedDocsConfig,
+  shiso?: ResolvedShisoConfig,
+): SiteModel {
   const appearance = config.appearance || {};
   const logo = config.logo
     ? typeof config.logo === 'string'
@@ -128,7 +133,7 @@ export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig)
     error404: { ...config.errors?.['404'], redirect: config.errors?.['404']?.redirect !== false },
     showTimestamp: config.metadata?.timestamp === true,
     drilldown: config.interaction?.drilldown,
-    locale: config.$shiso?.locale?.trim() || 'en-US',
+    locale: shiso?.locale || 'en-US',
     labels: SHISO_THEME_LABELS,
     docs,
   };

package/src/lib/standalone-pages.ts

@@ -0,0 +1,129 @@
+import type { DocsConfig, NormalizedDocsSite, StandalonePage } from '@/lib/types';
+
+/**
+ * Standalone pages: routes outside the docs navigation, declared with the
+ * top-level `pages` key in docs.json. They render with the site chrome
+ * (banner, header, footer) but no sidebar or table of contents, and a
+ * `path: "/"` entry replaces the default root redirect to the docs home.
+ */
+
+export interface NormalizeStandaloneOptions {
+  /** Docs prefix ("" or "/prefix"); standalone paths may not live under it. */
+  docsPrefix?: string;
+}
+
+function invalid(message: string): Error {
+  return new Error(`Invalid docs config: ${message}`);
+}
+
+/** Trims and canonicalizes a standalone route path; throws when malformed. */
+function normalizePath(rawPath: unknown): string {
+  const value = typeof rawPath === 'string' ? rawPath.trim() : '';
+
+  if (!value.startsWith('/')) {
+    throw invalid(`standalone page path "${String(rawPath)}" must start with "/".`);
+  }
+
+  if (/[:*]/.test(value)) {
+    throw invalid(`standalone page path "${value}" must not use wildcard patterns.`);
+  }
+
+  if (/\.mdx?$/i.test(value)) {
+    throw invalid(
+      `standalone page path "${value}" must be a route, not a file — drop the extension.`,
+    );
+  }
+
+  const collapsed = value.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+  return collapsed || '/';
+}
+
+/** Mirrors normalizePageReference in docs-config.ts for the `page` slug. */
+function normalizePageSlug(rawSlug: unknown): string {
+  const value = typeof rawSlug === 'string' ? rawSlug : '';
+
+  return (
+    value
+      .trim()
+      .replace(/\\/g, '/')
+      .replace(/^\/+/, '')
+      .replace(/^pages\//, '')
+      .replace(/\.mdx?$/, '')
+      .replace(/\/+$/, '') || 'index'
+  );
+}
+
+export function normalizeStandalonePages(
+  config: DocsConfig,
+  resolvePageFile: (fileSlug: string) => string | undefined,
+  site: NormalizedDocsSite,
+  options: NormalizeStandaloneOptions = {},
+): StandalonePage[] {
+  const items = config.pages || [];
+
+  if (!items.length) {
+    return [];
+  }
+
+  const docsPrefix = options.docsPrefix || '';
+  const pages: StandalonePage[] = [];
+  const seen = new Set<string>();
+
+  for (const item of items) {
+    const path = normalizePath(item?.path);
+
+    if (seen.has(path)) {
+      throw invalid(`duplicate standalone page path "${path}".`);
+    }
+
+    seen.add(path);
+
+    if (path === '/404') {
+      throw invalid('standalone page path "/404" is reserved for the error page.');
+    }
+
+    const docsPage = site.pageByUrl[path];
+
+    if (docsPage) {
+      throw invalid(
+        `standalone page path "${path}" collides with the docs page "${docsPage.fileSlug}". ` +
+          'Standalone pages must live outside the docs navigation.',
+      );
+    }
+
+    if (docsPrefix && (path === docsPrefix || path.startsWith(`${docsPrefix}/`))) {
+      throw invalid(
+        `standalone page path "${path}" is inside the docs prefix "${docsPrefix}". ` +
+          'Standalone pages must live outside the docs tree.',
+      );
+    }
+
+    const fileSlug = normalizePageSlug(item?.page);
+    const filePath = resolvePageFile(fileSlug);
+
+    if (!filePath) {
+      throw new Error(
+        `Missing standalone page file for "${fileSlug}": expected ` +
+          `"content/pages/${fileSlug}.mdx" or ".md".`,
+      );
+    }
+
+    pages.push({ path, filePath, title: item?.title?.trim() || undefined });
+  }
+
+  return pages;
+}
+
+/**
+ * Exact standalone page lookup by base-relative pathname. Tolerates trailing
+ * slashes and an explicit `/index` suffix, like getPageByPathname.
+ */
+export function getStandalonePageByPathname(
+  pages: StandalonePage[],
+  pathname: string,
+): StandalonePage | null {
+  const trimmed = pathname.replace(/\/+$/, '') || '/';
+  const collapsed = trimmed === '/index' ? '/' : trimmed.replace(/\/index$/, '') || '/';
+
+  return pages.find(page => page.path === trimmed || page.path === collapsed) || null;
+}

package/src/lib/types.ts

@@ -101,8 +101,9 @@ export type LogoOption =
   | string
   | { light?: string; dark?: string; href?: string; target?: LinkTarget };
 
-/** Shiso-only configuration. Namespaced so docs.json stays portable. */
-export interface ShisoOptions {
+/** Project-level settings supplied by shiso.config.ts. Mirrors the public
+ * shape exported from "@umami/shiso/config". */
+export interface ShisoConfig {
   /** Where docs pages are mounted within the site. Default "/docs"; "" for root. */
   docsPrefix?: string;
   /** Content directory relative to the project root. Default "content/docs". */
@@ -113,6 +114,14 @@ export interface ShisoOptions {
   locale?: string;
 }
 
+/** ShisoConfig after defaults and normalization, as served by `virtual:shiso-config`. */
+export interface ResolvedShisoConfig {
+  docsPrefix: string;
+  contentDir: string;
+  siteUrl?: string;
+  locale: string;
+}
+
 export type LinkTarget = '_self' | '_blank';
 
 /** A user-configured link. Presentation is determined entirely by its fields. */
@@ -166,6 +175,26 @@ export interface RedirectRule {
   destination: string;
 }
 
+/** A standalone page outside the docs navigation, e.g. a landing page. */
+export interface StandalonePageItem {
+  /** Route path, starting with "/". "/" replaces the root redirect to docs. */
+  path: string;
+  /** File slug under content/pages, e.g. "home" for content/pages/home.mdx. */
+  page: string;
+  /** Page title used in the document head. Frontmatter title wins. */
+  title?: string;
+}
+
+/** Normalized standalone page. */
+export interface StandalonePage {
+  /** Base-relative route, e.g. "/" or "/about". */
+  path: string;
+  /** Module key of the MDX file, e.g. "/content/pages/home.mdx". */
+  filePath: string;
+  /** Config-level head-title override. */
+  title?: string;
+}
+
 export interface SeoConfig {
   /** Extra meta tags added to every page, e.g. { "og:image": "/social.png" }. */
   metatags?: Record<string, string>;
@@ -271,7 +300,6 @@ export interface BackgroundConfig {
 
 export interface DocsConfig {
   $schema?: string;
-  $shiso?: ShisoOptions;
   theme?: string;
   name?: string;
   colors?: ThemeColors;
@@ -279,6 +307,8 @@ export interface DocsConfig {
   favicon?: string;
   description?: string;
   navigation: NavigationConfig;
+  /** Standalone pages outside the docs navigation, e.g. a landing page at "/". */
+  pages?: StandalonePageItem[];
   navbar?: NavbarConfig;
   footer?: FooterConfig;
   banner?: BannerConfig;

package/src/pages/StandalonePage.tsx

@@ -0,0 +1,42 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+import { Docs } from '@/components/Docs';
+import { Footer } from '@/components/Footer';
+import { getDocModule } from '@/lib/content';
+import type { SiteModel, StandalonePage } from '@/lib/types';
+
+/**
+ * A standalone (non-docs) page: site chrome from Layout (banner, header),
+ * the MDX content at full container width — no sidebar, TOC, or pager — and
+ * the footer. MDX components come from the app-level MDXProvider.
+ */
+export function StandalonePageView({ page, site }: { page: StandalonePage; site: SiteModel }) {
+  const { pathname } = useLocation();
+  const doc = getDocModule(page.filePath);
+
+  // Start each newly loaded page at the top, like Docs does for docs routes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname is the trigger
+  useEffect(() => {
+    if (!window.location.hash) {
+      window.scrollTo({ top: 0, left: 0 });
+    }
+  }, [pathname]);
+
+  // Normalization guarantees the file exists; this is a build-drift safety net.
+  if (!doc) {
+    return <Docs page={null} doc={null} site={site} />;
+  }
+
+  const Content = doc.default;
+
+  return (
+    <div className="flex min-h-full flex-col">
+      <article className="grow py-8">
+        <div className="docs-markdown">
+          <Content />
+        </div>
+      </article>
+      <Footer footer={site.footer} />
+    </div>
+  );
+}

package/src/styles/global.css

@@ -60,10 +60,17 @@
 /* Markdown content */
 
 @layer components {
+  /* Body copy is muted; headings, bold text, links, and inline code stay at
+     full foreground brightness so they stand out against the running text. */
   .docs-markdown {
     margin-bottom: 2.5rem;
     font-size: 16px;
     line-height: 1.75;
+    color: color-mix(in srgb, var(--foreground) 40%, var(--muted-foreground));
+  }
+
+  [data-theme="dark"] .docs-markdown {
+    color: color-mix(in srgb, var(--foreground) 25%, var(--muted-foreground));
   }
 
   .docs-markdown > * + * {
@@ -72,7 +79,7 @@
 
   .docs-markdown :where(h2, h3, h4, h5, h6) {
     font-family: var(--font-heading);
-    font-weight: var(--font-heading-weight, 700);
+    font-weight: var(--font-heading-weight, 600);
     letter-spacing: -0.02em;
     line-height: 1.25;
     color: var(--foreground);
@@ -129,7 +136,13 @@
     margin: 0.35rem 0;
   }
 
+  .docs-markdown :where(strong, b) {
+    color: var(--foreground);
+    font-weight: 600;
+  }
+
   .docs-markdown a {
+    color: var(--foreground);
     text-decoration: underline;
     text-decoration-color: color-mix(in srgb, currentColor 30%, transparent);
     text-underline-offset: 0.2em;
@@ -140,6 +153,7 @@
   }
 
   .docs-markdown code:not(pre code) {
+    color: var(--foreground);
     border-radius: var(--radius-sm);
     background: color-mix(in srgb, currentColor 4%, transparent);
     padding: 0.1rem 0.3rem;
@@ -158,6 +172,10 @@
     border-radius: var(--radius-lg);
   }
 
+  .docs-markdown th {
+    color: var(--foreground);
+  }
+
   .docs-markdown th,
   .docs-markdown td {
     border: none;

package/src/styles/tokens.css

@@ -40,7 +40,7 @@
 }
 
 :root {
-  --font-sans: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-sans: "Inter Variable", system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
   --font-heading: var(--font-sans);
   --header-height: 3rem;

package/types/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public types for shiso.config.ts. Kept self-contained (no imports) so the
+ * config file typechecks in consuming projects without pulling in the runtime.
+ */
+
+/** Project-level settings supplied by shiso.config.ts. All fields are optional. */
+export interface ShisoConfig {
+  /** Route prefix for docs pages within the site. Default "/docs"; "" serves docs at the site root. */
+  docsPrefix?: string;
+  /** Content directory relative to the project root. Default "content/docs". */
+  contentDir?: string;
+  /** Absolute site origin (e.g. "https://docs.example.com") used for canonical URLs, og:url, and the sitemap. */
+  siteUrl?: string;
+  /** Locale used for deterministic date formatting. Default "en-US". */
+  locale?: string;
+}
+
+/** Identity helper that types a shiso.config.ts default export. */
+export declare function defineConfig(config: ShisoConfig): ShisoConfig;

package/vite.config.ts

@@ -9,7 +9,7 @@ import { generateIconRegistry } from './scripts/generate-icon-registry.mjs';
 import { shisoLastModified } from './scripts/generate-last-modified.mjs';
 import { generateSearchIndex } from './scripts/generate-search-index.mjs';
 import { createDocsConfigModule } from './scripts/vite-docs-config.mjs';
-import type { DocsConfig } from './src/lib/types.ts';
+import type { DocsConfig, ResolvedShisoConfig } from './src/lib/types.ts';
 
 /**
  * Keeps src/lib/icon-registry.generated.ts in sync with the `icon="name"` values
@@ -37,15 +37,25 @@ function shisoIconRegistry(getDocsConfig: () => DocsConfig, root: string, output
  * Keeps src/lib/search-index.generated.ts in sync with content, so the search
  * dialog can query page text without a server.
  */
-function shisoSearchIndex(getDocsConfig: () => DocsConfig, root: string, output: string): Plugin {
+function shisoSearchIndex(
+  getDocsConfig: () => DocsConfig,
+  getShisoConfig: () => ResolvedShisoConfig,
+  root: string,
+  output: string,
+): Plugin {
   return {
     name: 'shiso-search-index',
     async buildStart() {
-      await generateSearchIndex({ config: getDocsConfig(), root, output });
+      await generateSearchIndex({ config: getDocsConfig(), shiso: getShisoConfig(), root, output });
     },
     async handleHotUpdate({ file }) {
-      if (/\.(md|mdx)$/.test(file) || file.endsWith('docs.json')) {
-        await generateSearchIndex({ config: getDocsConfig(), root, output });
+      if (/\.(md|mdx)$/.test(file) || file.endsWith('docs.json') || /shiso\.config\.\w+$/.test(file)) {
+        await generateSearchIndex({
+          config: getDocsConfig(),
+          shiso: getShisoConfig(),
+          root,
+          output,
+        });
       }
     },
   };
@@ -288,7 +298,11 @@ function shisoHtml(getDocsConfig: () => DocsConfig): Plugin {
  * production builds. The contextual menu's copy/view options and AI links
  * depend on these URLs.
  */
-function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin {
+function shisoMarkdownDev(
+  getDocsConfig: () => DocsConfig,
+  getShisoConfig: () => ResolvedShisoConfig,
+  root: string,
+): Plugin {
   return {
     name: 'shiso-markdown-dev',
     apply: 'serve',
@@ -300,17 +314,8 @@ function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin
           return next();
         }
 
-        const shiso =
-          (getDocsConfig() as { $shiso?: { docsPrefix?: string; contentDir?: string } }).$shiso ||
-          {};
-        const contentDir = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
-        const prefixValue = (shiso.docsPrefix ?? '/docs').trim().replace(/\/+$/, '');
-        const docsPrefix =
-          !prefixValue || prefixValue === '/'
-            ? ''
-            : prefixValue.startsWith('/')
-              ? prefixValue
-              : `/${prefixValue}`;
+        // Values arrive with defaults applied and already normalized.
+        const { contentDir, docsPrefix } = getShisoConfig();
 
         let route = decodeURIComponent(url).slice(0, -'.md'.length);
         const base = server.config.base.replace(/\/+$/, '');
@@ -319,6 +324,39 @@ function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin
           route = route.slice(base.length);
         }
 
+        // Standalone pages (top-level `pages` key) live under content/pages,
+        // outside the docs prefix. "/index.md" maps to the "/" entry.
+        const routeKey = (route.replace(/\/+$/, '') || '/').replace(/^\/index$/, '/');
+        const standalone = (getDocsConfig().pages || []).find(
+          item => (item?.path?.trim().replace(/\/+$/, '') || '/') === routeKey,
+        );
+
+        if (standalone?.page) {
+          const pagesRoot = path.resolve(root, 'content/pages');
+          const pageSlug = standalone.page
+            .trim()
+            .replace(/^\/+/, '')
+            .replace(/\.mdx?$/, '');
+
+          for (const candidate of [`${pageSlug}.mdx`, `${pageSlug}.md`]) {
+            const filePath = path.resolve(pagesRoot, candidate);
+
+            // Never read outside the pages directory.
+            if (!filePath.startsWith(pagesRoot + path.sep)) {
+              break;
+            }
+
+            try {
+              const source = await readFile(filePath, 'utf8');
+              res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+              res.end(source);
+              return;
+            } catch {
+              // Try the next candidate.
+            }
+          }
+        }
+
         if (docsPrefix && route.startsWith(docsPrefix)) {
           route = route.slice(docsPrefix.length);
         }
@@ -364,6 +402,7 @@ export default defineConfig(async () => {
     root: projectRoot,
   });
   const getDocsConfig = configModule.getConfig as () => DocsConfig;
+  const getShisoConfig = configModule.getShisoConfig as () => ResolvedShisoConfig;
 
   return {
     optimizeDeps: {
@@ -385,11 +424,12 @@ export default defineConfig(async () => {
       }),
       shisoSearchIndex(
         getDocsConfig,
+        getShisoConfig,
         projectRoot,
         path.join(generatedRoot, 'search-index.generated.ts'),
       ),
       shisoHtml(getDocsConfig),
-      shisoMarkdownDev(getDocsConfig, projectRoot),
+      shisoMarkdownDev(getDocsConfig, getShisoConfig, projectRoot),
       shisoMdx(),
       react({ include: /\.(mdx|md|tsx|ts|jsx|js)$/ }),
     ],