Quick Start
Assuming you chose to scaffold the VitePress project in ./docs
, the initial generated file structure should look like this:
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
Installation
Add vitepress-templ-preview
to your VitePress project using one of the following commands:
npm add -D vitepress-templ-preview
pnpm add -D vitepress-templ-preview
yarn add -D vitepress-templ-preview
VitePress configuration
- Configure the plugin in your VitePress project by editing the VitePress config file (
.vitepress/config.js
or.vitepress/config.mts
) - Register the rendering component: choose a predefined Vue component or Use a custom component; Create or edit
.vitepress/theme/index.js
or.vitepress/theme/index.ts
// .vitepress/config.mts
import { defineConfig } from "vitepress";
import viteTemplPreviewPlugin from "vitepress-templ-preview";
export default defineConfig({
/* ... */
markdown: {},
vite: {
plugins: [viteTemplPreviewPlugin()],
},
/* ... */
});
//.vitepress/theme/index.ts
import type { Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
import { VTPIconTabs } from "vitepress-templ-preview/components";
import "vitepress-templ-preview/style.css";
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
/* Make sure to name the tag `VTPLivePreview` */
app.component("VTPLivePreview", VTPIconTabs);
},
} satisfies Theme;
INFO
Please, refer to the Plugin Options to see the available options for the plugin.
Templ Project Setup
Initialize a new Go project within the VitePress project root folder
docs
as you would for a normaltempl
project. Refer to the official doc.bashcd docs go mod init components_demo go get github.com/a-h/templ
Create a
components
folder within./docs
.Create a
hello
folder to store both the markdown and thetempl
files for the demos:Create an
index.md
fileCreate a
hello-demo.templ
file with sometempl
code:templpackage hello templ HelloDemo() { @hello("World!!!") } templ hello(name string) { <div>Hello, { name }</div> }
Your project structure should look like this:
.
├── docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ ├─ index.md
│ ├─ components
│ │ ├─ hello
│ │ │ ├─ hello-demo.templ
│ │ │ └─ index.md
│ ├─ go.mod
│ ├─ go.sum
└─ package.json
Embed in Markdown
To embed and preview a templ
component in your markdown files, use the templ-demo
tag.
Edit the components/hello/index.md
file by adding:
<templ-demo src="hello-demo"></templ-demo>
Alternatively, you can use the self-closing format:
<templ-demo src="hello-demo" />
IMPORTANT
The src
property is the only mandatory attribute. It must be set to the templ
file name without the extension.
For more information on the available options for rendering components via the custom templ-demo
tag, refer to the Rendering Components documentation.
Run the project
Based on your initial configuration, the npm scripts might already be set in the package.json
file.
To start the local dev server, use one of the following commands:
npm run docs:dev
pnpm run docs:dev
yarn docs:dev
Visit the page for the hello component you just created.
Your project is now up and running. Enjoy! ❤️