From 7d8be83b733a19e0368b39840fa12254608a1f82 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 22 Jan 2025 15:20:28 -0800 Subject: [PATCH 1/5] Add vitepress doc page I fixed the test-builds repo to work properly, and this also links out to a user example repo, but I want to improve that probably with a logo. --- docs/user/intro/doctools.rst | 11 +++++++ docs/user/intro/vitepress.rst | 60 +++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/user/intro/vitepress.rst diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 7247395c28a..7338d528a07 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -65,6 +65,16 @@ 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` + Written in + :bdg-info:`javascript` + .. toctree:: :hidden: @@ -73,3 +83,4 @@ Below is a list of popular documentation tools that you can use to write your do /intro/docusaurus /intro/markdoc /intro/mdbook + /intro/vitepress diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst new file mode 100644 index 00000000000..38ff0bd80b4 --- /dev/null +++ b/docs/user/intro/vitepress.rst @@ -0,0 +1,60 @@ +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: + # 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/ + +.. button-link:: https://dbtoolsbundle.readthedocs.io/en/stable/ + + DbToolsBundle uses VitePress and Read the Docs + +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 + + +Example repository and demo +--------------------------- + +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.vuejs.org/ From ece0f89b9ae604bf9e13e55b1ec895e8637e04c0 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 22 Jan 2025 15:24:57 -0800 Subject: [PATCH 2/5] Fancier link --- docs/user/intro/vitepress.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst index 38ff0bd80b4..b1207304c2e 100644 --- a/docs/user/intro/vitepress.rst +++ b/docs/user/intro/vitepress.rst @@ -31,8 +31,10 @@ Minimal configuration is required to build an existing VitePress project on Read .. _VitePress: https://vitepress.dev/ .. button-link:: https://dbtoolsbundle.readthedocs.io/en/stable/ + :color: secondary - DbToolsBundle uses VitePress and Read the Docs + + 🔗 DbToolsBundle uses VitePress and Read the Docs Getting started --------------- From b576b00e8799a045c5142593fc2e1b7f83c90611 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 22 Jan 2025 15:55:46 -0800 Subject: [PATCH 3/5] Add basepath logic --- docs/user/intro/vitepress.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst index b1207304c2e..510affcacc7 100644 --- a/docs/user/intro/vitepress.rst +++ b/docs/user/intro/vitepress.rst @@ -44,6 +44,28 @@ Getting started .. _Getting started with VitePress: https://vitepress.vuejs.org/guide/getting-started.html +Using the proper basepath +------------------------- + +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 --------------------------- From de1dd0d1820ec87beda0968a78a64f0837e66182 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 22 Jan 2025 19:10:12 -0800 Subject: [PATCH 4/5] Consistnet url --- docs/user/intro/vitepress.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst index 510affcacc7..80259f110d5 100644 --- a/docs/user/intro/vitepress.rst +++ b/docs/user/intro/vitepress.rst @@ -33,7 +33,6 @@ Minimal configuration is required to build an existing VitePress project on Read .. button-link:: https://dbtoolsbundle.readthedocs.io/en/stable/ :color: secondary - 🔗 DbToolsBundle uses VitePress and Read the Docs Getting started @@ -81,4 +80,4 @@ Further reading * `VitePress documentation`_ -.. _VitePress documentation: https://vitepress.vuejs.org/ +.. _VitePress documentation: https://vitepress.dev/ From 8a11debfbe52bbe1b1fbee8672712813b655f48f Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 23 Jan 2025 07:56:05 -0800 Subject: [PATCH 5/5] Address review feedback --- docs/user/intro/vitepress.rst | 39 +++++++++++++++++------------------ 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/user/intro/vitepress.rst b/docs/user/intro/vitepress.rst index 80259f110d5..f10afcb8a73 100644 --- a/docs/user/intro/vitepress.rst +++ b/docs/user/intro/vitepress.rst @@ -14,27 +14,23 @@ Minimal configuration is required to build an existing VitePress project on Read version: 2 build: - os: ubuntu-lts-latest - tools: - nodejs: "latest" - jobs: - install: - - npm install vitepress - build: - # 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 + 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/ -.. button-link:: https://dbtoolsbundle.readthedocs.io/en/stable/ - :color: secondary - - 🔗 DbToolsBundle uses VitePress and Read the Docs - Getting started --------------- @@ -43,8 +39,8 @@ Getting started .. _Getting started with VitePress: https://vitepress.vuejs.org/guide/getting-started.html -Using the proper basepath -------------------------- +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: @@ -69,6 +65,9 @@ you need to set the ``base`` option in your VitePress configuration to the corre Example repository and demo --------------------------- +Production example from DbToolsBundle + https://dbtoolsbundle.readthedocs.io/en/stable/ + Example repository https://github.com/readthedocs/test-builds/tree/vitepress