Skip to content

Theming API

Modified at Nov 16, 2026
DescriptionCustom layouts, layout slots, dark mode, and custom components.

Typerighter's default layout has extension points for common customizations: adding a banner above the header, replacing the footer, or injecting analytics. You can fill these with layout slots in typedown.yaml, or replace the entire layout with your own Vue component.

NOTE

This page assumes familiarity with Vue.js and its Composition API.

Full example ​

Here is a complete setup that adds an announcement bar above the header and a feedback widget below the content, using layout slots and two custom components.

YAMLtypedown.yaml
theme:
  components:
    - "./components"
  layout:
    slots:
      layout_top: "AnnouncementBar"
      doc_after: "FeedbackWidget"
Vuecomponents/AnnouncementBar.vue
<script setup>
import { ref } from 'vue'

const dismissed = ref(false)
</script>

<template>
  <div v-if="!dismissed" class="announcement">
    <span>Typerighter v1.0 is out!</span>
    <button @click="dismissed = true">Dismiss</button>
  </div>
</template>
Vuecomponents/FeedbackWidget.vue
<script setup>
import { useRoute } from 'typerighter/client'

const route = useRoute()
</script>

<template>
  <div class="feedback">
    <p>Was this page helpful?</p>
    <a :href="`https://github.com/user/repo/issues/new?title=Feedback: ${route.data?.title}`">
      Leave feedback
    </a>
  </div>
</template>

The components are registered by scanning the ./components directory. The slot mappings in typedown.yaml tell the default layout where to render them. No layout replacement needed.

Layout slots ​

The default layout has named slots where you can inject your own components. Declare slot mappings in typedown.yaml under theme.layout.slots:

YAMLtypedown.yaml
theme:
  components:
    - "./components"
  layout:
    slots:
      layout_top: "AnnouncementBar"
      doc_after: "FeedbackWidget"

Each key is a slot name and each value is the PascalCase name of a registered component (from theme.components).

Available slots ​

Slot Position
layout_top Above the header
nav_bar_after After the navigation links in the header
sidebar_top Top of the sidebar, before search
sidebar_bottom Bottom of the sidebar, after the navigation tree
doc_before Top of the article, before the page title
doc_content_before After title and frontmatter, before the content body
doc_content_after After the content body, before prev/next navigation
doc_after After prev/next and the edit link
layout_bottom Below the footer

Slot names use underscores in the YAML config because hyphens are reserved in Typedown's expression syntax.

Custom layout ​

For full control, replace the default layout with your own Vue component:

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

A minimal custom layout:

Vue
<script setup>
import { Content, useTdContent, useRoute } from 'typerighter/client'

const route = useRoute()
useTdContent()
</script>

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

useTdContent() must be called in your layout's setup before <Content /> renders. See the Client API reference for all available composables and components.

Reusing default components ​

You can import individual components from the default theme:

TypeScript
import { TdLayout, TdContentNav, TdThemeToggle } from 'typerighter/client/theme-default'

Custom components ​

Register components globally for use in .td files and layout slots:

YAMLtypedown.yaml
theme:
  components:
    - "./components"        # scan directory for .vue files
    - name: MyCard          # explicit entry
      source: "./ui/Card.vue"

Components registered this way are available in any .td file without importing, and can be referenced by name in layout.slots.

Dark mode ​

Typerighter manages dark mode with the useTheme() composable, which persists the user's preference in localStorage and toggles a .dark class on <html>.

Vue
<script setup>
import { useTheme } from 'typerighter/client'

const { isDark, toggle, setTheme } = useTheme()
</script>

<template>
  <button @click="toggle">
    {{ isDark ? 'Light' : 'Dark' }}
  </button>
</template>

To style for dark mode in CSS, target the .dark class:

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