create-eziwiki 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eziwiki",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Scaffold a new eziwiki documentation site",
   "type": "module",
   "bin": {

package/template/app/globals.css

@@ -9,15 +9,19 @@
 @import '../styles/markdown.css';
 
 /*
- * `@font-face` for Pretendard and SUITE is declared in `app/layout.tsx`, not
- * here: the font URLs need the deployment base path prefixed, which a
- * stylesheet cannot read. See FONT_FACES there.
+ * `@font-face` for Pretendard is declared in `app/layout.tsx`, not here: the
+ * font URLs need the deployment base path prefixed, which a stylesheet cannot
+ * read. See FONT_FACES there, which also splits each weight by `unicode-range`
+ * so a page fetches only the character sets it uses.
  */
 
 body {
+  /* SUITE used to sit between Pretendard and the system stack. Pretendard
+     covers Latin and Korean, so nothing ever reached it except the emoji in
+     section names — which it has no glyphs for either, and which the platform
+     emoji font renders. It was 274 kB nobody saw. */
   font-family:
     'Pretendard',
-    'SUITE',
     -apple-system,
     BlinkMacSystemFont,
     'Segoe UI',

package/template/app/layout.tsx

@@ -74,6 +74,23 @@ export const metadata: Metadata = {
     : undefined,
 };
 
+/**
+ * Character ranges each font file covers.
+ *
+ * Pretendard carries the full Korean syllabary, which is most of its weight:
+ * one weight is 750 kB whole, 27 kB once the Hangul is taken out. Splitting it
+ * and declaring what each half covers lets the browser fetch only the halves a
+ * page actually uses — an English page never asks for the Korean file, and a
+ * Korean one pays for it once and keeps it, since `public/` is served
+ * immutable.
+ */
+const RANGES = {
+  latin:
+    'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,' +
+    'U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
+  korean: 'U+1100-11FF,U+3000-303F,U+3130-318F,U+A960-A97F,U+AC00-D7A3,U+D7B0-D7FF,U+FF00-FFEF',
+} as const;
+
 /**
  * Web fonts, declared here rather than in `globals.css`.
  *
@@ -83,31 +100,34 @@ export const metadata: Metadata = {
  * the declarations from here puts them through `asset()` like every other file
  * in `public/`.
  *
- * `preload` marks the weights the first paint needs; the rest load on demand.
+ * Only the Latin halves are preloaded. Preloading the Korean ones would undo
+ * the split by fetching them before anything has asked for a Korean glyph.
  */
-const FONT_FACES = [
-  { family: 'SUITE', weight: 400, file: '/fonts/SUITE/SUITE-Regular.woff2' },
-  { family: 'SUITE', weight: 600, file: '/fonts/SUITE/SUITE-SemiBold.woff2' },
-  { family: 'SUITE', weight: 700, file: '/fonts/SUITE/SUITE-Bold.woff2' },
-  {
-    family: 'Pretendard',
-    weight: 400,
-    file: '/fonts/Pretandard/Pretendard-Regular.woff2',
-    preload: true,
-  },
-  {
-    family: 'Pretendard',
-    weight: 600,
-    file: '/fonts/Pretandard/Pretendard-SemiBold.woff2',
-    preload: true,
-  },
-  { family: 'Pretendard', weight: 700, file: '/fonts/Pretandard/Pretendard-Bold.woff2' },
+interface FontFace {
+  weight: number;
+  subset: keyof typeof RANGES;
+  preload?: boolean;
+}
+
+const FONT_FACES: FontFace[] = [
+  { weight: 400, subset: 'latin', preload: true },
+  { weight: 400, subset: 'korean' },
+  { weight: 600, subset: 'latin', preload: true },
+  { weight: 600, subset: 'korean' },
+  { weight: 700, subset: 'latin' },
+  { weight: 700, subset: 'korean' },
 ];
 
+/** Where a weight-and-subset pair is served from. */
+function fontFile({ weight, subset }: FontFace): string {
+  return `/fonts/Pretendard/pretendard-${weight}-${subset}.woff2`;
+}
+
 const fontFaceCss = FONT_FACES.map(
-  ({ family, weight, file }) =>
-    `@font-face{font-family:'${family}';font-weight:${weight};` +
-    `src:url('${asset(file)}') format('woff2');font-display:swap}`,
+  (font) =>
+    `@font-face{font-family:'Pretendard';font-weight:${font.weight};` +
+    `src:url('${asset(fontFile(font))}') format('woff2');font-display:swap;` +
+    `unicode-range:${RANGES[font.subset]}}`,
 ).join('');
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -119,9 +139,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       <head>
         {FONT_FACES.filter((font) => font.preload).map((font) => (
           <link
-            key={font.file}
+            key={fontFile(font)}
             rel="preload"
-            href={asset(font.file)}
+            href={asset(fontFile(font))}
             as="font"
             type="font/woff2"
             crossOrigin="anonymous"

package/template/app/robots.ts

@@ -3,8 +3,17 @@ import { payload } from '@/payload/config';
 import { fileUrl } from '@/lib/basePath';
 
 /**
- * Generate robots.txt file
- * Controls how search engines crawl and index the site
+ * Generates robots.txt.
+ *
+ * Nothing is disallowed. Search engines render a page before judging it, so
+ * blocking `/_next/` — where the stylesheet and scripts live — leaves the
+ * crawler looking at an unstyled document and reporting the assets as blocked
+ * resources. There is no `/api/` either: the site is a static export.
+ *
+ * Pages that should stay out of the index carry `noindex` in their own
+ * metadata, which is the mechanism that actually keeps them out. A path
+ * disallowed here would still be indexable if something linked to it, since a
+ * crawler that is told not to fetch a page cannot read the `noindex` on it.
  *
  * @returns Robots configuration
  */
@@ -13,7 +22,6 @@ export default function robots(): MetadataRoute.Robots {
     rules: {
       userAgent: '*',
       allow: '/',
-      disallow: ['/api/', '/_next/'],
     },
     sitemap: fileUrl('/sitemap.xml', payload.global.baseUrl),
   };

package/template/components/search/SearchTrigger.tsx

@@ -22,17 +22,24 @@ export function SearchTrigger({ className = '' }: { className?: string }) {
   }, []);
 
   return (
+    // No aria-label: it read "Search documentation" while the control visibly
+    // says "Search…", so the spoken name did not contain the written one and
+    // voice control had nothing to match. The text names the button instead;
+    // the icon and the shortcut are hidden from the name, the latter because
+    // `aria-keyshortcuts` already announces it.
     <button
       type="button"
       onClick={open}
-      aria-label="Search documentation"
       aria-keyshortcuts="Meta+K Control+K"
-      className={`flex items-center gap-2 rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-400 transition-colors hover:border-gray-400 dark:border-gray-700 dark:bg-gray-800 dark:hover:border-gray-600 ${className}`}
+      className={`flex items-center gap-2 rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-500 transition-colors hover:border-gray-400 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:hover:border-gray-600 ${className}`}
     >
-      <Search className="h-4 w-4 flex-shrink-0" />
+      <Search className="h-4 w-4 flex-shrink-0" aria-hidden="true" />
       <span className="min-w-0 flex-1 truncate text-left">Search…</span>
       {shortcut && (
-        <kbd className="hidden flex-shrink-0 rounded border border-gray-300 px-1 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-600 dark:text-gray-400">
+        <kbd
+          aria-hidden="true"
+          className="hidden flex-shrink-0 rounded border border-gray-300 px-1 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-600 dark:text-gray-400"
+        >
           {shortcut}
         </kbd>
       )}

package/template/lib/markdown/rehype-plugins.ts

@@ -221,15 +221,32 @@ export function rehypeBasePath(basePath: string) {
 }
 
 /**
- * Adds lazy loading and consistent styling hooks to content images.
+ * Adds loading hints and consistent styling hooks to content images.
+ *
+ * Every image was deferred, including the first one. On a page that opens with
+ * a figure that image is what the browser measures as the largest contentful
+ * paint, and `loading="lazy"` keeps it out of the preload scan — the request
+ * only starts once layout has reached it, so the headline metric waits on a
+ * round trip that need not have been late. The first image is therefore
+ * fetched eagerly and marked high priority; the rest, which are further down,
+ * keep deferring.
  */
 export function rehypeImages() {
   return (tree: Root) => {
+    let seen = 0;
+
     visit(tree, 'element', (node: Element) => {
       if (node.tagName !== 'img') return;
 
       node.properties ??= {};
-      node.properties.loading ??= 'lazy';
+      const isFirst = seen++ === 0;
+
+      if (isFirst) {
+        node.properties.loading ??= 'eager';
+        node.properties.fetchPriority ??= 'high';
+      } else {
+        node.properties.loading ??= 'lazy';
+      }
       node.properties.decoding ??= 'async';
 
       const className = node.properties.className;

package/template/lib/markdown/render.ts

@@ -43,14 +43,32 @@ export interface RenderedMarkdown {
   headings: Heading[];
 }
 
-/** Syntax highlighting themes, applied as CSS variables for light and dark. */
-const SHIKI_THEMES = { light: 'github-light', dark: 'github-dark' } as const;
+/**
+ * Syntax highlighting themes, applied as CSS variables for light and dark.
+ *
+ * The high-contrast variants, because the plain ones are tuned for GitHub's
+ * near-white code background: against the slightly darker grey used here their
+ * strings, keywords and comments land between 4.15:1 and 4.37:1, under the
+ * 4.5:1 that body-sized text needs. Lightening the background would fix the
+ * ratios too, but a code block that matches the page around it stops reading
+ * as a code block.
+ */
+const SHIKI_THEMES = {
+  light: 'github-light-high-contrast',
+  dark: 'github-dark-high-contrast',
+} as const;
 
 let processor: Processor | null = null;
 
 /**
  * Resolves a wiki-link target to a destination in this site.
  *
+ * The trailing slash is applied here rather than downstream. Under the `path`
+ * strategy `rehypeInternalLinks` sees a content path it can resolve and adds
+ * one, but under `hash` the URL is already a digest, which does not map back
+ * to a document — so the link was left without it and every wiki link cost a
+ * redirect.
+ *
  * @param target - Raw target text from inside the brackets
  * @returns The destination, or null when the target does not resolve
  */
@@ -59,7 +77,7 @@ function resolveWikiLink(target: string): WikiLinkTarget | null {
   if (!doc) return null;
 
   const url = docPathToUrl(getUrlMap(), doc.path);
-  return url ? { url: `/${url}`, title: doc.title } : null;
+  return url ? { url: `/${url}/`, title: doc.title } : null;
 }
 
 /**

package/template/styles/markdown.css

@@ -31,14 +31,14 @@
   font-size: 0.75rem;
   text-transform: uppercase;
   letter-spacing: 0.03em;
-  color: var(--color-text-muted);
+  color: var(--color-code-muted);
 }
 
 .ezw-code__copy {
   font-size: 0.75rem;
   padding: 0.25rem 0.5rem;
   border-radius: 0.25rem;
-  color: var(--color-text-muted);
+  color: var(--color-code-muted);
   background: transparent;
   transition:
     color 0.15s ease,

package/template/styles/theme.css

@@ -28,6 +28,11 @@
   /* Code block colors */
   --color-code-bg: #f3f4f6;
   --color-code-text: #1f2937;
+  /* Secondary text inside a code block. Darker than --color-text-muted, which
+     reaches only 4.39:1 against the code background and so falls short of the
+     4.5:1 that the small type used for the language label and the copy button
+     needs. */
+  --color-code-muted: #4b5563;
 
   /* Border colors */
   --color-border: #e5e7eb;
@@ -59,6 +64,8 @@
   /* Code block colors */
   --color-code-bg: #374151;
   --color-code-text: #f9fafb;
+  /* See the light theme: the muted grey reaches only 4.06:1 here. */
+  --color-code-muted: #d1d5db;
 
   /* Border colors */
   --color-border: #374151;

package/template/vercel.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "headers": [
+    {
+      "source": "/fonts/(.*)",
+      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
+    },
+    {
+      "source": "/images/(.*)",
+      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
+    },
+    {
+      "source": "/(search-index.json|favicon.svg|og-image.svg)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "SAMEORIGIN" },
+        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
+        { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }
+      ]
+    }
+  ]
+}