自定义路由

更新于 2026年11月12日

Livemark 基于 TanStack Router 构建。你放入 .livemark/routes/ 的任何 .tsx 文件都会成为对应 URL 上的页面，无需注册，也无需修改配置。

最小示例

.livemark/routes/about.tsx

import { createFileRoute } from "@tanstack/react-router"
import { Layout } from "livemark/components/Layout"

export const Route = createFileRoute("/about")({
  component: About,
})

function About() {
  return (
    <Layout>
      <div className="mx-auto max-w-3xl px-6 py-16 prose">
        <h1>About</h1>
        <p>Anything you'd write in a normal React page, here.</p>
      </div>
    </Layout>
  )
}

保存后访问 /about/。Layout 为页面提供与文章相同的外框：横幅、顶栏、导航和深色模式切换按钮。

选择页面外框

自定义路由一开始是空白的：在你添加之前，它周围什么都不会绘制。按页面需要组合即可：

你渲染的内容	你得到的效果
`<Layout>`	横幅、顶栏、手机端导航面板、返回顶部
`<Layout withSidebar>`	以上内容，外加文章侧边栏
`<Banner />` + `<Header />`	仅横幅和顶栏；在手机上是一个栏目菜单
什么都不渲染	一个空白页面，完全由你掌控

首页通常只需要顶栏：

.livemark/routes/index.tsx

import { createFileRoute } from "@tanstack/react-router"
import { Banner } from "livemark/components/Banner"
import { Header } from "livemark/components/Header"

export const Route = createFileRoute("/")({ component: Landing })

function Landing() {
  return (
    <>
      <Banner />
      <Header />
      <main>{/* your hero */}</main>
    </>
  )
}

与站点其余部分的关系

精确路径优先。 自定义路由的优先级高于提供 Markdown 文章的兜底路由。如果你创建了 /about，那么位于同一路径的 docs/about.md 文章将无法访问。
根路径 /。 放入 .livemark/routes/index.tsx，即可用你自己的页面替换默认首页。Livemark 的默认站点使用 Markdown 首页，覆盖它可以让你用 React 完全掌控首屏区域。
嵌套路径。 文件路径与 URL 路径一一对应：.livemark/routes/guide/quickstart.tsx ⇒ /guide/quickstart/。
自行预渲染。 livemark build 会把每个不带 $ 参数的自定义路由写入磁盘，即使没有任何页面链接到它。带参数的路由只会为其他页面所链接的 URL 生成文件。
head 标签随之提供。 自定义路由会获得站点标题和描述、规范链接和 og:url（设置了 site 时），在多语言站点上还会获得 og:locale 和 hreflang 链接，所用语言取决于其路径所属的语言。路由上的 head 可以覆盖标题和 meta 标签。

导入 Livemark 基础组件

通过 livemark/* 子路径导出，复用 Livemark 内部使用的相同组件：

.livemark/routes/about.tsx

import { createFileRoute, Link } from "@tanstack/react-router"
import { buttonVariants } from "livemark/elements/button"
import { cn } from "cn"

export const Route = createFileRoute("/about")({ component: About })

function About() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-16">
      <h1 className="text-4xl font-bold tracking-tight">About</h1>
      <Link to="/" className={cn(buttonVariants({ variant: "outline" }), "mt-6")}>
        ← Back home
      </Link>
    </main>
  )
}

静态资源

放在 .livemark/public/ 中的文件会在站点根路径下提供。可以把 robots.txt、自定义的 favicon.svg 或 /og-image.png 放在这里。

另请参阅

覆盖（escape）：替换内置页面或组件，而不是新增一个。
站点元数据：站点标题和 favicon，同样会显示在自定义路由上。