From 7b58df3af3cd34ddee9b8fa00f118ce376d5ac95 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Tue, 7 Mar 2023 21:29:11 +0800
Subject: [PATCH] docs: cms, mpa, using vue edits

---
 docs/guide/cms.md       | 49 +++++++++++++++++++++++++++++++++++++----
 docs/guide/mpa-mode.md  | 24 +++++++++++++++++++-
 docs/guide/using-vue.md | 16 ++++++++++----
 3 files changed, 80 insertions(+), 9 deletions(-)

diff --git a/docs/guide/cms.md b/docs/guide/cms.md
index ed6a07f7d72f..92e617506f62 100644
--- a/docs/guide/cms.md
+++ b/docs/guide/cms.md
@@ -6,10 +6,51 @@ outline: deep
 
 ## General Workflow
 
-## Integration Guides
+Connecting VitePress to a CMS will largely revolve around [Dynamic Routes](/guide/routing#dynamic-routes). Make sure to understand how it works before proceeding.
 
-If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here!
+Since each CMS will work differently, here we can only provide a generic workflow that you will need to adapt to your specific scenario.
+
+1. If your CMS requires authentication, create an `.env` file to store your API tokens and load it so:
+
+    ```js
+    // posts/[id].paths.js
+    import { loadEnv } from 'vitepress'
+
+    const env = loadEnv('', process.cwd())
+    ```
+
+2. Fetch the necessary data from the CMS and format it into proper paths data:
+
+    ```js
+    export default {
+      async paths() {
+        // use respective CMS client library if needed
+        const data = await (await fetch('https://my-cms-api', {
+          headers: {
+            // token if necessary
+          }
+        })).json()
 
-### Storyblok
+        return data.map(entry => {
+          return {
+            params: { id: entry.id, /* title, authors, date etc. */ },
+            content: entry.content
+          }
+        })
+      }
+    }
+    ```
 
-### Directus
+3. Render the content in the page:
+
+    ```md
+    # {{ $params.title }}
+
+    - by {{ $params.author }} on {{ $params.date }}
+
+    <!-- @content -->
+    ```
+
+## Integration Guides
+
+If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here!
diff --git a/docs/guide/mpa-mode.md b/docs/guide/mpa-mode.md
index e4bcd0f23f04..32c9203624ff 100644
--- a/docs/guide/mpa-mode.md
+++ b/docs/guide/mpa-mode.md
@@ -1 +1,23 @@
-# MPA Mode
+# MPA Mode <Badge type="warning" text="experimental" />
+
+MPA (Multi-Page Application) mode can be enabled via the command line via `vitepress build --mpa`, or via config through the `mpa: true` option.
+
+In MPA mode, all pages are rendered without any JavaScript included by default. As a result, the production site will likely have a better initial visit performance score from audit tools.
+
+However, due to the absence of SPA navigation, cross-page links will lead to full page reloads. Post-load navigations in MPA mode will not feel as instant as in SPA mode.
+
+Also note that no-JS-by-default also means you are essentially using Vue purely as a server-side templating language - no event handlers will be attached in the browser, so there will be no interactivity. To load client-side JavaScript, you can do so by using the special `<script client>` tag (works in both `.md` and `.vue` files, but only in MPA mode):
+
+```html
+<script client>
+document.querySelector('h1').addEventListener('click', () => {
+  console.log('client side JavaScript!')
+})
+</script>
+
+# Hello
+```
+
+Client scripts in all theme components will be bundled together, while client script for a specific page will be split for that page only.
+
+Notice that `<script client>` is **not evaluated as Vue component code**: it's processed as a plain JavaScript module. For this reason, MPA mode should only be used if your site requires absolutely minimal client-side interactivity.
diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md
index fdb5b89dd0ce..734ebd54515f 100644
--- a/docs/guide/using-vue.md
+++ b/docs/guide/using-vue.md
@@ -36,9 +36,13 @@ Directives also work (note that by design, raw HTML is also valid in Markdown):
 
 ## `<script>` and `<style>`
 
-Root-level `<script>` and `<style>` tags in Markdown files work just like they do in Vue SFCs, including `<script setup>`, `<style scoped>`, `<style module>`, etc. The main difference here is that there is no `<template>` tag: all other root-level content is Markdown.
+Root-level `<script>` and `<style>` tags in Markdown files work just like they do in Vue SFCs, including `<script setup>`, `<style module>`, etc. The main difference here is that there is no `<template>` tag: all other root-level content is Markdown. Also note that all tags should be placed **after** the frontmatter:
 
 ```html
+---
+hello: world
+---
+
 <script setup>
 import { ref } from 'vue'
 
@@ -49,16 +53,20 @@ const count = ref(0)
 
 The count is: {{ count }}
 
-<button @click="count++">Increment</button>
+<button :class="$style.module" @click="count++">Increment</button>
 
-<style scoped>
-button {
+<style module>
+.button {
   color: red;
   font-weight: bold;
 }
 </style>
 ```
 
+:::warning Avoid `<style scoped>` in Markdown
+When used in Markdown, `<style scoped>` requires adding special attributes to every element on the current page, which will significantly bloat the page size. `<style module>` is preferred when locally-scoped styling is needed in a page.
+:::
+
 You also have access to VitePress' runtime APIs such as the [`useData` helper](/reference/runtime-api#usedata), which provides access to current page's metadata:
 
 **Input**