different headers for comp/options apis

Author: yyx990803

src/.vitepress/config.js

@@ -3,6 +3,7 @@ const fs = require('fs')
 const path = require('path')
 const { genApiIndex } = require('../../scripts/genApiIndex')
 const { genExamplesData } = require('../../scripts/genExamplesData')
+const { headerPlugin } = require('./header')
 
 const nav = [
   {
@@ -521,6 +522,12 @@ module.exports = {
     ]
   ],
 
+  markdown: {
+    config(md) {
+      md.use(headerPlugin)
+    }
+  },
+
   themeConfig: {
     logo: '/logo.svg',
     repo: 'vuejs/docs',

src/.vitepress/header.js

@@ -0,0 +1,39 @@
+/**
+ * A markdown-it plugin to support custom header metadata
+ * Headers that end with * are Options API only
+ * Headers that end with ** are Composition API only
+ * This plugin strips the markers and augments the extracted header data,
+ * which can be then used by the theme to filter headers.
+ *
+ * TODO: we will likely also need special syntax for preserving the same anchor
+ * links across translations similar to the one at
+ * https://github.com/vitejs/docs-cn/tree/main/.vitepress/markdown-it-custom-anchor
+ */
+
+exports.headerPlugin = (md) => {
+  const originalOpen = md.renderer.rules.heading_open
+  md.renderer.rules.heading_open = (tokens, i, ...rest) => {
+    for (const child of tokens[i + 1].children) {
+      if (child.type === 'text' && child.content.endsWith('*')) {
+        child.content = child.content.replace(/\s*\*+$/, '')
+      }
+    }
+    return originalOpen.call(null, tokens, i, ...rest)
+  }
+
+  md.renderer.rules.heading_close = (tokens, i, options, env, self) => {
+    const headers = md.__data?.headers
+    if (headers) {
+      const last = headers[headers.length - 1]
+      if (last.title.endsWith('*')) {
+        if (last.title.endsWith('**')) {
+          last.compositionOnly = true
+        } else {
+          last.optionsOnly = true
+        }
+        last.title = last.title.replace(/\s*\*+$/, '')
+      }
+    }
+    return self.renderToken(tokens, i, options)
+  }
+}

src/.vitepress/theme/components/preferences.ts

@@ -1,3 +1,4 @@
+import { Header } from 'vitepress'
 import { ref } from 'vue'
 
 const hasStorage = typeof localStorage !== 'undefined'
@@ -11,3 +12,16 @@ export const preferComposition = ref(get(preferCompositionKey))
 
 export const preferSFCKey = 'vue-docs-prefer-sfc'
 export const preferSFC = ref(get(preferSFCKey, true))
+
+// headers are augmented via the md plugin in ../header.js
+type AugmentedHeader = Header & {
+  compositionOnly?: boolean
+  optionsOnly?: boolean
+}
+
+export function filterHeadersByPreference(headers: AugmentedHeader[]) {
+  const enableComp = preferComposition.value
+  return headers.filter((h) => {
+    return enableComp ? !h.optionsOnly : !h.compositionOnly
+  })
+}

src/.vitepress/theme/index.ts

@@ -1,7 +1,11 @@
 import { h } from 'vue'
 import { VPTheme, VTBadge } from '@vue/theme'
 import PreferenceSwitch from './components/PreferenceSwitch.vue'
-import { preferComposition, preferSFC } from './components/preferences'
+import {
+  preferComposition,
+  preferSFC,
+  filterHeadersByPreference
+} from './components/preferences'
 import './styles/inline-demo.css'
 import './styles/options-boxes.css'
 
@@ -15,5 +19,6 @@ export default Object.assign({}, VPTheme, {
     app.component('Badge', VTBadge)
     app.provide('prefer-composition', preferComposition)
     app.provide('prefer-sfc', preferSFC)
+    app.provide('filter-headers', filterHeadersByPreference)
   }
 })

src/guide/advanced/reactivity-in-depth.md

@@ -313,33 +313,3 @@ A `render` function is conceptually very similar to a `computed` property. Vue d
 <div class="reactivecontent">
   <!-- <common-codepen-snippet title="Second Reactivity with Proxies in Vue 3 Explainer" slug="wvgqyJK" tab="result" theme="light" :height="500" :editable="false" :preview="false" /> -->
 </div>
-
-## Additional Details
-
-### Computed amd Watcher Debugging
-
-It's great that a computed property automatically tracks its reactive dependencies, but in some cases we may want to figure out exactly what is being tracked, or what is causing it to re-compute. We can do that by passing `computed()` a second options object with `onTrack` and `onTrigger` callbacks:
-
-- `onTrack` will be called when a reactive property or ref is tracked as a dependency.
-- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency.
-
-Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
-
-```js
-const plusOne = computed(() => count.value + 1, {
-  onTrack(e) {
-    // triggered when count.value is tracked as a dependency
-    debugger
-  },
-  onTrigger(e) {
-    // triggered when count.value is mutated
-    debugger
-  }
-})
-
-// access plusOne, should trigger onTrack
-console.log(plusOne.value)
-
-// mutate count.value, should trigger onTrigger
-count.value++
-```

src/guide/essentials/computed.md

@@ -188,6 +188,38 @@ In comparison, a method invocation will **always** run the function whenever a r
 
 Why do we need caching? Imagine we have an expensive computed property `list`, which requires looping through a huge array and doing a lot of computations. Then we may have other computed properties that in turn depend on `list`. Without caching, we would be executing `list`’s getter many more times than necessary! In cases where you do not want caching, use a method call instead.
 
+<div class="composition-api">
+
+## Computed Debugging **
+
+It's great that a computed property automatically tracks its reactive dependencies, but in some cases we may want to figure out exactly what is being tracked, or what is causing it to re-compute. We can do that by passing `computed()` a second options object with `onTrack` and `onTrigger` callbacks:
+
+- `onTrack` will be called when a reactive property or ref is tracked as a dependency.
+- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency.
+
+Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
+
+```js
+const plusOne = computed(() => count.value + 1, {
+  onTrack(e) {
+    // triggered when count.value is tracked as a dependency
+    debugger
+  },
+  onTrigger(e) {
+    // triggered when count.value is mutated
+    debugger
+  }
+})
+
+// access plusOne, should trigger onTrack
+console.log(plusOne.value)
+
+// mutate count.value, should trigger onTrigger
+count.value++
+```
+
+</div>
+
 ## Writable Computed
 
 Computed properties are by default getter-only. When you attempt to mutate a computed property, you will receive a runtime warning. In the rare cases where you need a "writable" computed property, you can create one by providing both a getter and a setter:

src/guide/essentials/reactivity-fundamentals.md

@@ -4,10 +4,10 @@
 This section contains different content for Options API and Composition API. Your current preference is <span class="options-api">Options API</span><span class="composition-api">Composition API</span>. You can toggle between the API styles using the "API Preference" switches at the top of the left sidebar.
 :::
 
-## Declaring State
-
 <div class="options-api">
 
+## Declaring Reactive State *
+
 With Options API, we use the `data` option to declare reactive state of a component. The option value should be a function that returns an object. Vue will call the function when creating a new component instance, and wrap the returned object in its reactivity system. The wrapped object is stored on the component instance as `$data`. For convenience, any top-level properties of that object are also exposed directly on the component instance (`this` in methods and lifecycle hooks):
 
 ```js
@@ -45,7 +45,7 @@ Vue uses a `$` prefix when exposing its own built-in APIs via the component inst
 
 <div class="composition-api">
 
-### Reactive Variables with `ref`
+## Reactive Variables with `ref` **
 
 The primary API for declaring reactive state when using Composition API is the [`ref()`](/api/reactivity-core.html#ref) method:
 
@@ -106,7 +106,7 @@ There are two reasons why we need to wrap the value in an object:
 
    This capability is quite important as it is frequently used when extracting logic into [Composable Functions](/guide/reusability/composables.html).
 
-### Exposing State to Template
+## Exposing State to Template **
 
 To use refs in a component's template, declare and return them from a component's `setup()` function:
 
@@ -150,7 +150,7 @@ Top-level imports and variables declared in `<script setup>` are automatically u
 
 > For the rest of the guide, we will be primarily using SFC + `<script setup>` syntax for Composition API code examples, as that is the most common usage for Vue developers.
 
-### Reactive Objects with `reactive`
+## Reactive Objects with `reactive` **
 
 It is also possible to directly create a reactive object or array with the [`reactive()`](/api/reactivity-core.html#reactive) method:
 
@@ -274,7 +274,7 @@ In the example above, the method `increment` will be called when the `<button>`
 
 <div class="composition-api">
 
-To declare methods when using Composition API, simply declare functions in the same scope with the reactive state:
+We can declare functions that mutate reactive state in the same scope, and expose it as a method alongside the state:
 
 ```js
 import { ref } from 'vue'
@@ -297,7 +297,7 @@ export default {
 }
 ```
 
-Methods are typically used as event listeners:
+Exposed methods are typically used as event listeners:
 
 ```vue-html
 <button @click="increment">{{ count }}</button>
@@ -386,7 +386,7 @@ function mutateDeeply() {
 
 </div>
 
-It is also possible to explicitly create [shallow refs](<(/api/reactivity-advanced.html#shallowref)>) and [shallow reactive objects](/api/reactivity-advanced.html#shallowreactive) where the reactivity is only tracked at the root-level, however they are typically only needed in advanced use cases.
+It is also possible to explicitly create [shallow refs](/api/reactivity-advanced.html#shallowref) and [shallow reactive objects](/api/reactivity-advanced.html#shallowreactive) where the reactivity is only tracked at the root-level, however they are typically only needed in advanced use cases.
 
 <div class="options-api">
 
@@ -442,7 +442,7 @@ app.component('save-button', {
 
 <div class="composition-api">
 
-### Ref Transform <Badge type="warning" text="experimental" />
+## Ref Transform <Badge type="warning" text="experimental" /> **
 
 Refs require the `.value` property due to the language constraints of JavaScript. However, with compile-time transforms we can improve the ergonomics by automatically appending `.value` in appropriate locations. The [ref transform](https://github.com/vuejs/vue-next/tree/master/packages/ref-transform) allows us to write the above example like this:
 

src/guide/essentials/watchers.md

@@ -319,10 +319,10 @@ watchPostEffect(() => {
 })
 ```
 
-</div>
+## Side Effect Invalidation **
 
-## Side Effect Invalidation
+## Stopping a Watcher **
 
-## Stopping a Watcher
+## Watcher Debugging **
 
-## Watcher Debugging
+</div>