Quick Start

1. Replace Domain

Goto config.mts file, change 'sitemap' & 'socialLinks' parts to your own domains.

{
    sitemap: {
        hostname: "https://docs.code2life.top", 
        hostname: "https://docs.awesome.com", 
    },

    socialLinks: [
        {
            icon: "github",
            link: "https://github.com/code2life/vitepress-diataxis-template", 
            link: "https://github.com/your-org/your-project", 
        },
    ]
}

2. Setup Giscus Comments

1. Install Giscus App to your public doc repo

2. Enable discussion feature for the repo

1. Replace data-repo and data-repo, data-repo-id, data-category, data-category-id in docs/.vitepress/theme/components/VComments.vue, find the snippets here: https://giscus.app/

// docs/.vitepress/theme/components/VComment.vue
<ClientOnly>
  <component :is="'script'" src="https://giscus.app/client.js" 
    data-repo="code2life/vitepress-diataxis-template"
    data-repo-id="R_kgDOMsQCjQ"
    data-category="General"
    data-category-id="DIC_kwDOMsQCjc4CisoM"
    data-repo="replace-me"
    data-repo-id="replace-me"
    data-category="General"
    data-category-id="replace-me"
    data-mapping="pathname" data-strict="0" 
    :data-theme="isDark ? 'dark' : 'light'"
    data-reactions-enabled="1" data-emit-metadata="0"
    crossorigin="anonymous"
    data-input-position="top" data-lang="en"  data-loading="lazy" async />
</ClientOnly>

3. Setup Auto Translate

This template repo is integrated GPT translate, you can start using it in 3 steps.

1. Modify .github/workflows/auto-translate.yml config based on this doc
2. Enable write permission and add OPENAI_API_KEY based on this doc, the built-in example using Perplexity AI
3. Once commit to main, it will auto translate based on the workflow config

4. Setup PostHog Analysis

PostHog is an amazing SaaS product that covers almost all customer behavior analysis requirements.

Goto PostHog, register account and follow the setup steps, then copy the code snippets to replace docs/.vitepress/config.mts head part.

head: [
    ["meta", { name: "color-scheme", content: "dark" }],
    ...
    [
        "script",
        {},
        // copy your own script from PostHog onboarding page
        `!function(t,e){var o,n,p,r;e.__SV||(window.posthog=...{api_host:'https://us.i.posthog.com'...`,  
    ],
],

5. Setup Sandpack Code Sandbox

Sandpack is a great tool for adding interactive tutorials on documents, especially for frontend tech stack, it's out-of-box for this template site, see

See example page and check vitepress-plugin-sandpack doc for more details.

6. Add Auto-generated API Docs

This template integrates with Stoplightio Elements for auto generating API docs based on OpenAPI schema, using separate page without any layout is recommended.

Use the WebComponent with just one line of doc, see this demo.

---
layout: false
---

<ClientOnly>
    <elements-api apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml" router="hash" layout="sidebar"></elements-api>
</ClientOnly>

If you need to customize API doc page, check the Stoplight Elements Options.

7. Customization

Read VitePress official docs to find customization ways, here are some common customization entrypoints.

• docs/.vitepress/sidebar.mts is for changing the menu of guide/reference, remember to update it upon new markdown added.
• docs/.vitepress/en.mts and docs/.vitepress/zh.mts are the entrypoints to configure whole page menus and links, go through and change on-demand
• You can change the default layout by editing docs/.vitepress/theme/index.ts
• You can custom other layouts by adding new components and use it in front-formatter

Known Issues

1. Mermaid pie chart, ZenUML are not working due to vitepress-plugin-mermaid bug
2. Page layout is not optimized for multiple products
3. Search is local frontend by default, should change to remote search like Algolia if there are lots of contents.