From e7623ec0b7d1c812d1d606ca9c026f7b36809dd1 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Tue, 4 Apr 2023 14:23:13 +0100 Subject: [PATCH] docs: re-enable docs linting and update docs (#20084) --- .markdownlint.yml | 2 ++ .markdownlintignore | 6 ++-- docs/1.getting-started/10.deployment.md | 2 +- docs/1.getting-started/2.installation.md | 34 +++++++++++-------- docs/1.getting-started/8.error-handling.md | 1 - docs/2.guide/1.concepts/1.auto-imports.md | 2 +- .../2.directory-structure/1.modules.md | 3 ++ .../2.directory-structure/1.plugins.md | 2 +- .../2.directory-structure/3.app-config.md | 1 - docs/2.guide/3.going-further/3.modules.md | 7 ++-- docs/3.api/1.composables/use-head-safe.md | 1 + docs/3.api/4.advanced/1.hooks.md | 2 +- docs/3.api/5.commands/devtools.md | 2 +- docs/5.community/5.framework-contribution.md | 15 +++++--- docs/7.migration/2.configuration.md | 1 - package.json | 4 +-- 16 files changed, 51 insertions(+), 34 deletions(-) diff --git a/.markdownlint.yml b/.markdownlint.yml index 15a0e34464..c1fac0779d 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -12,3 +12,5 @@ MD025: false MD033: false # Allow non blank lines around list MD032: false +MD046: + style: fenced diff --git a/.markdownlintignore b/.markdownlintignore index 04a20c4d4c..76059468f3 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,5 +1,5 @@ **/node_modules -docs/content/index.md -docs/content/**/*.nuxt.config.md -docs/content/changelog.md +docs/0.index.md +docs/1.getting-started/1.introduction.md +docs/**/*.nuxt.config.md diff --git a/docs/1.getting-started/10.deployment.md b/docs/1.getting-started/10.deployment.md index 0627b89591..b816e2b27d 100644 --- a/docs/1.getting-started/10.deployment.md +++ b/docs/1.getting-started/10.deployment.md @@ -141,7 +141,7 @@ Nuxt 3 can be deployed to several cloud providers with a minimal amount of confi - :icon{name="logos:microsoft-azure" class="h-5 w-4 inline mb-2"} [Azure](https://nitro.unjs.io/deploy/providers/azure) - :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Cleavr](https://nitro.unjs.io/deploy/providers/cleavr) - :icon{name="logos:cloudflare" class="h-5 w-4 inline mb-2"} [CloudFlare](https://nitro.unjs.io/deploy/providers/cloudflare) -- :icon{name="logos:digital-ocean" class="h-5 w-4 inline mb-2"} [Digital Ocean](https://nitro.unjs.io/deploy/providers/digitalocean) +- :icon{name="logos:digital-ocean" class="h-5 w-4 inline mb-2"} [DigitalOcean](https://nitro.unjs.io/deploy/providers/digitalocean) - :icon{name="logos:firebase" class="h-5 w-4 inline mb-2"} [Firebase](https://nitro.unjs.io/deploy/providers/firebase) - :icon{name="logos:heroku-icon" class="h-5 w-4 inline mb-2"} [heroku](https://nitro.unjs.io/deploy/providers/heroku) - :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Edgio](https://nitro.unjs.io/deploy/providers/edgio) diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md index c568166951..2db33a6ec4 100644 --- a/docs/1.getting-started/2.installation.md +++ b/docs/1.getting-started/2.installation.md @@ -19,28 +19,32 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/ ## New Project + + #### Prerequisites + - **Node.js** - [`v16.10.0`](https://nodejs.org/en/) or newer -- **Text editor** - We recommend [Visual Studio Code]() with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) +- **Text editor** - We recommend [Visual Studio Code](https://code.visualstudio.com/) with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) - **Terminal** - In order to run Nuxt commands ::alert - ::details - :summary[Additional notes for an optimal setup:] - - **Node.js**: Make sure to use an even numbered version (16, 18, etc) +::details +:summary[Additional notes for an optimal setup:] +- **Node.js**: Make sure to use an even numbered version (16, 18, etc) - - **Volar**: Either enable [**Take Over Mode**](https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode) (recommended) or add the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) +- **Volar**: Either enable [**Take Over Mode**](https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode) (recommended) or add the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) - If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your `nuxt.config.ts` file: +If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your `nuxt.config.ts` file: - ```ts [nuxt.config.ts] - export default defineNuxtConfig({ - typescript: { - shim: false - } - }) - ``` - :: +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + typescript: { + shim: false + } +}) +``` + +:: :: Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.com/), you can open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal)) and use the following command to create a new starter project: @@ -110,4 +114,4 @@ Well done! A browser window should automatically open for -When you are using the built-in composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_. +When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_. During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components. diff --git a/docs/2.guide/2.directory-structure/1.modules.md b/docs/2.guide/2.directory-structure/1.modules.md index fc9c51c341..305b9d9f65 100644 --- a/docs/2.guide/2.directory-structure/1.modules.md +++ b/docs/2.guide/2.directory-structure/1.modules.md @@ -16,6 +16,7 @@ The auto-registered files patterns are: You don't need to add those local modules to your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt.config) separately. ::code-group + ```ts [modules/hello/index.ts] // `nuxt/kit` is a helper subpath import you can use when defining local modules // that means you do not need to add `@nuxt/kit` to your project's dependencies @@ -36,11 +37,13 @@ export default defineNuxtModule({ } }) ``` + ```ts [modules/hello/runtime/api-route.ts] export default defineEventHandler(() => { return { hello: 'world' } } ``` + :: When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available. diff --git a/docs/2.guide/2.directory-structure/1.plugins.md b/docs/2.guide/2.directory-structure/1.plugins.md index b24ef8a0dd..e5147b23d1 100644 --- a/docs/2.guide/2.directory-structure/1.plugins.md +++ b/docs/2.guide/2.directory-structure/1.plugins.md @@ -134,7 +134,7 @@ export { } ``` ::alert{type=warning} -If you are using WebStorm, you may need to augment `@vue/runtime-core` until [this issue](https://youtrack.jetbrains.com/issue/WEB-59818/VUE-Typescript-WS-PS-does-not-correctly-display-type-of-globally-injected-properties) is resolved. +If you are using WebStorm, you may need to augment `@vue/runtime-core` until [this issue](https://youtrack.jetbrains.com/issue/WEB-59818/VUE-TypeScript-WS-PS-does-not-correctly-display-type-of-globally-injected-properties) is resolved. :: ## Vue Plugins diff --git a/docs/2.guide/2.directory-structure/3.app-config.md b/docs/2.guide/2.directory-structure/3.app-config.md index a4719428bc..30cdd7b3e5 100644 --- a/docs/2.guide/2.directory-structure/3.app-config.md +++ b/docs/2.guide/2.directory-structure/3.app-config.md @@ -91,4 +91,3 @@ declare module 'nuxt/schema' { // It is always important to ensure you import/export something when augmenting a type export {} ``` - diff --git a/docs/2.guide/3.going-further/3.modules.md b/docs/2.guide/3.going-further/3.modules.md index a031cd53b8..ba73c55f56 100644 --- a/docs/2.guide/3.going-further/3.modules.md +++ b/docs/2.guide/3.going-further/3.modules.md @@ -424,6 +424,7 @@ export default defineNuxtModule({ :ReadMore{link="/docs/api/advanced/hooks" title="API > Advanced > Hooks"} +::alert{type=info} **Module cleanup** If your module opens, handles, or starts a watcher, you should close it when the Nuxt lifecycle is done. The `close` hook is available for this. @@ -440,6 +441,8 @@ export default defineNuxtModule({ }) ``` +:: + #### Augmenting Types If your module should augment types handled by Nuxt, you can use the `prepare:types` hook to perform this operation. @@ -589,9 +592,9 @@ Consider documenting module usage in the readme file: Linking to the integration website and documentation is always a good idea. -#### Provide a Stackblitz Demo or Boilerplate +#### Provide a StackBlitz Demo or Boilerplate -It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v3) that you add to your module readme. +It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v3) that you add to your module readme. This not only provides potential users of your module a quick and easy way to experiment with the module but also an easy way for them to build minimal reproductions they can send you when they encounter issues. diff --git a/docs/3.api/1.composables/use-head-safe.md b/docs/3.api/1.composables/use-head-safe.md index f90add71e0..b5d2addd5f 100644 --- a/docs/3.api/1.composables/use-head-safe.md +++ b/docs/3.api/1.composables/use-head-safe.md @@ -9,6 +9,7 @@ The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/api/compo ## Usage You can pass all the same values as `useHead` + ```ts useHeadSafe({ script: [ diff --git a/docs/3.api/4.advanced/1.hooks.md b/docs/3.api/4.advanced/1.hooks.md index d280f13633..412199d94f 100644 --- a/docs/3.api/4.advanced/1.hooks.md +++ b/docs/3.api/4.advanced/1.hooks.md @@ -46,7 +46,7 @@ Hook | Arguments | Description `app:templatesGenerated` | `app` | Called after templates are compiled into the [virtual file system](https://nuxt.com/docs/guide/directory-structure/nuxt#virtual-file-system) (vfs). `build:before` | - | Called before Nuxt bundle builder. `build:done` | - | Called after Nuxt bundle builder is complete. -`build:manifest` | `manifest` | Called during the manifest build by Vite and Webpack. This allows customizing the manifest that Nitro will use to render `