Pages
The files you'd like to declare as pages are configured in the Vitebook configuration file
as shown here. Pages can be markdown files (.md
),
or component files (.vue,.svelte,.jsx,.tsx
), depending on the plugins you've setup.
It's important to note that a plugin must resolve a file as a page via the resolvePage
hook,
otherwise you'll see a warning in your terminal. If a file is not resolved as a page by any
plugin but it's included in your configuration, it is assumed to not be supported and ultimately
not included in your application.
Routing
Every file you declare as a page, is used to do something called file-based routing. This simply
means the path to your file determines the application route to that page in your browser. The
<srcDir>
is used to determine the root of
all routes.
INFO
The example mappings below of file path to application routes is assuming your <srcDir>
is
the default, which is <rootDir>/src
.
- Markdown
- Preact
- Svelte
- Vue
src/index.md -> site.com/
src/intro.md -> site.com/intro.html
src/about/README.md -> site.com/about/
src/button/index.md -> site.com/button/
src/button/usage.md -> site.com/button/usage.html
src/index.jsx -> site.com/
src/intro.jsx -> site.com/intro.html
src/button/index.jsx -> site.com/button/
src/button/usage.jsx -> site.com/button/usage.html
src/Button/Button.story.jsx -> site.com/button/button.html
src/index.svelte -> site.com/
src/intro.svelte -> site.com/intro.html
src/button/index.svelte -> site.com/button/
src/button/usage.svelte -> site.com/button/usage.html
src/Button/Button.story.svelte -> site.com/button/button.html
src/index.vue -> site.com/
src/intro.vue -> site.com/intro.html
src/button/index.vue -> site.com/button/
src/button/usage.vue -> site.com/button/usage.html
src/Button/Button.story.vue -> site.com/button/button.html
404 Page
The theme you've selected will most likely already include a 404 page, but you can have a
custom one by creating a file at <srcDir>/404.{md,jsx,tsx,vue,svelte}
. Now when
a user visits any unknown route in the browser they'll be redirected to this 404 page.
Custom Routes
You can escape the default route resolution in two ways:
(1) Creating a route resolver in your Vitebook config file.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
resolveRoute({ filePath, relativeFilePath }) {
// ...
},
});
(2) Or, exporting a route in either the frontmatter for markdown files, or as an export binding for JS modules.
- Markdown
- Preact
- Svelte
- Vue
---
route: 'Design System/Atoms/Button'
---
# Title
...
export const __route = 'Design System/Atoms/Button';
function Page() {
// ...
}
export default Page;
<script context="module" lang="ts">
export const __route = 'Design System/Atoms/Button';
</script>
<script lang="ts">
// ...
</script>
<!-- ... -->
<script lang="ts">
export const __route = 'Design System/Atoms/Button';
</script>
<script setup lang="ts">
// ...
</script>
<template>
<!-- ... -->
</template>
Page Meta
Page meta refers to metadata about the page such as the title, description, and head tags. You
can set the page meta via markdown frontmatter, or by exporting a __pageMeta
object.
INFO
The title for markdown pages is automatically inferred by the top-level heading, and for all other pages by the filename.
- Markdown
- Preact
- Svelte
- Vue
---
title: Awesome Title
description: Awesome description.
head:
- - meta
- name: foo
content: bar
- - script
- type: module
src: https://foobar.com
---
# Inferred Title
...
import type { PageMeta } from '@vitebook/client';
// This can also be an async function which receives the loaded page and module.
export const __pageMeta: PageMeta = {
title: 'Awesome Title',
description: 'Awesome description.',
head: [
['meta', { name: 'foo', content: 'bar' }],
['script', { type: 'module', src: 'https://foobar.com' }],
['style', { type: 'text/css' }, 'p { color: red; }'],
],
};
function Page() {
// ...
}
export default Page;
<script context="module" lang="ts">
import type { PageMeta } from '@vitebook/client';
// This can also be an async function which receives the loaded page and module.
export const __pageMeta: PageMeta = {
title: 'Awesome Title',
description: 'Awesome description.',
head: [
['meta', { name: 'foo', content: 'bar' }],
['script', { type: 'module', src: 'https://foobar.com' }],
['style', { type: 'text/css' }, 'p { color: red; }'],
],
}
</script>
<script lang="ts">
// ...
</script>
<!-- ... -->
<script lang="ts">
import type { PageMeta } from '@vitebook/client';
// This can also be an async function which receives the loaded page and module.
export const __pageMeta: PageMeta = {
title: 'Awesome Title',
description: 'Awesome description.',
head: [
['meta', { name: 'foo', content: 'bar' }],
['script', { type: 'module', src: 'https://foobar.com' }],
['style', { type: 'text/css' }, 'p { color: red; }'],
],
};
</script>
<script setup lang="ts">
// ...
</script>
<template>
<!-- ... -->
</template>