setup tutorial src markdown support

Author: yyx990803

.gitignore

@@ -107,3 +107,4 @@ temp/
 TODOs.md
 src/api/index.json
 src/examples/data.json
+src/tutorial/data.json

package.json

@@ -12,6 +12,6 @@
   "devDependencies": {
     "@types/node": "^16.9.1",
     "cheap-watch": "^1.0.3",
-    "vitepress": "^0.20.2"
+    "vitepress": "^0.20.4"
   }
 }

pnpm-lock.yaml

@@ -15,6 +15,8 @@ exports.genExamplesData = () => {
   })
 }
 
+exports.readExample = readExample
+
 function genExamples() {
   const srcDir = path.resolve(__dirname, '../src/examples/src')
   const examples = fs.readdirSync(srcDir)

scripts/genExamplesData.js

@@ -0,0 +1,40 @@
+/**
+ * watch / generate an all-tutorial data temporary json file (ignored by Git)
+ */
+
+// @ts-check
+const fs = require('fs')
+const path = require('path')
+const { watch } = require('./watch')
+const { readExample } = require('./genExamplesData')
+const { createMarkdownRenderer } = require('vitepress')
+
+exports.genTutorialData = () => {
+  const md = createMarkdownRenderer(process.cwd())
+
+  watch({
+    src: 'tutorial/src',
+    out: 'tutorial/data.json',
+    genData: () => genTutorialSteps(md)
+  })
+}
+
+/**
+ * @param {import('vitepress').MarkdownRenderer} md
+ */
+function genTutorialSteps(md) {
+  const srcDir = path.resolve(__dirname, '../src/tutorial/src')
+  const steps = fs.readdirSync(srcDir).sort()
+  const data = {}
+
+  for (const name of steps) {
+    const step = readExample(path.join(srcDir, name))
+    const desc = step['description.md']
+    if (desc) {
+      step['description.md'] = md.render(desc).html
+    }
+
+    data[name] = step
+  }
+  return data
+}

scripts/genTutorialData.js

@@ -3,7 +3,8 @@ const fs = require('fs')
 const path = require('path')
 const { genApiIndex } = require('../../scripts/genApiIndex')
 const { genExamplesData } = require('../../scripts/genExamplesData')
-const { headerPlugin } = require('./header')
+const { genTutorialData } = require('../../scripts/genTutorialData')
+const { headerPlugin } = require('./headerMdPlugin')
 
 const nav = [
   {
@@ -460,11 +461,11 @@ const sidebar = {
       text: 'Tutorial',
       items: [
         {
-          text: '1. Hello World',
+          text: '1. Adding Data',
           link: '/tutorial/#step-1'
         },
         {
-          text: '2. Render a List',
+          text: '2. Two-way Binding',
           link: '/tutorial/#step-2'
         }
       ]
@@ -474,6 +475,7 @@ const sidebar = {
 
 genApiIndex(sidebar['/api/'])
 genExamplesData()
+genTutorialData()
 
 /**
  * @type {import('vitepress').UserConfig}

src/.vitepress/config.js

@@ -11,6 +11,7 @@ import {
 
 const route = useRoute()
 const show = computed(() => /^\/(guide|tutorial|examples)\//.test(route.path))
+const showSFC = computed(() => !/^\/guide/.test(route.path))
 const isOpen = ref(
   typeof localStorage !== 'undefined' &&
   !localStorage.getItem(preferCompositionKey)
@@ -79,7 +80,7 @@ function useToggleFn(
           @click="closeSideBar"
         >?</a>
       </div>
-      <div class="switch-container" v-if="route.path.startsWith('/examples')">
+      <div class="switch-container" v-if="showSFC">
         <label class="no-sfc-label" @click="toggleSFC(false)">HTML</label>
         <VTSwitch
           class="sfc-switch"

src/.vitepress/header.js renamed to src/.vitepress/headerMdPlugin.js

@@ -3,7 +3,7 @@ import { Repl, ReplStore } from '@vue/repl'
 import '@vue/repl/style.css'
 import data from './data.json'
 import { inject, watchEffect, version, Ref } from 'vue'
-import { resolveSFCExample, resolveNoBuildExample } from './utils'
+import { resolveSFCExample, resolveNoBuildExample, onHashChange } from './utils'
 
 const store = new ReplStore({
   defaultVueRuntimeURL: `https://unpkg.com/vue@${version}/dist/vue.esm-browser.js`
@@ -13,7 +13,7 @@ const preferComposition = inject('prefer-composition') as Ref<boolean>
 const preferSFC = inject('prefer-sfc') as Ref<boolean>
 
 watchEffect(updateExample)
-window.addEventListener('hashchange', updateExample)
+onHashChange(updateExample)
 
 /**
  * We perform some runtime logic to transform source files into different

src/.vitepress/theme/components/PreferenceSwitch.vue

@@ -1,3 +1,5 @@
+import { onBeforeUnmount } from 'vue'
+
 type ExampleData = {
   [key: string]: Record<string, string>
 } & {
@@ -66,7 +68,7 @@ function forEachComponent(
 ) {
   for (const filename in raw) {
     const content = raw[filename]
-    if (filename === 'description.txt') {
+    if (filename === 'description.txt' || filename === 'description.md') {
       continue
     } else if (typeof content === 'string') {
       files[filename] = content
@@ -93,14 +95,18 @@ function injectCreateApp(src: string): string {
   return src.replace(/export default ({[^]*\n})/, "createApp($1).mount('#app')")
 }
 
-export function resolveSFCExample(raw: ExampleData, preferComposition: boolean) {
+export function resolveSFCExample(
+  raw: ExampleData,
+  preferComposition: boolean
+) {
   const files: Record<string, string> = {}
   forEachComponent(
     raw,
     files,
     (filename, { template, composition, options, style }) => {
+      const desc = raw['description.txt']
       let sfcContent =
-        filename === 'App' ? `<!--\n${raw['description.txt']}\n-->\n\n` : ``
+        desc && filename === 'App' ? `<!--\n${desc}\n-->\n\n` : ``
       if (preferComposition) {
         sfcContent += `<script setup>\n${toScriptSetup(
           composition,
@@ -119,10 +125,14 @@ export function resolveSFCExample(raw: ExampleData, preferComposition: boolean)
   return files
 }
 
-export function resolveNoBuildExample(raw: ExampleData, preferComposition: boolean) {
+export function resolveNoBuildExample(
+  raw: ExampleData,
+  preferComposition: boolean
+) {
   const files: Record<string, string> = {}
 
-  let html = `<!--\n${raw['description.txt']}\n-->\n\n`
+  const desc = raw['description.txt']
+  let html = desc ? `<!--\n${desc})}\n-->\n\n` : ``
   let css = ''
 
   // set it first for ordering
@@ -140,7 +150,7 @@ export function resolveNoBuildExample(raw: ExampleData, preferComposition: boole
 
       if (filename === 'App') {
         html += `<script type="module">\n${injectCreateApp(js)}<\/script>`
-        html += `\n\n<div id="app">\n${_template}</div>`
+        html += `\n\n<div id="app">\n${_template}\n</div>`
       } else {
         // html += `\n\n<template id="${filename}">\n${_template}</template>`
         js = js.replace(
@@ -158,4 +168,9 @@ export function resolveNoBuildExample(raw: ExampleData, preferComposition: boole
   return files
 }
 
-
+export function onHashChange(cb) {
+  window.addEventListener('hashchange', cb)
+  onBeforeUnmount(() => {
+    window.removeEventListener('hashchange', cb)
+  })
+}

src/examples/ExampleRepl.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import { Repl, ReplStore } from '@vue/repl'
-import { inject, watchEffect, version, Ref } from 'vue'
+import { inject, watch, version, Ref, ref, computed } from 'vue'
 import data from './data.json'
-import { resolveSFCExample, resolveNoBuildExample } from '../examples/utils'
+import { resolveSFCExample, resolveNoBuildExample, onHashChange } from '../examples/utils'
 import '@vue/repl/style.css'
 
 const store = new ReplStore({
@@ -12,33 +12,80 @@ const store = new ReplStore({
 const preferComposition = inject('prefer-composition') as Ref<boolean>
 const preferSFC = inject('prefer-sfc') as Ref<boolean>
 
+const currentStep = ref('')
+
+const currentDescription = computed(() => {
+  return data[currentStep.value]?.['description.md']
+})
+
+const nextStep = computed(() => {
+  const next = `step-${parseInt(currentStep.value, 10) + 1}`
+  if (data.hasOwnProperty(next)) {
+    return next
+  }
+})
+
+const userEditedState = ref<object | null>(null)
+const buttonText = computed(() => (userEditedState.value ? 'Reset' : 'Show me!'))
+
 function updateExample() {
+  console.log('Update example triggered')
   let hash = location.hash.slice(1)
   if (!data.hasOwnProperty(hash)) {
-    hash = 'hello-world'
+    hash = 'step-1'
     location.hash = `#${hash}`
   }
+  currentStep.value = hash
+
+  const content = userEditedState.value ? data[nextStep.value] : data[hash]
+
   store.setFiles(
     preferSFC.value
-      ? resolveSFCExample(data[hash], preferComposition.value)
-      : resolveNoBuildExample(data[hash], preferComposition.value),
+      ? resolveSFCExample(content, preferComposition.value)
+      : resolveNoBuildExample(content, preferComposition.value),
     preferSFC.value ? 'App.vue' : 'index.html'
   )
 }
 
-watchEffect(updateExample)
-window.addEventListener('hashchange', updateExample)
+function toggleResult() {
+  if (userEditedState.value) {
+    store.setFiles(userEditedState.value)
+    userEditedState.value = null
+  } else {
+    userEditedState.value = store.getFiles()
+    updateExample()
+  }
+}
+
+watch([preferComposition, preferSFC], () => {
+  userEditedState.value = null
+  updateExample()
+})
+
+onHashChange(() => {
+  userEditedState.value = null
+  updateExample()
+})
+
+updateExample()
 </script>
 
 <template>
-  <div class="tutorial">
-    <div class="instruction">
-      <h1>1. Hello World</h1>
-      <p>Let's do get something on the screen!</p>
-      <p>Next Step &gt;</p>
-    </div>
-    <Repl :store="store" :showCompileOutput="false" />
-  </div>
+  <section class="tutorial">
+    <article class="instruction">
+      <div class="vt-doc" v-html="currentDescription"></div>
+      <footer class="footer">
+        <button @click="toggleResult">{{ buttonText }}</button>
+        <a v-if="nextStep" :href="`#${nextStep}`">Next Step &gt;</a>
+      </footer>
+    </article>
+    <Repl
+      :store="store"
+      :showCompileOutput="false"
+      :clearConsole="false"
+      :showImportMap="false"
+    />
+  </section>
 </template>
 
 <style scoped>
@@ -76,4 +123,9 @@ window.addEventListener('hashchange', updateExample)
     height: calc(100vh - var(--vp-nav-height) - var(--ins-height) - 48px);
   }
 }
+
+.vt-doc :deep(h1) {
+  font-size: 1.5em;
+  margin-bottom: 1em;
+}
 </style>

src/examples/utils.ts

@@ -0,0 +1,6 @@
+import { ref } from 'vue'
+
+export default {
+  name: 'App',
+  setup() {}
+}

src/tutorial/TutorialRepl.vue

@@ -0,0 +1,6 @@
+export default {
+  name: 'App',
+  data() {
+    return {}
+  }
+}