diff --git a/.github/contributing/writing-guide.md b/.github/contributing/writing-guide.md index 5f4aa07d0c..a686f0924e 100644 --- a/.github/contributing/writing-guide.md +++ b/.github/contributing/writing-guide.md @@ -10,15 +10,15 @@ Writing documentation is an exercise in empathy. We're not describing an objecti - Cognitive capacity is **depleted more slowly** when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the document can help keep them in this state. - **Always try to see from the user's perspective.** When we understand something thoroughly, it becomes obvious to us. This is called _the curse of knowledge_. In order to write good documentation, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? Good documentation meets users where they are. It can be helpful to practice explaining the concept to people in person before. - **Describe the _problem_ first, then the solution.** Before showing how a feature works, it's important to explain why it exists. Otherwise, users won't have the context to know if this information is important to them (is it a problem they experience?) or what prior knowledge/experience to connect it to. -- **While writing, don't be afraid to ask questions**, _especially_ if you're afraid they might be "dumb". Being vulnerable is hard, but it's the only way for us to more fully understand what we need to explain. -- **Be involved in feature discussions.** The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions (especially "dumb" questions) earlier often helps reveal confusions, inconsistencies, and problematic behavior before a breaking change would be required to fix them. +- **While writing, don't be afraid to ask questions**, _especially_ if you're afraid that your questions might be "foolish". Being vulnerable is hard, but it's the only way for us to more fully understand what we need to explain. +- **Be involved in feature discussions.** The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions (especially "foolish" questions) earlier often helps reveal confusions, inconsistencies, and problematic behavior before a breaking change would be required to fix them. ## Organization - **Installation/Integration**: Provide a thorough overview of how to integrate the software into as many different kinds of projects as necessary. - **Introduction/Getting Started**: - Provide a less than 10 minute overview of the problems the project solves and why it exists. - - Provide a less than 30 minute overview of the problems the project solves and how, including when and why to use the project and some simple code examples. At the end, link to both to Installation page and the beginning of the Essentials Guide. + - Provide a less than 30 minute overview of the problems the project solves and how, including when and why to use the project and some simple code examples. At the end, link to both the Installation page and the beginning of the Essentials Guide. - **Guide**: Make users feel smart, powerful, and curious, then maintain this state so that users maintain the motivation and cognitive capacity to keep learning more. Guide pages are meant to be read sequentially, so should generally be ordered from the highest to lowest power/effort ratio. - **Essentials**: It should take no longer than 5 hours to read the Essentials, though shorter is better. Its goal is to provide the 20% of knowledge that will help users handle 80% of use cases. Essentials can link to more advanced guides and the API, though, in most cases, you should avoid such links. When they are provided, you need also provide a context so users are aware if they should follow this link on their first reading. Otherwise, many users end up exhausting their cognitive capacity link-hopping, trying to fully learn every aspect of a feature before moving on, and as a result, never finish that first read-through of the Essentials. Remember that a smooth read is more important than being thorough. We want to give people the information they need to avoid a frustrating experience, but they can always come back and read further, or Google a less common problem when they encounter it. - **Advanced**: While the Essentials helps people handle ~80% of use cases, subsequent guides help get users to 95% of use cases, plus more detailed information on non-essential features (e.g. transitions, animations), more complex convenience features (e.g. mixins, custom directives), and dev experience improvements (e.g. JSX, plugins). The final 5% of use cases that are more niche, complex, and/or prone to abuse will be left to the cookbook and API reference, which can be linked to from these advanced guides. @@ -59,9 +59,9 @@ Writing documentation is an exercise in empathy. We're not describing an objecti - **When referencing a directly following example, use a colon (`:`) to end a sentence**, rather than a period (`.`). - **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](./oxford-comma.jpg) - Source: [The Serial (Oxford) Comma: When and Why To Use It](https://www.inkonhand.com/2015/10/the-serial-oxford-comma-when-and-why-to-use-it/) -- **When referencing the name of a project, use the name that project refers to itself as.** For example, "webpack" and "npm" should both use lowercase as that's how their documentation refers to them. +- **When referencing the name of a project, use the name that the project refers to itself as.** For example, "webpack" and "npm" should both use lowercase as that's how their documentation refers to them. - **Use Title Case for headings** - at least for now, since it's what we use through the rest of the docs. There's research suggesting that sentence case (only first word of the heading starts with a capital) is actually superior for legibility and also reduces the cognitive overhead for documentation writers, since they don't have to try to remember whether to capitalize words like "and", "with", and "about". -- **Don't use emojis (except in discussions).** Emojis are cute and friendly, but they can be a distraction in documentation and some emoji even convey different meanings in different cultures. +- **Don't use emojis (except in discussions).** Emojis are cute and friendly, but they can be a distraction in documentation and some emojis even convey different meanings in different cultures. ## Iteration & Communication @@ -85,11 +85,11 @@ Writing documentation is an exercise in empathy. We're not describing an objecti ### Tips, Callouts, Alerts, and Line Highlights -We have some dedicated styles to denote something that's worth highlighting in a particular way. These are captured [on this page](https://v3.vuejs.org/guide/doc-style-guide.html#alerts). **They are to be used sparingly.** +We have some dedicated styles to denote something that's worth highlighting in a particular way. These are captured [on this page](https://vitepress.dev/guide/markdown#custom-containers). **They are to be used sparingly.** -There is a certain temptation to abuse these styles, as one can simply add a change inside a callout. However, this breaks up the flow of reading for the user, and thus, should only be used in special circumstances. Wherever possible, we should attempt to create a narrative and flow within the page to respect the readers cognitive load. +There is a certain temptation to abuse these styles, as one can simply add a change inside a callout. However, this breaks up the flow of reading for the user and should only be used in special circumstances. Wherever possible, we should attempt to create a narrative and flow within the page to respect the reader's cognitive load. -Under no circumstances should 2 alerts be used next to one another, it's a sign that we're not able to explain context well enough. +Under no circumstances should two alerts be used next to one another, it's a sign that we're not able to explain context well enough. ### Contributing diff --git a/.gitignore b/.gitignore index b4a9415240..e52da2f480 100644 --- a/.gitignore +++ b/.gitignore @@ -95,8 +95,10 @@ pnpm-global # rollup.js default build output dist/ -# vuepress build output -.vuepress/dist +# vitepress build output +.vitepress/dist +.vitepress/cache +.vitepress/.temp # Serverless directories .serverless/ @@ -109,3 +111,6 @@ src/api/index.json src/examples/data.json src/tutorial/data.json draft.md + +# folders created by IDE +.idea diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000000..e941d13c20 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +package-manager-strict=false diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000000..65a7d0588f --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +*.vue diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 495605c288..80c74de089 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -1,11 +1,13 @@ import fs from 'fs' import path from 'path' -import { defineConfigWithTheme } from 'vitepress' +import { defineConfigWithTheme, type HeadConfig, type Plugin } from 'vitepress' import type { Config as ThemeConfig } from '@vue/theme' +import llmstxt from 'vitepress-plugin-llms' import baseConfig from '@vue/theme/config' import { headerPlugin } from './headerMdPlugin' +// import { textAdPlugin } from './textAdMdPlugin' -const nav = [ +const nav: ThemeConfig['nav'] = [ { text: 'Docs', activeMatch: `^/(guide|style-guide|cookbook|examples)/`, @@ -14,7 +16,13 @@ const nav = [ { text: 'Tutorial', link: '/tutorial/' }, { text: 'Examples', link: '/examples/' }, { text: 'Quick Start', link: '/guide/quick-start' }, - { text: 'Style Guide', link: '/style-guide/' }, + // { text: 'Style Guide', link: '/style-guide/' }, + { text: 'Glossary', link: '/glossary/' }, + { text: 'Error Reference', link: '/error-reference/' }, + { + text: 'Vue 2 Docs', + link: 'https://v2.vuejs.org/' + }, { text: 'Migration from Vue 2', link: 'https://v3-migration.vuejs.org/' @@ -28,7 +36,7 @@ const nav = [ }, { text: 'Playground', - link: 'https://sfc.vuejs.org/' + link: 'https://play.vuejs.org/' }, { text: 'Ecosystem', @@ -37,12 +45,26 @@ const nav = [ { text: 'Resources', items: [ - { text: 'Partners', link: '/ecosystem/partners' }, + { text: 'Partners', link: '/partners/' }, + { text: 'Developers', link: '/developers/' }, { text: 'Themes', link: '/ecosystem/themes' }, + { text: 'UI Components', link: 'https://ui-libs.vercel.app/' }, + { + text: 'Certification', + link: 'https://certificates.dev/vuejs/?ref=vuejs-nav' + }, { text: 'Jobs', link: 'https://vuejobs.com/?ref=vuejs' }, { text: 'T-Shirt Shop', link: 'https://vue.threadless.com/' } ] }, + { + text: 'Official Libraries', + items: [ + { text: 'Vue Router', link: 'https://router.vuejs.org/' }, + { text: 'Pinia', link: 'https://pinia.vuejs.org/' }, + { text: 'Tooling Guide', link: '/guide/scaling-up/tooling.html' } + ] + }, { text: 'Video Courses', items: [ @@ -63,7 +85,10 @@ const nav = [ text: 'Discord Chat', link: 'https://discord.com/invite/HBherRA' }, - { text: 'Forum', link: 'https://forum.vuejs.org/' }, + { + text: 'GitHub Discussions', + link: 'https://github.com/vuejs/core/discussions' + }, { text: 'DEV Community', link: 'https://dev.to/t/vue' } ] }, @@ -72,8 +97,8 @@ const nav = [ items: [ { text: 'Blog', link: 'https://blog.vuejs.org/' }, { text: 'Twitter', link: 'https://twitter.com/vuejs' }, - { text: 'Newsletter', link: 'https://news.vuejs.org/' }, - { text: 'Events', link: 'https://events.vuejs.org/' } + { text: 'Events', link: 'https://events.vuejs.org/' }, + { text: 'Newsletters', link: '/ecosystem/newsletters' } ] } ] @@ -90,6 +115,7 @@ const nav = [ link: '/about/community-guide' }, { text: 'Code of Conduct', link: '/about/coc' }, + { text: 'Privacy Policy', link: '/about/privacy' }, { text: 'The Documentary', link: 'https://www.youtube.com/watch?v=OrxmtDw4pVI' @@ -99,10 +125,19 @@ const nav = [ { text: 'Sponsor', link: '/sponsor/' + }, + { + text: 'Experts', + badge: { text: 'NEW' }, + activeMatch: `^/(partners|developers)/`, + items: [ + { text: 'Partners', link: '/partners/' }, + { text: 'Developers', link: '/developers/', badge: { text: 'NEW' } } + ] } ] -export const sidebar = { +export const sidebar: ThemeConfig['sidebar'] = { '/guide/': [ { text: 'Getting Started', @@ -147,15 +182,15 @@ export const sidebar = { link: '/guide/essentials/event-handling' }, { text: 'Form Input Bindings', link: '/guide/essentials/forms' }, - { - text: 'Lifecycle Hooks', - link: '/guide/essentials/lifecycle' - }, { text: 'Watchers', link: '/guide/essentials/watchers' }, { text: 'Template Refs', link: '/guide/essentials/template-refs' }, { text: 'Components Basics', link: '/guide/essentials/component-basics' + }, + { + text: 'Lifecycle Hooks', + link: '/guide/essentials/lifecycle' } ] }, @@ -168,6 +203,7 @@ export const sidebar = { }, { text: 'Props', link: '/guide/components/props' }, { text: 'Events', link: '/guide/components/events' }, + { text: 'Component v-model', link: '/guide/components/v-model' }, { text: 'Fallthrough Attributes', link: '/guide/components/attrs' @@ -292,16 +328,11 @@ export const sidebar = { { text: 'Animation Techniques', link: '/guide/extras/animation' - }, - { - text: 'Reactivity Transform', - link: '/guide/extras/reactivity-transform' } // { // text: 'Building a Library for Vue', // link: '/guide/extras/building-a-library' // }, - // { text: 'Custom Renderers', link: '/guide/extras/custom-renderer' }, // { // text: 'Vue for React Devs', // link: '/guide/extras/vue-for-react-devs' @@ -343,6 +374,10 @@ export const sidebar = { { text: 'Dependency Injection', link: '/api/composition-api-dependency-injection' + }, + { + text: 'Helpers', + link: '/api/composition-api-helpers' } ] }, @@ -382,7 +417,7 @@ export const sidebar = { ] }, { - text: 'Single File Component', + text: 'Single-File Component', items: [ { text: 'Syntax Specification', link: '/api/sfc-spec' }, { text: ' + + + + diff --git a/.vitepress/theme/components/CardList.vue b/.vitepress/theme/components/CardList.vue new file mode 100644 index 0000000000..e29722bf13 --- /dev/null +++ b/.vitepress/theme/components/CardList.vue @@ -0,0 +1,105 @@ + + + + + diff --git a/.vitepress/theme/components/Home.vue b/.vitepress/theme/components/Home.vue index eb0e73cc2f..f5fb2f6dc7 100644 --- a/.vitepress/theme/components/Home.vue +++ b/.vitepress/theme/components/Home.vue @@ -1,10 +1,17 @@ diff --git a/.vitepress/theme/components/NewsLetter.vue b/.vitepress/theme/components/NewsLetter.vue index 43de4c2f6e..c3bd08f3e4 100644 --- a/.vitepress/theme/components/NewsLetter.vue +++ b/.vitepress/theme/components/NewsLetter.vue @@ -46,7 +46,7 @@ import { VTLink } from '@vue/theme' no-icon >news.vuejs.org. You may also go social at Twitter, or join our home at - Discord. + Discord.

diff --git a/src/ecosystem/partners/PartnerHero.vue b/.vitepress/theme/components/PageHero.vue similarity index 50% rename from src/ecosystem/partners/PartnerHero.vue rename to .vitepress/theme/components/PageHero.vue index 3fb4150d34..084eae0866 100644 --- a/src/ecosystem/partners/PartnerHero.vue +++ b/.vitepress/theme/components/PageHero.vue @@ -1,66 +1,63 @@ - - diff --git a/.vitepress/theme/components/PageShowcaseListLayout.vue b/.vitepress/theme/components/PageShowcaseListLayout.vue new file mode 100644 index 0000000000..ea223eff28 --- /dev/null +++ b/.vitepress/theme/components/PageShowcaseListLayout.vue @@ -0,0 +1,112 @@ + + + + + diff --git a/.vitepress/theme/components/PreferenceSwitch.vue b/.vitepress/theme/components/PreferenceSwitch.vue index 85ffb646c3..b16403405c 100644 --- a/.vitepress/theme/components/PreferenceSwitch.vue +++ b/.vitepress/theme/components/PreferenceSwitch.vue @@ -1,24 +1,25 @@ + + + + diff --git a/.vitepress/theme/components/ScrimbaLink.vue b/.vitepress/theme/components/ScrimbaLink.vue new file mode 100644 index 0000000000..1fb6021610 --- /dev/null +++ b/.vitepress/theme/components/ScrimbaLink.vue @@ -0,0 +1,59 @@ + + + \ No newline at end of file diff --git a/.vitepress/theme/components/SecurityUpdateBtn.vue b/.vitepress/theme/components/SecurityUpdateBtn.vue new file mode 100644 index 0000000000..cfd8ceb291 --- /dev/null +++ b/.vitepress/theme/components/SecurityUpdateBtn.vue @@ -0,0 +1,63 @@ + + + + + diff --git a/.vitepress/theme/components/SiteMap.vue b/.vitepress/theme/components/SiteMap.vue new file mode 100644 index 0000000000..47b520c550 --- /dev/null +++ b/.vitepress/theme/components/SiteMap.vue @@ -0,0 +1,67 @@ + + + + + diff --git a/.vitepress/theme/components/SponsorsGroup.vue b/.vitepress/theme/components/SponsorsGroup.vue index f1e3e7c8bf..9a03ce3d35 100644 --- a/.vitepress/theme/components/SponsorsGroup.vue +++ b/.vitepress/theme/components/SponsorsGroup.vue @@ -1,72 +1,82 @@ - -