Skip to content

Client API

Modified at Nov 16, 2026
DescriptionComposables and components exported from typerighter/client for use in custom layouts.

When building a custom Typerighter layout, you need access to page data, routing, and site configuration. The typerighter/client module exports composables and components for this.

Full example ​

A complete custom layout that renders a header with site title and dark mode toggle, the page content, and a list of sibling pages:

Vuetheme/Layout.vue
<script setup>
import {
  Content,
  useRoute,
  useSiteConfig,
  useSiteData,
  useTdContent,
  useTheme,
} from 'typerighter/client'
import { computed } from 'vue'

const route = useRoute()
const { title, withBase, nav } = useSiteConfig()
const siteData = useSiteData()
const { isDark, toggle } = useTheme()

useTdContent()

const siblings = computed(() => {
  if (!siteData.value.ready) return []
  const directory = route.data?.filepath?.split('/').slice(0, -1).join('/') ?? ''
  return siteData.value.directoryListings[`/${directory}`] ?? []
})
</script>

<template>
  <header>
    <a :href="withBase('/')">{{ title }}</a>
    <nav>
      <a v-for="link in nav" :key="link.link" :href="withBase(link.link)">
        {{ link.title }}
      </a>
    </nav>
    <button @click="toggle">{{ isDark ? 'Light' : 'Dark' }}</button>
  </header>

  <main>
    <h1 v-if="route.data?.title">{{ route.data.title }}</h1>
    <Content />
  </main>

  <aside v-if="siblings.length > 0">
    <h2>In this section</h2>
    <ul>
      <li v-for="entry in siblings" :key="entry.route">
        <a :href="withBase(entry.route)">{{ entry.label ?? entry.title }}</a>
      </li>
    </ul>
  </aside>
</template>

Register this layout in typedown.yaml:

YAMLtypedown.yaml
theme:
  layout: "./theme/Layout.vue"

The sections below document each composable and component used in this example.

useRoute ​

Returns the current route as a reactive object. Updates on every navigation.

TypeScript
const route = useRoute()

route.path    // "/guide/introduction"
route.hash    // "#getting-started"
route.data    // PageData for the current page

PageData ​

TypeScript
interface PageData {
  title: string
  titleHtml: string              // title with inline markup, safe for v-html
  headings: MarkdownHeading[]    // nested heading tree (h1 to h6)
  frontmatter: Record<string, unknown>
  schema?: string                // schema type name if page uses a schema
  schemaLabel?: string
  label?: string                 // _label override
  filepath: string               // path relative to vault root, e.g. "guide/intro.td"
  fileMetadata?: { mtime: number; ctime: number }
}

MarkdownHeading ​

TypeScript
interface MarkdownHeading {
  level: number           // 1 to 6
  title: string           // plain text
  titleHtml: string       // HTML with inline code/math, safe for v-html
  slug: string            // anchor id (deduplicated)
  link: string            // e.g. "#getting-started"
  children: MarkdownHeading[]
}

Headings are returned as a nested tree. To flatten for a TOC:

TypeScript
function flattenHeadings(items: MarkdownHeading[], depth = 2) {
  const result = []
  for (const h of items) {
    if (h.level <= depth) result.push(h)
    result.push(...flattenHeadings(h.children, depth))
  }
  return result
}

useSiteConfig ​

Returns site-wide configuration from typedown.yaml. Reactive across HMR config changes.

TypeScript
const config = useSiteConfig()
TypeScript
interface TypedownSiteConfig {
  title: string
  description: string
  basePath: string                          // e.g. "/" or "/docs"
  origin?: string                           // e.g. "https://example.com"
  lang: string                              // HTML lang attribute
  rootDir: string                           // vault root directory name
  repo?: { url: string; root: string }
  author?: string
  license?: string
  nav: { title: string; link: string; icon?: string }[]
  withBase(path: string): string            // prepends basePath to a path
}

withBase is useful for generating hrefs that work under a subpath deployment:

TypeScript
const { withBase } = useSiteConfig()

withBase('/guide/index')  // returns "/docs/guide/index" if basePath is "/docs"

useSiteData ​

Returns a reactive Ref containing the full vault graph. Updates via HMR when content changes. Use this to query pages, schemas, and directory contents from a custom layout or component.

TypeScript
const siteData = useSiteData()

// wait for initial load before accessing content
if (!siteData.value.ready) return
TypeScript
interface TypedownSiteData {
  ready: boolean
  contentTree: ContentTree
  schemas: Record<string, SchemaInfo>
  directoryListings: Record<string, DirectoryListing>
}

ContentTree ​

The full set of published pages, keyed by route path.

TypeScript
type ContentTree = Record<string, ContentNode>

interface ContentNode {
  route: string                        // e.g. "/people/alice"
  filepath: string                     // path relative to vault root
  title: string
  label?: string                       // _label override
  icon?: string                        // _icon value
  schema?: string                      // schema type name
  frontmatter: Record<string, unknown>
  children: string[]                   // child routes for directory nodes
}

Example - list all pages that use a given schema:

TypeScript
const nodes = Object.values(siteData.value.contentTree)
const articles = nodes.filter(node => node.schema === 'Article')

SchemaInfo ​

Metadata about a schema defined in _types/.

TypeScript
interface SchemaInfo {
  name: string
  label?: string
  fields: SchemaField[]
}

interface SchemaField {
  name: string
  type: string        // e.g. "string", "number", "boolean", "fref", schema name
  required: boolean
  description?: string
}

Example - render a table of all fields for the current page's schema:

TypeScript
const { page } = useTdContent()
const schema = computed(() =>
  page.value.schema
    ? siteData.value.schemas[page.value.schema]
    : undefined
)

DirectoryListing ​

The ordered list of child pages for a directory node. Keyed by directory route.

TypeScript
type DirectoryListing = Record<string, DirectoryEntry[]>

interface DirectoryEntry {
  route: string
  title: string
  label?: string
  icon?: string
  description?: string    // frontmatter.description
  schema?: string
}

Example - render a card grid of sibling pages in a custom layout:

TypeScript
const { page } = useTdContent()
const siblings = computed(() => {
  const dir = page.value.filepath.split('/').slice(0, -1).join('/')
  return siteData.value.directoryListings[`/${dir}`] ?? []
})

useTdContent ​

Sets up the provide/inject context required by <Content /> and returns reactive page bindings. Must be called once in your layout's setup function.

TypeScript
const { page, title, frontmatter, isDark } = useTdContent()
TypeScript
interface TypedownData {
  page: Ref<PageData>
  frontmatter: Ref<Record<string, unknown>>
  title: Ref<string>
  isDark: Ref<boolean>
}

isDark reflects the current theme state, derived from useTheme() internally.

useTheme ​

Controls the dark mode state. Persists the user's preference in localStorage and toggles the .dark class on <html>.

TypeScript
const { isDark, toggle, setTheme, effectiveTheme, theme } = useTheme()
TypeScript
{
  theme: Readonly<Ref<'light' | 'dark' | 'system'>>
  effectiveTheme: ComputedRef<'light' | 'dark'>   // resolved value when mode is 'system'
  isDark: ComputedRef<boolean>
  toggle(): void
  setTheme(value: 'light' | 'dark' | 'system'): void
}

'system' is the default. It reads prefers-color-scheme and updates reactively when the OS setting changes.

Vue
<button @click="toggle">Toggle dark mode</button>

To style for dark mode in CSS, target the .dark class on <html>:

CSS
:root       { --bg: #fff; --fg: #111; }
.dark       { --bg: #111; --fg: #eee; }

useRouter ​

Returns the router for programmatic navigation.

TypeScript
const router = useRouter()

await router.go('/guide/introduction')
await router.go('/guide/introduction#section', { replace: true })
TypeScript
interface Router {
  route: Route
  go(to: string, options?: { replace?: boolean }): Promise<void>
  onBeforeRouteChange?: (to: string) => Promise<boolean | undefined> | boolean | undefined
  onAfterRouteChange?: (to: string) => Promise<void> | void
}

Content ​

The <Content /> component renders the compiled markdown body of the current page. It has no props.

Vue
<template>
  <article class="prose">
    <Content />
  </article>
</template>

useTdContent() must be called before <Content /> renders.

Rendered output consists of standard HTML elements (h1-h6, p, ul, pre, table, etc.). Style them by wrapping with a class:

CSS
.prose h1 { font-size: 2rem; font-weight: 800; }
.prose p  { line-height: 1.7; color: #555; }
.prose pre { background: #f5f5f5; border-radius: 8px; padding: 16px; }
Edit this page