Vuepress is an amazing tool to create fast documentation and it can live inside your main project with few configuration changes.
Your existing project
For this example, we are going to set a static html project as the "parent" project, but it could use any technology without issues.
Create the existing project
mkdir my-site
cd my-site
touch index.html
We can add a pretty simple html layout as an example using tailwindcss:
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
<h1 class="text-3xl font-bold underline">
Hello world!
</h1>
<a class="mt-6" href="/docs/index.html">Documentation</a>
</body>
</html>
Install
Run:
npm add -D vitepress
Init Vitepress
Run:
npx vitepress init
As we are setting /vitepress as the vitepress dev directory, the configuration wizard should look like this:
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./vitepress
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└
Configuration changes
in vitepress/.vitepress/config.mts add this key-values:
base: '/docs/',
outDir: '../docs',
Work in your documentation
Execute in your project root path:
npx vitepress dev vitepress
Go to http://localhost:xxxx/docs and make your required changes as you need.
Build documentation for production
Run:
npx vitepress build vitepress
You can open your main project and link your docs with an anchor tag to /docs/index.html
Bonus
Sometimes you would prefer to go directly to the docs and avoid the vitepress default homepage
Replace index.md content with:
<meta http-equiv="refresh" content="0;url=/docs/markdown-examples.html" />
It could redirect to any html generated page.
Deploy
Take in mind that your entry point for this configuration should be /, that automatically is going to try to load /index.html, so it could probably require to adjust your output directory, eg: vercel settings
Top comments (0)