livemark 0.14.0 → 0.16.0

package/source/content/article.ts

@@ -1,11 +1,7 @@
 import { config } from "livemark:virtual"
 import { allArticles } from "content-collections"
-import type { ArticleGroup } from "../models/article.ts"
-import {
-  buildArticleTree,
-  flattenArticleTree,
-  groupArticleTree,
-} from "../helpers/article.ts"
+import type { ArticleNode } from "../models/article.ts"
+import { buildArticleTree, flattenArticleTree } from "../helpers/article.ts"
 import { matchSection, partitionBySection } from "../helpers/section.ts"
 
 /**
@@ -20,16 +16,11 @@ export const sortedArticles = [...allArticles].sort(
 /** The article whose path is `/`, if any (rendered in place at the root) */
 export const homeArticle = sortedArticles.find(a => a.path === "/")
 
-/** Sidebar sections derived from the path tree, partitioned by `group` */
-export const articleGroups = groupArticleTree(
-  buildArticleTree(sortedArticles),
-  sortedArticles,
-)
+/** Sidebar tree derived from the article path hierarchy */
+export const articleTree = buildArticleTree(sortedArticles)
 
-/** Articles in depth-first order across all sections (matches sidebar walk) */
-export const flatArticles = articleGroups.flatMap(group =>
-  flattenArticleTree(group.nodes),
-)
+/** Articles in depth-first order across the tree (matches sidebar walk) */
+export const flatArticles = flattenArticleTree(articleTree)
 
 /** The first article in sidebar order, used as the default landing page */
 export const firstArticle = sortedArticles.find(a => a.path === flatArticles[0])
@@ -42,8 +33,12 @@ function orderKey(order?: number) {
 
 const configSections = config.sections
 
-/** Per-section article groups, keyed by section prefix */
-export const sectionArticleGroups = new Map<string, ArticleGroup[]>()
+/** Route-bound sections (everything except `external`). External sections
+ *  are pure links — they have no `prefix` and don't claim a URL space. */
+const routedSections = configSections?.filter(s => s.type !== "external") ?? []
+
+/** Per-section article tree, keyed by section prefix */
+export const sectionArticleTrees = new Map<string, ArticleNode[]>()
 
 /** Per-section flat article lists, keyed by section prefix */
 export const sectionFlatArticles = new Map<string, string[]>()
@@ -51,9 +46,9 @@ export const sectionFlatArticles = new Map<string, string[]>()
 /** Per-section first article path, keyed by section prefix */
 export const sectionFirstArticle = new Map<string, string | undefined>()
 
-if (configSections?.length) {
-  const sectionByPrefix = new Map(configSections.map(s => [s.prefix, s]))
-  const buckets = partitionBySection(sortedArticles, configSections)
+if (routedSections.length) {
+  const sectionByPrefix = new Map(routedSections.map(s => [s.prefix, s]))
+  const buckets = partitionBySection(sortedArticles, routedSections)
   for (const [key, bucket] of buckets) {
     const section = sectionByPrefix.get(key)
     const sorted =
@@ -64,16 +59,15 @@ if (configSections?.length) {
           )
         : bucket
     const tree = buildArticleTree(sorted)
-    const groups = groupArticleTree(tree, sorted)
-    const flat = groups.flatMap(g => flattenArticleTree(g.nodes))
-    sectionArticleGroups.set(key, groups)
+    const flat = flattenArticleTree(tree)
+    sectionArticleTrees.set(key, tree)
     sectionFlatArticles.set(key, flat)
     sectionFirstArticle.set(key, flat[0])
   }
 }
 
-/** Find which config section an article path belongs to */
+/** Find which routed config section an article path belongs to */
 export function currentSection(path: string) {
-  if (!configSections?.length) return undefined
-  return matchSection(path, configSections)
+  if (!routedSections.length) return undefined
+  return matchSection(path, routedSections)
 }

package/source/content-collections.ts

@@ -162,6 +162,7 @@ const articles = defineCollection({
             {
               filePath: resolve(config.root, doc._meta.filePath),
               root: config.root,
+              base: config.base,
             },
           ],
           remarkAnsi,
@@ -213,7 +214,7 @@ const articles = defineCollection({
     const searchText = extractSearchText(content)
     const lastUpdated = getLastUpdated(doc._meta.filePath)
     const image = doc.image
-      ? resolveAssetPath(doc.image, filePath, config.root)
+      ? resolveAssetPath(doc.image, filePath, config.root, config.base)
       : undefined
     return {
       ...doc,

package/source/helpers/article.ts

@@ -1,4 +1,4 @@
-import type { ArticleGroup, ArticleNode } from "../models/article.ts"
+import type { ArticleNode } from "../models/article.ts"
 
 /** Build a tree from a flat sorted list of articles based on path hierarchy */
 export function buildArticleTree(
@@ -41,44 +41,6 @@ export function buildArticleTree(
   return roots
 }
 
-/**
- * Partition root nodes into sidebar sections.
- *
- * Walks root nodes in sort order. A root whose article has a `group` field
- * opens a new section; subsequent roots without `group` append to the current
- * section. Roots before the first `group` field land in a single leading
- * section with `name: undefined` (rendered without a label).
- *
- * `group` on non-root articles is ignored — only roots gate section boundaries.
- */
-export function groupArticleTree(
-  tree: ArticleNode[],
-  articles: { path: string; group?: string }[],
-): ArticleGroup[] {
-  const groupByPathname = new Map<string, string | undefined>()
-  for (const article of articles) {
-    groupByPathname.set(article.path, article.group)
-  }
-
-  const sections: ArticleGroup[] = []
-  let current: ArticleGroup | undefined
-
-  for (const node of tree) {
-    const group = groupByPathname.get(node.path)
-    if (group) {
-      current = { name: group, nodes: [node] }
-      sections.push(current)
-    } else if (current) {
-      current.nodes.push(node)
-    } else {
-      current = { name: undefined, nodes: [node] }
-      sections.push(current)
-    }
-  }
-
-  return sections
-}
-
 /** Depth-first flatten of an article tree into a list of paths */
 export function flattenArticleTree(nodes: ArticleNode[]) {
   const result: string[] = []

package/source/helpers/prefix-url.ts

@@ -0,0 +1,22 @@
+/** Prefix a root-relative URL with `base` when the site is mounted at
+ *  a sub-path. Leaves protocol-absolute (`http(s)://`, `//`), scheme
+ *  (`mailto:`, `tel:`, `data:`), hash, and relative URLs untouched, and
+ *  is idempotent — already-prefixed URLs are returned unchanged so
+ *  config validation or hot reload can't double-prefix. */
+export function prefixUrl(url: string, base: string | undefined) {
+  if (!base) return url
+  if (
+    url.startsWith("http://") ||
+    url.startsWith("https://") ||
+    url.startsWith("//") ||
+    url.startsWith("mailto:") ||
+    url.startsWith("tel:") ||
+    url.startsWith("data:") ||
+    url.startsWith("#")
+  ) {
+    return url
+  }
+  if (!url.startsWith("/")) return url
+  if (url === base || url.startsWith(`${base}/`)) return url
+  return `${base}${url}`
+}

package/source/helpers/prefix-url.unit.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vite-plus/test"
+import { prefixUrl } from "./prefix-url.ts"
+
+describe("prefixUrl", () => {
+  it("should return url unchanged when base is undefined", () => {
+    expect(prefixUrl("/foo", undefined)).toBe("/foo")
+  })
+
+  it("should prefix a root-relative url", () => {
+    expect(prefixUrl("/foo", "/repo")).toBe("/repo/foo")
+  })
+
+  it("should prefix a deep root-relative url", () => {
+    expect(prefixUrl("/a/b/c.png", "/repo")).toBe("/repo/a/b/c.png")
+  })
+
+  it("should leave protocol-absolute http urls untouched", () => {
+    expect(prefixUrl("http://x.com/y", "/repo")).toBe("http://x.com/y")
+    expect(prefixUrl("https://x.com/y", "/repo")).toBe("https://x.com/y")
+  })
+
+  it("should leave protocol-relative urls untouched", () => {
+    expect(prefixUrl("//cdn.x.com/y", "/repo")).toBe("//cdn.x.com/y")
+  })
+
+  it("should leave scheme urls untouched", () => {
+    expect(prefixUrl("mailto:a@b.com", "/repo")).toBe("mailto:a@b.com")
+    expect(prefixUrl("tel:+123", "/repo")).toBe("tel:+123")
+    expect(prefixUrl("data:image/png;base64,xyz", "/repo")).toBe(
+      "data:image/png;base64,xyz",
+    )
+  })
+
+  it("should leave hash urls untouched", () => {
+    expect(prefixUrl("#section", "/repo")).toBe("#section")
+  })
+
+  it("should leave document-relative urls untouched", () => {
+    expect(prefixUrl("foo.png", "/repo")).toBe("foo.png")
+    expect(prefixUrl("./foo.png", "/repo")).toBe("./foo.png")
+    expect(prefixUrl("../foo.png", "/repo")).toBe("../foo.png")
+  })
+
+  it("should be idempotent on already-prefixed urls", () => {
+    expect(prefixUrl("/repo/foo", "/repo")).toBe("/repo/foo")
+    expect(prefixUrl("/repo", "/repo")).toBe("/repo")
+  })
+
+  it("should not match prefix-as-substring", () => {
+    expect(prefixUrl("/repository/foo", "/repo")).toBe("/repo/repository/foo")
+  })
+
+  it("should support multi-segment base", () => {
+    expect(prefixUrl("/foo", "/a/b")).toBe("/a/b/foo")
+    expect(prefixUrl("/a/b/foo", "/a/b")).toBe("/a/b/foo")
+  })
+})

package/source/helpers/resolve-asset-path.ts

@@ -1,9 +1,16 @@
-import { dirname, relative, resolve } from "node:path"
+import { dirname, relative, resolve, sep } from "node:path"
+import { prefixUrl } from "./prefix-url.ts"
 
 /** Resolve a relative asset path to an absolute URL serveable by Vite */
-export function resolveAssetPath(url: string, filePath: string, root: string) {
-  if (url.startsWith("http") || url.startsWith("/") || url.startsWith("data:"))
-    return url
+export function resolveAssetPath(
+  url: string,
+  filePath: string,
+  root: string,
+  base?: string,
+) {
+  if (url.startsWith("http") || url.startsWith("data:")) return url
+  if (url.startsWith("/")) return prefixUrl(url, base)
   const absolute = resolve(dirname(filePath), url)
-  return "/" + relative(root, absolute)
+  const rel = relative(root, absolute).split(sep).join("/")
+  return prefixUrl("/" + rel, base)
 }

package/source/helpers/resolve-asset-path.unit.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vite-plus/test"
+import { resolveAssetPath } from "./resolve-asset-path.ts"
+
+describe("resolveAssetPath", () => {
+  const root = "/site"
+  const filePath = "/site/docs/page.md"
+
+  it("should resolve a sibling relative path", () => {
+    expect(resolveAssetPath("./logo.png", filePath, root)).toBe(
+      "/docs/logo.png",
+    )
+  })
+
+  it("should resolve a parent relative path", () => {
+    expect(resolveAssetPath("../assets/x.png", filePath, root)).toBe(
+      "/assets/x.png",
+    )
+  })
+
+  it("should pass through a root-relative url", () => {
+    expect(resolveAssetPath("/foo.png", filePath, root)).toBe("/foo.png")
+  })
+
+  it("should pass through an http url", () => {
+    expect(resolveAssetPath("https://x.com/y.png", filePath, root)).toBe(
+      "https://x.com/y.png",
+    )
+  })
+
+  it("should pass through a data url", () => {
+    expect(resolveAssetPath("data:image/png;base64,xyz", filePath, root)).toBe(
+      "data:image/png;base64,xyz",
+    )
+  })
+
+  it("should prefix a resolved relative path with base", () => {
+    expect(resolveAssetPath("./logo.png", filePath, root, "/repo")).toBe(
+      "/repo/docs/logo.png",
+    )
+  })
+
+  it("should prefix a root-relative url with base", () => {
+    expect(resolveAssetPath("/foo.png", filePath, root, "/repo")).toBe(
+      "/repo/foo.png",
+    )
+  })
+
+  it("should not double-prefix an already-prefixed url", () => {
+    expect(resolveAssetPath("/repo/foo.png", filePath, root, "/repo")).toBe(
+      "/repo/foo.png",
+    )
+  })
+
+  it("should not prefix external urls when base is set", () => {
+    expect(
+      resolveAssetPath("https://x.com/y.png", filePath, root, "/repo"),
+    ).toBe("https://x.com/y.png")
+  })
+})

package/source/helpers/section.ts

@@ -4,6 +4,7 @@ const DEFAULT_ICONS: Record<Section["type"], string> = {
   article: "book-open",
   blog: "rss",
   changelog: "history",
+  external: "external-link",
 }
 
 /** Return the section's icon, falling back to a type-based default */

package/source/models/article.ts

@@ -12,7 +12,6 @@ export const Article = z.object({
   icon: nonEmptyString.optional(),
   order: z.number().optional(),
   path: nonEmptyString.optional(),
-  group: nonEmptyString.optional(),
   sidebar: z.boolean().default(true),
   toc: z.boolean().default(true),
   image: nonEmptyString.optional(),
@@ -49,12 +48,3 @@ export interface ArticleNode {
   icon: string
   children: ArticleNode[]
 }
-
-/**
- * A contiguous section of root articles sharing the same `group` label.
- * `name: undefined` represents the leading ungrouped section (at most one).
- */
-export interface ArticleGroup {
-  name?: string
-  nodes: ArticleNode[]
-}

package/source/models/config.ts

@@ -23,6 +23,14 @@ export type UserConfig = Omit<z.infer<typeof UserConfig>, "vite"> & {
 }
 export const UserConfig = z.object({
   site: z.string().optional(),
+  base: z
+    .string()
+    .optional()
+    .transform(v => {
+      if (!v) return undefined
+      const trimmed = v.replace(/^\/|\/$/g, "")
+      return trimmed ? `/${trimmed}` : undefined
+    }),
   favicon: z.string().optional(),
   logo: z.string().optional(),
   title: z.string().default("Livemark"),
@@ -46,6 +54,7 @@ export const WebsiteConfig = UserConfig.pick({
   title: true,
   description: true,
   site: true,
+  base: true,
   favicon: true,
   logo: true,
   links: true,

package/source/models/section.ts

@@ -3,7 +3,6 @@ import { z } from "zod"
 const BaseSection = z.object({
   icon: z.string().optional(),
   title: z.string(),
-  prefix: z.string(),
   position: z.enum(["header", "sidebar"]).default("header"),
 })
 
@@ -11,22 +10,32 @@ const BaseSection = z.object({
 export type ArticleSection = z.infer<typeof ArticleSection>
 export const ArticleSection = BaseSection.extend({
   type: z.literal("article"),
+  prefix: z.string(),
 })
 
 /** Blog section: date-sorted posts with tags and index. */
 export type BlogSection = z.infer<typeof BlogSection>
 export const BlogSection = BaseSection.extend({
   type: z.literal("blog"),
+  prefix: z.string(),
 })
 
 /** Changelog section: single file or GitHub releases, split per version. */
 export type ChangelogSection = z.infer<typeof ChangelogSection>
 export const ChangelogSection = BaseSection.extend({
   type: z.literal("changelog"),
+  prefix: z.string(),
   source: z.string(),
   version: z.boolean().optional(),
 })
 
+/** External section: renders as a link to an arbitrary URL. */
+export type ExternalSection = z.infer<typeof ExternalSection>
+export const ExternalSection = BaseSection.extend({
+  type: z.literal("external"),
+  url: z.string(),
+})
+
 /**
  * A site section. Discriminated on `type`.
  * When `type` is omitted, it defaults to "article" so plain
@@ -41,5 +50,10 @@ export const Section = z.preprocess(
     const record = input as Record<string, unknown>
     return "type" in record ? record : { ...record, type: "article" }
   },
-  z.discriminatedUnion("type", [ArticleSection, BlogSection, ChangelogSection]),
+  z.discriminatedUnion("type", [
+    ArticleSection,
+    BlogSection,
+    ChangelogSection,
+    ExternalSection,
+  ]),
 )

package/source/plugins/remark-image.ts

@@ -5,12 +5,12 @@ import { resolveAssetPath } from "../helpers/resolve-asset-path.ts"
 
 /** Remark plugin that resolves relative image paths and unwraps image-only paragraphs */
 export const remarkImage: Plugin<
-  [{ filePath: string; root: string }],
+  [{ filePath: string; root: string; base?: string }],
   Root
-> = ({ filePath, root }) => {
+> = ({ filePath, root, base }) => {
   return tree => {
     visit(tree, "image", node => {
-      node.url = resolveAssetPath(node.url, filePath, root)
+      node.url = resolveAssetPath(node.url, filePath, root, base)
     })
 
     visit(tree, "paragraph", (node, index, parent) => {

package/source/plugins/vite-livemark.ts

@@ -50,6 +50,11 @@ export function livemark(opts: LivemarkOptions): Plugin {
       targetDir = buildTarget(opts.config.configPath)
       const base: ViteUserConfig = {
         root: targetDir,
+        // Mount everything (asset URLs, modulepreloads, dev server) under
+        // `config.base` so the same build works at root or at a sub-path
+        // (e.g. GitHub Pages `https://user.github.io/repo/`). The router
+        // and asset-path resolver mirror this at runtime.
+        base: opts.config.base ? `${opts.config.base}/` : "/",
         // outDir lives outside the target root (in the consumer's
         // .livemark/) so the consumer can find their deployable output
         // without digging into node_modules. Vite's default refusal to

package/source/router.tsx

@@ -1,3 +1,4 @@
+import { config } from "livemark:virtual"
 import { QueryClient } from "@tanstack/react-query"
 import { createRouter } from "@tanstack/react-router"
 import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query"
@@ -10,6 +11,7 @@ export function getRouter() {
 
   const router = createRouter({
     routeTree,
+    basepath: config.base,
     context: { queryClient },
     trailingSlash: "always",
     defaultPreload: "intent",

package/source/routes/__root.tsx

@@ -15,13 +15,17 @@ import { DefaultCatchBoundary } from "../components/DefaultCatchBoundary.tsx"
 import { NotFound } from "../components/NotFound.tsx"
 import { Toaster } from "../elements/sonner.tsx"
 import { faviconType } from "../helpers/favicon.ts"
+import { prefixUrl } from "../helpers/prefix-url.ts"
 import defaultFavicon from "../assets/logo.svg"
 import generalCss from "../styles/general.css?url"
 import markdownCss from "../styles/markdown.css?url"
 
 export const Route = createRootRoute({
   head: () => {
-    const favicon = config.favicon ?? config.logo ?? defaultFavicon
+    const favicon = prefixUrl(
+      config.favicon ?? config.logo ?? defaultFavicon,
+      config.base,
+    )
     return {
       meta: [
         { charSet: "utf-8" },

package/source/vite.config.ts

@@ -18,12 +18,26 @@ export default defineConfig({
     contentCollections({ configPath: "content-collections.ts" }),
     tanstackStart({
       srcDirectory: ".",
-      pages: [{ path: "/" }],
-      prerender: { enabled: true, crawlLinks: true },
+      // Seed path must match what the crawler produces (router-emitted
+      // hrefs include the basepath), otherwise prerender records both
+      // shapes and the sitemap ends up with duplicate entries.
+      pages: [{ path: config.base ? `${config.base}/` : "/" }],
+      // Disable route-tree auto-discovery: it produces basepath-naive
+      // paths (e.g. `/`) that duplicate the crawl-derived prefixed paths,
+      // bloating pages.json and sitemap. Crawling from the seed already
+      // reaches every linked page.
+      prerender: {
+        enabled: true,
+        crawlLinks: true,
+        autoStaticPathsDiscovery: false,
+      },
       sitemap: config.site
         ? { enabled: true, host: config.site }
         : { enabled: false },
-      router: { generatedRouteTree: "routeTree.gen.ts" },
+      router: {
+        generatedRouteTree: "routeTree.gen.ts",
+        basepath: config.base,
+      },
     }),
     react(),
     svgr(),