diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index a26bdf54e61..b6068a1cedd 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -64,6 +64,14 @@ Below is a list of popular documentation tools that you can use to write your do Written in :bdg-info:`rust` + .. grid-item-card:: VitePress + :link: vitepress.html + + VitePress is a static site generator with a focus on performance and simplicity. + + Supported formats + :bdg-success:`md` + .. grid-item-card:: Antora :link: antora.html @@ -71,6 +79,7 @@ Below is a list of popular documentation tools that you can use to write your do Supported formats :bdg-success:`adoc` + Written in :bdg-info:`javascript` @@ -82,4 +91,5 @@ Below is a list of popular documentation tools that you can use to write your do /intro/docusaurus /intro/markdoc /intro/mdbook + /intro/vitepress /intro/antora diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst new file mode 100644 index 00000000000..f10afcb8a73 --- /dev/null +++ b/docs/user/intro/vitepress.rst @@ -0,0 +1,82 @@ +VitePress +========= + +.. meta:: + :description lang=en: Learn how to host VitePress documentation on Read the Docs. + +`VitePress`_ is a static site generator with a focus on performance and simplicity. + +Minimal configuration is required to build an existing VitePress project on Read the Docs. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + build: + os: ubuntu-lts-latest + tools: + nodejs: "latest" + jobs: + install: + - npm install vitepress + build: + html: + # The site was created by running `vitepress init` + # and following the official guide + # https://vitepress.dev/guide/getting-started + - vitepress build docs + - mkdir -p $READTHEDOCS_OUTPUT/ + - mv docs/.vitepress/dist $READTHEDOCS_OUTPUT/html + +.. _VitePress: https://vitepress.dev/ + +Getting started +--------------- + +- If you have an existing VitePress project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide. +- If you're new to VitePress, check out the official `Getting started with VitePress`_ guide. + +.. _Getting started with VitePress: https://vitepress.vuejs.org/guide/getting-started.html + +Using the proper base path +-------------------------- + +To ensure that your VitePress site works correctly on Read the Docs, +you need to set the ``base`` option in your VitePress configuration to the correct base path: + +.. code-block:: js + :caption: .vitepress/config.js + + import { defineConfig } from 'vitepress' + + // https://vitepress.dev/reference/site-config + export default defineConfig({ + // Use Canonical URL, but only the path and with no trailing / + // End result is like: `/en/latest` + base: process.env.READTHEDOCS_CANONICAL_URL + ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "") + : "", + + title: "My Awesome Project", + description: "A VitePress Site", + }) + +Example repository and demo +--------------------------- + +Production example from DbToolsBundle + https://dbtoolsbundle.readthedocs.io/en/stable/ + +Example repository + https://github.com/readthedocs/test-builds/tree/vitepress + +Demo + https://test-builds.readthedocs.io/en/vitepress/ + +Further reading +--------------- + +* `VitePress documentation`_ + +.. _VitePress documentation: https://vitepress.dev/