viteTemplPreviewPlugin

The plugin supports two modes of operation, reflecting the static-templ modes. The resulting output is the same in both cases, but the choice depends on your preferences for content management and resulting URLs.

Inline Mode

This is the default method. It involves setting up a Go module project in the root folder of your VitePress project, with the templ files alongside your markdown content files.

The resulting URLs will be in the form of /components/button or /components/dropdown.

1. Initialize a new Go project within the VitePress project root folder docs as you would for a normal templ project. Refer to the official documentation.

   cd docs
   go mod init components_demo
   go get github.com/a-h/templ

2. Create a components folder within ./docs and structure your documentation pages accordingly.

The resulting project structure should look like this:

.
├── docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  ├─ index.md
│  ├─ components
│  │  ├─ button
│  │  │  ├─ button-demo.templ
│  │  │  └─ index.md
│  │  ├─ dropdown
│  │  │  ├─ dropdown-demo.templ
│  │  │  └─ index.md
│  ├─ go.mod
│  ├─ go.sum
└─ package.json

TIP

This website is built using inline mode. The code is available in the GitHub repository and can be used as a reference.

Bundle mode

This method involves setting up a new Go module project in a subfolder of your VitePress project.

The resulting URLs will be in the form of /components/button.html or /components/dropdown.html.

1. Create a templ-preview folder within ./docs containing your templ project.

2. Initialize a new Go project within it as you would for a normal templ project. Refer to the official doc.

   cd templ-preview
   go mod init templ-preview
   go get github.com/a-h/templ

3. Create a demos folder to store your templ files

The resulting project structure should look like this:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  ├─ components
│  │  └─ button.md
│  │  └─ dropdown.md
│  └─ index.md
│  ├─ templ-preview
│  │  └─ demos
│  │     └─ button-demo.templ
│  │     └─ dropdown-demo.templ
│  │  └─ go.mod
│  │  └─ go.sum
└─ package.json

TIP

If you are interested in bundle working mode, there is a sample project in the GitHub repository that you can use as a reference. Check it out here.

Options

The following table lists the configurable options for the viteTemplPreviewPlugin. These options allow you to customize the plugin's behavior according to your project's needs. Most of these options are the same as those accepted by static-templ.

Option	Type	Default	Description
goProjectDir	string	.	The base directory where your Go templ project is located. Default to the vitepress project root folder.
mode	string	inline	The working mode for the plugin: inline or bundle.
inputDir	string	components	The directory relative to goProjectDir where your .templ files are located.
outputDir	string	output	The directory relative to goProjectDir where the generated HTML files will be placed.
debug	boolean	false	Whether or not to keep the static-templ generation script after completion.
runTemplGenerate	boolean	true	Whether the plugin should run the templ generate command for you.
cacheSize	number	100	The maximum number of files to cache.

To configure these options, set the values in your VitePress configuration file as shown below:

// .vitepress/config.mts
import { defineConfig } from "vitepress";
import viteTemplPreviewPlugin from "vitepress-templ-preview";

export default defineConfig({
  /* ... */
  vite: {
    plugins: [
      viteTemplPreviewPlugin({
        // goProjectDir: "",
        // mode: "inline",
        // inputDir: "components",
        // outputDir: "output",
        // debug: false,
        // runTemplGenerate: true,
        // cacheSize: 100,
      }),
    ],
  },
  /* ... */
});