@umami/shiso 1.4.0 → 1.5.0

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/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)$/ }),
     ],