wip: more reorganization

wahid-moh · Aug 26, 2021 · a97ff2e · a97ff2e
1 parent 39fceda
commit a97ff2e
Show file tree

Hide file tree

Showing 16 changed files with 202 additions and 578 deletions.
diff --git a/package.json b/package.json
@@ -6,6 +6,7 @@
   },
   "devDependencies": {
     "@vue/theme": "vuejs/theme",
+    "sass": "^1.37.5",
     "vitepress": "^0.16.1"
   }
 }
diff --git a/src/.vitepress/config.js b/src/.vitepress/config.js
@@ -39,7 +39,6 @@ module.exports = (async () => ({
               { text: 'Tutorial', link: '/tutorial/' },
               { text: 'Examples', link: '/examples/' },
               { text: 'Style Guide', link: '/style-guide/' },
-              { text: 'Release & Versioning', link: '/release/' },
               {
                 text: 'Migration from Vue 2',
                 link: '/guide/migration/introduction'
@@ -49,10 +48,14 @@ module.exports = (async () => ({
         ]
       },
       {
-        text: 'API Reference',
+        text: 'API',
         activeMatch: `^/api/`,
         link: '/api/'
       },
+      {
+        text: 'Playground',
+        link: 'https://sfc.vuejs.org'
+      },
       {
         text: 'Ecosystem',
         items: [
@@ -131,12 +134,8 @@ module.exports = (async () => ({
           items: [
             { text: 'Introduction', link: '/guide/introduction' },
             {
-              text: 'Pick Your Learning Path',
-              link: '/guide/pick-your-learning-path'
-            },
-            {
-              text: 'Dev Environment Setup',
-              link: '/guide/dev-environment-setup'
+              text: 'Development Setup',
+              link: '/guide/dev-setup'
             }
           ]
         },
@@ -199,32 +198,14 @@ module.exports = (async () => ({
           ]
         },
         {
-          text: 'Composition API',
+          text: 'Reusability',
           items: [
             {
-              text: 'Introduction',
-              link: '/guide/composition-api-introduction'
-            },
-            {
-              text: 'Reactivity Fundamentals',
-              link: '/guide/reactivity-fundamentals'
-            },
-            {
-              text: 'Computed and Watch',
-              link: '/guide/reactivity-computed-watchers'
-            },
-            {
-              text: 'Lifecycle Hooks',
-              link: '/guide/composition-api-lifecycle-hooks'
+              text: 'Composable Functions',
+              link: '/guide/composables'
             },
-            {
-              text: 'Provide / Inject',
-              link: '/guide/composition-api-provide-inject'
-            },
-            {
-              text: 'Template Refs',
-              link: '/guide/composition-api-template-refs'
-            }
+            { text: 'Custom Directives', link: '/guide/custom-directive' },
+            { text: 'Plugins', link: '/guide/plugins' }
           ]
         },
         {
@@ -237,13 +218,6 @@ module.exports = (async () => ({
             { text: 'KeepAlive', link: '/guide/keep-alive' }
           ]
         },
-        {
-          text: 'Reusability',
-          items: [
-            { text: 'Custom Directives', link: '/guide/custom-directive' },
-            { text: 'Plugins', link: '/guide/plugins' }
-          ]
-        },
         {
           text: 'Scaling Up',
           items: [
@@ -256,44 +230,40 @@ module.exports = (async () => ({
             { text: 'State Management', link: '/guide/state-management' },
             { text: 'Testing', link: '/guide/testing' },
             {
-              text: 'Performance',
-              link: '/guide/perf'
+              text: 'Optimizing Performance',
+              link: '/guide/optimizing-performance'
             }
           ]
         },
         {
           text: 'Advanced Topics',
           items: [
-            {
-              text: 'Security',
-              link: '/guide/security'
-            },
-            {
-              text: 'Accessibility',
-              link: '/guide/a11y'
-            },
             { text: 'Reactivity in Depth', link: '/guide/reactivity' },
+            { text: 'Rendering Mechanism', link: '/guide/rendering-mechanism' },
             {
-              text: 'Reactivity Debugging',
-              link: '/guide/debugging'
+              text: 'Render Functions & JSX',
+              link: '/guide/render-fn-and-jsx'
             },
-            { text: 'Render Function & JSX', link: '/guide/render-function' },
             { text: 'Server-Side Rendering', link: '/guide/ssr' },
             {
-              text: 'Advanced Animations',
-              link: '/guide/animation'
+              text: 'Security',
+              link: '/guide/security'
             },
             {
-              text: 'Render Mechanism & Optimizations',
-              link: '/guide/optimizations'
+              text: 'Accessibility',
+              link: '/guide/a11y'
             },
             {
-              text: 'Vue and Web Components',
+              text: 'Web Components',
               link: '/guide/web-components'
             },
             {
               text: 'Building a Library for Vue',
               link: '/guide/building-a-library'
+            },
+            {
+              text: 'Advanced Animations',
+              link: '/guide/animation'
             }
             // {
             //   text: 'Vue for React Devs',
@@ -340,7 +310,10 @@ module.exports = (async () => ({
           items: [
             { text: 'Directives', link: '/api/built-in-directives' },
             { text: 'Components', link: '/api/built-in-components' },
-            { text: 'Special Attributes', link: '/api/special-attributes' }
+            {
+              text: 'Special Attributes',
+              link: '/api/built-in-special-attributes'
+            }
           ]
         },
         {
@@ -352,16 +325,13 @@ module.exports = (async () => ({
             { text: '<style> Features', link: '/api/sfc-style' }
           ]
         },
-        {
-          text: 'TypeScript',
-          items: [{ text: 'Utility Types', link: '/api/types-utility' }]
-        },
         {
           text: 'Advanced APIs',
           items: [
             { text: 'Render Function', link: '/api/render-function' },
-            { text: 'Compiler', link: '/api/compiler' },
-            { text: 'SSR', link: '/api/ssr' },
+            { text: 'TypeScript Utility Types', link: '/api/utility-types' },
+            { text: 'Server-Side Rendering', link: '/api/ssr' },
+            { text: 'Compiler Options', link: '/api/compiler' },
             { text: 'Custom Renderer', link: '/api/custom-renderer' }
           ]
         }

diff --git a/src/.vitepress/theme/api-preference.css b/src/.vitepress/theme/api-preference.css
@@ -0,0 +1,11 @@
+.composition-api {
+  display: none;
+}
+
+.prefer-composition .options-api {
+  display: none;
+}
+
+.prefer-composition .composition-api {
+  display: block;
+}
diff --git a/src/.vitepress/theme/index.ts b/src/.vitepress/theme/index.ts
@@ -1,4 +1,5 @@
 import { VPTheme } from '@vue/theme'
+import './api-preference.css'
 
 export default {
   ...VPTheme

diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md
@@ -1,4 +1,4 @@
-# Built-In Components
+# Built-in Components
 
 Built-in components can be used directly in templates without needing to be registered.
 

diff --git a/src/api/directives.md → src/api/built-in-directives.md b/src/api/directives.md → src/api/built-in-directives.md
@@ -1,4 +1,4 @@
-# Directives
+# Built-in Directives
 
 ## v-text
 

diff --git a/src/api/special-attributes.md → src/api/built-in-special-attributes.md b/src/api/special-attributes.md → src/api/built-in-special-attributes.md
@@ -1,4 +1,4 @@
-# Special Attributes
+# Built-in Special Attributes
 
 ## key
 

diff --git a/src/api/index.md b/src/api/index.md
@@ -3,6 +3,8 @@ sidebar: false
 page: true
 ---
 
+// TODO render all API items on this page
+
 <script setup>
 import { useData } from 'vitepress'
 

diff --git a/src/api/sfc-tooling.md b/src/api/sfc-tooling.md
@@ -17,35 +17,24 @@ It is also recommended to use these online playgrounds to provide reproductions
 
 ### Vite
 
-[Vite](https://vitejs.dev/) is a lightweight and fast build tool with first-class Vue SFC support. It is created by Evan You, who is also the author of Vue itself! To get started with Vite + Vue, simply run:
+[Vite](https://vitejs.dev/) is a lightweight and fast build tool with first-class Vue SFC support. It is created by Evan You, who is also the author of Vue itself!
+
+To get started with Vite + Vue, simply run:
 
 ```sh
-npm init vite@latest
+npm init vue@latest
 ```
 
-Then select the Vue template and follow the instructions.
+Then follow the instructions to select desired features.
 
 - To learn more about Vite, check out the [Vite docs](https://vitejs.dev/guide/).
 - To configure Vue-specific behavior in a Vite project, for example passing options to the Vue compiler, check out the docs for [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#readme).
 
-The [SFC Playground](https://sfc.vuejs.org/) also supports downloading the files as a Vite project.
+Both online playgrounds mentioned above also support downloading files as a Vite project.
 
 ### Vue CLI
 
-[Vue CLI](https://cli.vuejs.org/) is the official webpack-based build tool for Vue projects. To get started with Vue CLI:
-
-```sh
-npm install -g @vue/cli
-vue create hello-vue
-```
-
-- To learn more about Vue CLI, check out [Vue CLI docs](https://cli.vuejs.org/guide/installation.html).
-
-### Vite or Vue CLI?
-
-We recommend starting new projects with Vite as it offers significantly better development experience in terms of dev server startup and HMR update performance ([details](https://vitejs.dev/guide/why.html)). Only go with Vue CLI if you rely on specific webpack features (e.g. Module Federation).
-
-If you are a [Rollup](https://rollupjs.org/) user, you can safely adopt Vite as it uses Rollup for production builds and supports a Rollup-compatible plugin system. [Even Rollup's maintainer recommends Vite as THE web development wrapper for Rollup](https://twitter.com/lukastaegert/status/1412119729431584774).
+[Vue CLI](https://cli.vuejs.org/) is the official webpack-based toolchain for Vue. It is now in maintenance mode and we recommend starting new prjects with Vite unless you rely on specific webpack-only features.
 
 ## IDE Support
 
@@ -71,7 +60,10 @@ Custom blocks are compiled into imports to the same Vue file with different requ
 
 - If using Vue CLI or plain webpack, a webpack loader should be configured to transform the matched blocks. [[Example](https://vue-loader.vuejs.org/guide/custom-blocks.html#custom-blocks)]
 
-## Lower-Level Tools
+## Backend Framework Integrations
+
+// TODO
+## Lower-Level Packages
 
 ### `@vue/compiler-sfc`
 
@@ -98,4 +90,4 @@ The official loader that provides Vue SFC support in webpack. If you are using V
 - [VueUse Playground](https://play.vueuse.org)
 - [Vue + Vite on Repl.it](https://replit.com/@templates/VueJS-with-Vite)
 - [Vue on CodeSandbox](https://codesandbox.io/s/vue-3)
-- [Vue on Codepen](https://codepen.io/pen/editor/vue)
+- [Vue on Codepen](https://codepen.io/pen/editor/vue)
diff --git a/src/guide/dev-setup.md b/src/guide/dev-setup.md
@@ -0,0 +1,61 @@
+# Development Setup
+
+## No Build Tool
+
+All you need is an HTML file with the following:
+
+```html
+<script type="module">
+  import { createApp } from 'https://unpkg.com/vue/dist/vue.esm-browser.js'
+
+  createApp({
+    // component logic
+  }).mount('#app')
+</script>
+
+<div id="app">
+  <!-- component template -->
+</div>
+```
+
+## With Build Tool
+
+To leverage Vue [Single File Components](/guide/single-file-component) (SFCs), a build setup is required. The official Vue build setup is based on [Vite](https://vitejs.dev), a modern build tool that is lightweight and extremely fast.
+
+### Online
+
+You can try Vue SFCs online on [StackBlitz](https://vite.new/vue). StackBlitz runs the Vite-based build setup directly in the browser, so it is almost identical to the local setup but doesn't require installing anything on your machine.
+
+### Local
+
+:::tip Pre-requisites
+- Familiarity with the command line
+- Install [Node.js](https://nodejs.org/)
+:::
+
+```sh
+npm init vue@latest
+```
+
+This command will download and run [create-vue](https://github.com/vuejs/create-vue). It will walk you through a few questions to scaffold a production-ready Vue project. For more details on Vue-related tooling, check out the [SFC Tooling](/api/sfc-tooling.html) section.
+
+## IDE Setup
+
+- Recommended: [Visual Studio Code](https://code.visualstudio.com/) + [Volar extension](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)
+- Also viable: [JetBrains WebStorm](https://www.jetbrains.com/webstorm/)
+
+While almost all editors can support syntax highlighting for Vue components, most of them lack the level of Intellisense / refactoring support the above solutions provide (especially with TypeScript).
+
+## Browser Devtools Extension
+
+// TODO screenshot
+
+// TODO explain what devtool does
+
+- [Chrome Extension](https://chrome.google.com/webstore/detail/vuejs-devtools/ljjemllljcmogpfapbkkighbhhppjdbg)
+- [Firefox Addon](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
+- [Standalone Electron app](https://github.com/vuejs/vue-devtools/blob/dev/packages/shell-electron/README.md)
+
+## Next Steps
+
+// TODO link to guide / tutorial / playground