Theming API
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.
theme:
components:
- "./components"
layout:
slots:
layout_top: "AnnouncementBar"
doc_after: "FeedbackWidget"<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><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:
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:
theme:
layout: "./theme/MyLayout.vue"A minimal custom layout:
<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:
import { TdLayout, TdContentNav, TdThemeToggle } from 'typerighter/client/theme-default'Custom components
Register components globally for use in .td files and layout slots:
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>.
<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:
:root { --bg: #fff; --fg: #111; }
.dark { --bg: #111; --fg: #eee; }