npm - create-eziwiki - Versions diffs - 0.3.0 → 0.4.0 - Mend

create-eziwiki 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/package.json +1 -1
package/template/app/[...slug]/page.tsx +3 -0
package/template/app/layout.tsx +4 -1
package/template/app/sitemap.ts +21 -1
package/template/app/tags/[[...tag]]/page.tsx +139 -0
package/template/components/layout/PageTags.tsx +32 -0
package/template/components/layout/TabBar.tsx +1 -1
package/template/lib/content/registry.ts +43 -0
package/template/lib/content/tags.test.ts +93 -0
package/template/lib/content/tags.ts +139 -0
package/template/lib/payload/schema.ts +1 -0
package/template/lib/payload/types.ts +8 -0
package/template/styles/markdown.css +4 -1

package/package.json CHANGED Viewed

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

package/template/app/[...slug]/page.tsx CHANGED Viewed

@@ -4,10 +4,12 @@ import { TableOfContents } from '@/components/layout/TableOfContents';
 import { Backlinks } from '@/components/layout/Backlinks';
 import { LocalGraph } from '@/components/layout/LocalGraph';
 import { PageNavigation } from '@/components/layout/PageNavigation';
+import { PageTags } from '@/components/layout/PageTags';
 import { MovedPage } from '@/components/layout/MovedPage';
 import { getBacklinks, getLocalGraph } from '@/lib/graph/build';
 import { getAdjacentPages } from '@/lib/navigation/sequence';
 import { getAliasMap, aliasUrl, resolveAliasUrl } from '@/lib/content/aliases';
+import { getTagsFor } from '@/lib/content/tags';
 import { renderDoc } from '@/lib/markdown/render';
 import { getDoc, type ContentDoc } from '@/lib/content/registry';
 import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
@@ -201,6 +203,7 @@ export default async function ContentPage({ params }: PageProps) {
       <div className="flex gap-8">
         <article className="prose prose-slate min-w-0 max-w-none flex-1 dark:prose-invert">
           <ArticleSchema doc={doc} url={resolved.url} />
+          <PageTags tags={getTagsFor(resolved.path)} />
           <MarkdownContent html={rendered.html} />
           <PageNavigation adjacent={getAdjacentPages(resolved.path)} />
           <Backlinks links={getBacklinks(resolved.path)} />

package/template/app/layout.tsx CHANGED Viewed

@@ -130,12 +130,15 @@ const fontFaceCss = FONT_FACES.map(
     `unicode-range:${RANGES[font.subset]}}`,
 ).join('');
+/** Language announced when the payload names none. */
+const DEFAULT_LANG = 'en';
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   const site = getSite();
   const homeUrl = pageUrl('', site.global.baseUrl);
   return (
-    <html lang="en">
+    <html lang={site.global.lang ?? DEFAULT_LANG}>
       <head>
         {FONT_FACES.filter((font) => font.preload).map((font) => (
           <link

package/template/app/sitemap.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import { MetadataRoute } from 'next';
 import { getSite } from '@/lib/site';
 import { docPathToUrl } from '@/lib/navigation/url';
 import { pageUrl } from '@/lib/basePath';
+import { getTags } from '@/lib/content/tags';
 /**
  * Generates the sitemap for every published page.
@@ -44,5 +45,24 @@ export default function sitemap(): MetadataRoute.Sitemap {
     ];
   });
-  return [homeEntry, ...contentEntries];
+  // Tag pages are indexable and canonical, so leaving them out of the sitemap
+  // said one thing to a crawler following links and another to one reading
+  // this. The index is listed even when empty; a tag page only exists when
+  // something carries it.
+  const tagEntries: MetadataRoute.Sitemap = [
+    {
+      url: pageUrl('tags', global.baseUrl),
+      lastModified,
+      changeFrequency: 'weekly',
+      priority: 0.4,
+    },
+    ...getTags().map((tag) => ({
+      url: pageUrl(`tags/${tag.slug}`, global.baseUrl),
+      lastModified,
+      changeFrequency: 'weekly' as const,
+      priority: 0.4,
+    })),
+  ];
+  return [homeEntry, ...contentEntries, ...tagEntries];
 }

package/template/app/tags/[[...tag]]/page.tsx ADDED Viewed

@@ -0,0 +1,139 @@
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { getTag, getTags, type Tag } from '@/lib/content/tags';
+import { getSite } from '@/lib/site';
+import { pageUrl } from '@/lib/basePath';
+interface PageProps {
+  params: { tag?: string[] };
+}
+/**
+ * The tag index and every tag, served by one route.
+ *
+ * An optional catch-all rather than two routes because a static export refuses
+ * a dynamic segment whose `generateStaticParams` comes back empty — which is
+ * exactly what a new wiki has, before anyone has written a tag. Folded together,
+ * the index is always one of the params and the build has something to make.
+ */
+export async function generateStaticParams() {
+  return [{ tag: [] as string[] }, ...getTags().map((tag) => ({ tag: [tag.slug] }))];
+}
+/** The tag a route names, or null when the route is the index. */
+function resolveTag(params: PageProps['params']): Tag | null {
+  const [slug] = params.tag ?? [];
+  return slug ? getTag(slug) : null;
+}
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { global } = getSite();
+  const [slug] = params.tag ?? [];
+  if (!slug) {
+    return {
+      title: 'Tags',
+      description: 'Subjects across the wiki',
+      alternates: { canonical: pageUrl('tags', global.baseUrl) },
+    };
+  }
+  const tag = getTag(slug);
+  if (!tag) return { title: 'Tag', description: global.description };
+  return {
+    title: tag.name,
+    description: `Pages about ${tag.name}`,
+    alternates: { canonical: pageUrl(`tags/${tag.slug}`, global.baseUrl) },
+  };
+}
+/**
+ * Lists every subject, or the pages about one.
+ *
+ * The sidebar shows one arrangement — the folder tree — and this shows the
+ * other. A page belongs to one section and to as many subjects as it touches,
+ * and only this view can say so.
+ */
+export default function TagsPage({ params }: PageProps) {
+  const [slug] = params.tag ?? [];
+  if (slug) {
+    const tag = resolveTag(params);
+    if (!tag) notFound();
+    return (
+      <div className="mx-auto max-w-3xl px-6 py-10">
+        <Link
+          href="/tags/"
+          className="text-xs uppercase tracking-wide text-gray-500 no-underline hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+        >
+          Tags
+        </Link>
+        <h1 className="mt-2 text-2xl font-semibold text-gray-900 dark:text-gray-100">{tag.name}</h1>
+        <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+          {tag.pages.length} {tag.pages.length === 1 ? 'page' : 'pages'}
+        </p>
+        <ul className="mt-6 space-y-3">
+          {tag.pages.map((page) => (
+            <li key={page.path}>
+              <Link
+                href={page.url}
+                className="block rounded-lg border border-gray-200 p-4 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+              >
+                <span className="block text-sm font-medium text-gray-900 dark:text-gray-100">
+                  {page.title}
+                </span>
+                {page.description && (
+                  <span className="mt-1 block text-sm text-gray-600 dark:text-gray-400">
+                    {page.description}
+                  </span>
+                )}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+  const tags = getTags();
+  return (
+    <div className="mx-auto max-w-3xl px-6 py-10">
+      <h1 className="text-2xl font-semibold text-gray-900 dark:text-gray-100">Tags</h1>
+      {tags.length === 0 ? (
+        <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+          No tags yet. Add <code>tags</code> to a page&rsquo;s frontmatter and it will appear here.
+        </p>
+      ) : (
+        <>
+          <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+            {tags.length} {tags.length === 1 ? 'subject' : 'subjects'} across the wiki.
+          </p>
+          <ul className="mt-6 flex flex-wrap gap-2">
+            {tags.map((tag) => (
+              <li key={tag.slug}>
+                <Link
+                  href={`/tags/${encodeURIComponent(tag.slug)}/`}
+                  className="inline-flex items-baseline gap-1.5 rounded-md border border-gray-200 px-3 py-1.5 text-sm text-gray-700 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:text-gray-300 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+                >
+                  {tag.name}
+                  <span className="text-xs text-gray-500 dark:text-gray-400">
+                    {tag.pages.length}
+                  </span>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+    </div>
+  );
+}

package/template/components/layout/PageTags.tsx ADDED Viewed

@@ -0,0 +1,32 @@
+import Link from 'next/link';
+import { Tag as TagIcon } from 'lucide-react';
+import type { Tag } from '@/lib/content/tags';
+/**
+ * Shows the subjects a page belongs to.
+ *
+ * Placed at the top of the article rather than the foot: knowing what a page is
+ * about is useful before reading it, and it is the one piece of navigation the
+ * sidebar cannot express, since a file sits in exactly one folder.
+ *
+ * @param props - Component props
+ * @param props.tags - Tags on the page, from `getTagsFor()`
+ */
+export function PageTags({ tags }: { tags: Tag[] }) {
+  if (tags.length === 0) return null;
+  return (
+    <nav aria-label="Tags" className="mb-6 flex flex-wrap items-center gap-2">
+      <TagIcon className="h-3.5 w-3.5 flex-shrink-0 text-gray-400" aria-hidden="true" />
+      {tags.map((tag) => (
+        <Link
+          key={tag.slug}
+          href={`/tags/${encodeURIComponent(tag.slug)}/`}
+          className="rounded-md bg-gray-100 px-2 py-0.5 text-xs text-gray-700 no-underline transition-colors hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+        >
+          {tag.name}
+        </Link>
+      ))}
+    </nav>
+  );
+}

package/template/components/layout/TabBar.tsx CHANGED Viewed

@@ -210,7 +210,7 @@ export function TabBar() {
               <button
                 onClick={(e) => handleTabClose(e, tab.id)}
                 className={`
-                  flex-shrink-0 w-5 h-5 min-w-[20px] min-h-[20px] flex items-center justify-center rounded hover:bg-gray-200 dark:hover:bg-gray-600
+                  flex-shrink-0 w-5 h-5 min-w-[20px] min-h-[20px] max-md:w-6 max-md:h-6 max-md:min-w-[24px] max-md:min-h-[24px] flex items-center justify-center rounded hover:bg-gray-200 dark:hover:bg-gray-600
                   transition-opacity
                   ${isActive ? 'opacity-100' : 'opacity-0 group-hover:opacity-100'}
                 `}

package/template/lib/content/registry.ts CHANGED Viewed

@@ -25,6 +25,14 @@ export interface ContentDoc {
   order: number;
   /** Excluded from navigation, but still reachable by direct URL */
   hidden: boolean;
+  /**
+   * Labels grouping this document with others across the folder tree.
+   *
+   * A file sits in exactly one directory, so the sidebar can only express one
+   * way of organising a wiki. Tags are the second axis: a page belongs to one
+   * section and to as many subjects as it touches.
+   */
+  tags: string[];
   /**
    * Paths this document used to live at.
    *
@@ -114,6 +122,40 @@ function readBoolean(value: unknown): boolean {
   return false;
 }
+/**
+ * Reads the `tags` frontmatter.
+ *
+ * Accepts a single tag or a list, and a comma-separated string, because all
+ * three are how people write this and none of them is wrong. Tags are compared
+ * case-insensitively — `Setup` and `setup` are one subject, and treating them
+ * as two would split a wiki quietly — but the first spelling seen is the one
+ * displayed.
+ *
+ * @param value - The raw frontmatter value
+ * @returns Tags in the order written, without duplicates
+ */
+function readTags(value: unknown): string[] {
+  const raw = typeof value === 'string' ? value.split(',') : Array.isArray(value) ? value : [];
+  const seen = new Set<string>();
+  const tags: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'string') continue;
+    const tag = entry.trim();
+    if (!tag) continue;
+    const key = tag.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    tags.push(tag);
+  }
+  return tags;
+}
 /**
  * Reads the `aliases` frontmatter into a list of content paths.
  *
@@ -228,6 +270,7 @@ function readDoc(filePath: string): ContentDoc | null {
     description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
     order: readOrder(frontmatter.order),
     hidden: readBoolean(frontmatter.hidden) || frontmatter.nav === false,
+    tags: readTags(frontmatter.tags),
     aliases: readAliases(frontmatter.aliases),
     frontmatter,
     content,

package/template/lib/content/tags.test.ts ADDED Viewed

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { getTags, getTag, getTagsFor, findTagRouteCollisions } from './tags';
+import { getContentRegistry } from './registry';
+import { getSite } from '../site';
+describe('getTags', () => {
+  it('gathers pages by subject across the folder tree', () => {
+    for (const tag of getTags()) {
+      expect(tag.pages.length).toBeGreaterThan(0);
+      expect(tag.slug).toBe(tag.name.toLowerCase());
+    }
+  });
+  it('sorts subjects by name', () => {
+    const names = getTags().map((tag) => tag.name);
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+  });
+  // A page kept off the sidebar on purpose should not reappear here, or the
+  // tag index becomes a way of enumerating exactly what was unlisted.
+  it('leaves hidden pages out', () => {
+    const { hiddenPaths } = getSite();
+    const listed = getTags().flatMap((tag) => tag.pages.map((page) => page.path));
+    for (const hidden of hiddenPaths) {
+      expect(listed).not.toContain(hidden);
+    }
+  });
+  it('emits URLs in the form the export serves', () => {
+    for (const tag of getTags()) {
+      for (const page of tag.pages) {
+        expect(page.url).toMatch(/^\/.*\/$/);
+      }
+    }
+  });
+  it('lists a page under each of its tags', () => {
+    const { docs } = getContentRegistry();
+    const { hiddenPaths } = getSite();
+    for (const doc of docs) {
+      if (hiddenPaths.has(doc.path) || doc.tags.length === 0) continue;
+      for (const name of doc.tags) {
+        const tag = getTag(name.toLowerCase());
+        expect(tag?.pages.some((page) => page.path === doc.path)).toBe(true);
+      }
+    }
+  });
+});
+describe('getTag', () => {
+  it('finds a subject however its name is cased', () => {
+    const [first] = getTags();
+    if (!first) return;
+    expect(getTag(first.slug)?.slug).toBe(first.slug);
+    expect(getTag(first.slug.toUpperCase())?.slug).toBe(first.slug);
+  });
+  it('finds nothing for a subject no page carries', () => {
+    expect(getTag('no-such-subject')).toBeNull();
+  });
+});
+describe('getTagsFor', () => {
+  it('returns the tags a page carries', () => {
+    const { docs } = getContentRegistry();
+    const { hiddenPaths } = getSite();
+    const tagged = docs.find((doc) => doc.tags.length > 0 && !hiddenPaths.has(doc.path));
+    if (!tagged) return;
+    expect(
+      getTagsFor(tagged.path)
+        .map((tag) => tag.slug)
+        .sort(),
+    ).toEqual(tagged.tags.map((tag) => tag.toLowerCase()).sort());
+  });
+  it('returns nothing for an untagged page', () => {
+    expect(getTagsFor('no/such/page')).toEqual([]);
+  });
+});
+// `/tags/…` is a route of its own and Next resolves it before the catch-all,
+// so a page published there would be unreachable.
+describe('findTagRouteCollisions', () => {
+  it('reports no collision in this wiki', () => {
+    expect(findTagRouteCollisions()).toEqual([]);
+  });
+});

package/template/lib/content/tags.ts ADDED Viewed

@@ -0,0 +1,139 @@
+import { getContentRegistry, type ContentDoc } from './registry';
+import { getSite } from '../site';
+import { docPathToUrl } from '../navigation/url';
+import { cached } from '../cache';
+/**
+ * Subjects, gathered across the folder tree.
+ *
+ * A file lives in one directory, so the sidebar can only ever show one way of
+ * organising a wiki. Tags are the other way: a page sits in one section and
+ * touches as many subjects as it touches. Where the graph says which pages
+ * mention each other, tags say which are about the same thing whether or not
+ * anyone thought to link them.
+ *
+ * Server-only: reads the content registry.
+ */
+/** Route segment the tag pages live under. */
+export const TAGS_SEGMENT = 'tags';
+/** A page carrying a tag. */
+export interface TaggedPage {
+  /** Content path */
+  path: string;
+  /** Display title */
+  title: string;
+  /** Href, in the site's configured URL form */
+  url: string;
+  /** Short summary, when the page has one */
+  description?: string;
+}
+/** A subject and the pages about it. */
+export interface Tag {
+  /** The tag as first written by an author */
+  name: string;
+  /** Lowercased form, used in URLs and for comparison */
+  slug: string;
+  /** Pages carrying it, in reading order */
+  pages: TaggedPage[];
+}
+let memo: Tag[] | null = null;
+/**
+ * Converts a page to the shape a listing needs.
+ */
+function toTaggedPage(doc: ContentDoc): TaggedPage | null {
+  const url = docPathToUrl(getSite().urlMap, doc.path);
+  if (!url) return null;
+  return { path: doc.path, title: doc.title, url: `/${url}/`, description: doc.description };
+}
+/**
+ * Collects every tag and the pages carrying it.
+ *
+ * Hidden pages are left out. A page kept off the sidebar on purpose should not
+ * reappear in a tag listing, which would make the tag index a way of
+ * enumerating exactly what was meant to stay unlisted.
+ *
+ * @returns Tags sorted by name, each with its pages
+ *
+ * @example
+ * ```typescript
+ * getTags().map((tag) => `${tag.name} (${tag.pages.length})`);
+ * ```
+ */
+export function getTags(): Tag[] {
+  const hit = cached(memo);
+  if (hit) return hit;
+  const { docs } = getContentRegistry();
+  const { hiddenPaths } = getSite();
+  const bySlug = new Map<string, Tag>();
+  for (const doc of docs) {
+    if (hiddenPaths.has(doc.path)) continue;
+    const page = toTaggedPage(doc);
+    if (!page) continue;
+    for (const name of doc.tags) {
+      const slug = name.toLowerCase();
+      const existing = bySlug.get(slug);
+      // The first spelling wins, so a wiki that writes `Setup` once and `setup`
+      // thereafter still shows one tag rather than two.
+      if (existing) existing.pages.push(page);
+      else bySlug.set(slug, { name, slug, pages: [page] });
+    }
+  }
+  memo = [...bySlug.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return memo;
+}
+/**
+ * Finds one tag by its slug.
+ *
+ * @param slug - Lowercased tag name from the URL
+ * @returns The tag, or null when nothing carries it
+ */
+export function getTag(slug: string): Tag | null {
+  const wanted = decodeURIComponent(slug).toLowerCase();
+  return getTags().find((tag) => tag.slug === wanted) ?? null;
+}
+/**
+ * Returns the tags on one page, in the order they were written.
+ *
+ * @param path - Content path
+ * @returns The page's tags, empty when it has none
+ */
+export function getTagsFor(path: string): Tag[] {
+  return getTags().filter((tag) => tag.pages.some((page) => page.path === path));
+}
+/**
+ * Reports a content page whose URL the tag routes would shadow.
+ *
+ * `/tags/…` is a route of its own, and Next resolves it before the catch-all
+ * that serves content, so a page published at that address would become
+ * unreachable. Surfacing it is better than letting a page quietly disappear;
+ * the fix is to rename the file or the directory.
+ *
+ * @returns Paths that collide, empty when none do
+ */
+export function findTagRouteCollisions(): string[] {
+  const { docs } = getContentRegistry();
+  const { urlMap } = getSite();
+  return docs
+    .filter((doc) => {
+      const url = docPathToUrl(urlMap, doc.path);
+      return url === TAGS_SEGMENT || url?.startsWith(`${TAGS_SEGMENT}/`);
+    })
+    .map((doc) => doc.path);
+}

package/template/lib/payload/schema.ts CHANGED Viewed

@@ -13,6 +13,7 @@ export const payloadSchema = {
         title: { type: 'string', minLength: 1 },
         description: { type: 'string', minLength: 1 },
         favicon: { type: 'string' },
+        lang: { type: 'string', minLength: 2 },
         baseUrl: { type: 'string', format: 'uri' },
         repoUrl: { type: 'string', format: 'uri' },
         urlStrategy: { type: 'string', enum: ['path', 'hash'] },

package/template/lib/payload/types.ts CHANGED Viewed

@@ -28,6 +28,14 @@ export interface GlobalConfig {
   description: string;
   /** Path to favicon */
   favicon?: string;
+  /**
+   * BCP 47 language tag for the content, e.g. `ko`, `ja`, `en-GB`.
+   *
+   * Announced on the root element. Screen readers pick pronunciation from it
+   * and translation tools decide what to offer, so a Korean wiki left at the
+   * `en` default is read aloud as English. Defaults to `en`.
+   */
+  lang?: string;
   /** Base URL for the site */
   baseUrl?: string;
   /**

package/template/styles/markdown.css CHANGED Viewed

@@ -366,10 +366,13 @@ details.ezw-callout:not([open]) > summary.ezw-callout__title {
 }
 /* A pointer is not always available. On touch the anchor is simply shown,
-   since there is no hover to reveal it with. */
+   since there is no hover to reveal it with, and padded out to a target a
+   finger can hit — the glyph stays the same size, the area around it grows. */
 @media (hover: none) {
   .ezw-heading__anchor {
     opacity: 0.5;
+    padding: 0 0.3em;
+    margin-left: 0.1em;
   }
 }