docs: re-enable docs linting and update docs (#20084)

This commit is contained in:
Daniel Roe 2023-04-04 14:23:13 +01:00 committed by GitHub
parent bc9c7dcac8
commit e7623ec0b7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 51 additions and 34 deletions

View File

@ -12,3 +12,5 @@ MD025: false
MD033: false
# Allow non blank lines around list
MD032: false
MD046:
style: fenced

View File

@ -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

View File

@ -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)

View File

@ -19,28 +19,32 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/
## New Project
<!-- TODO: need to fix upstream in nuxt/nuxt.com -->
<!-- markdownlint-disable-next-line MD001 -->
#### 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 <http://localhost:3000
Now that you've created your Nuxt 3 project, you are ready to start building your application.
* Learn about the framework [concepts](/docs/guide/concepts/auto-imports)
- Learn about the framework [concepts](/docs/guide/concepts/auto-imports)

View File

@ -48,7 +48,6 @@ This includes:
You cannot currently define a server-side handler for these errors, but can render an error page (see the next section).
### Errors downloading JS chunks
You might encounter chunk loading errors due to a network connectivity failure or a new deployment (which invalidates your old, hashed JS chunk URLs). Nuxt provides built-in support for handling chunk loading errors by performing a hard reload when a chunk fails to load during route navigation.

View File

@ -50,7 +50,7 @@ Vue 3 exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hoo
<!-- TODO: move to separate page with https://github.com/nuxt/nuxt/issues/14723 and add more information -->
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.

View File

@ -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.

View File

@ -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

View File

@ -91,4 +91,3 @@ declare module 'nuxt/schema' {
// It is always important to ensure you import/export something when augmenting a type
export {}
```

View File

@ -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,7 +592,7 @@ 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.

View File

@ -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: [

View File

@ -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 `<script>` and `<link>` tags in the final HTML.
`build:manifest` | `manifest` | Called during the manifest build by Vite and webpack. This allows customizing the manifest that Nitro will use to render `<script>` and `<link>` tags in the final HTML.
`builder:generateApp` | `options` | Called before generating the app.
`builder:watch` | `event, path` | Called at build time in development when the watcher spots a change to a file or directory in the project.
`pages:extend` | `pages` | Called after pages routes are resolved.

View File

@ -1,6 +1,6 @@
---
title: "nuxi devtools"
description: The devtools command allows you to enable or disable Nuxt Devtools on a per-project basis.
description: The devtools command allows you to enable or disable Nuxt DevTools on a per-project basis.
---
# `nuxi devtools`

View File

@ -134,11 +134,18 @@ git checkout -b my-new-branch
### Set Up Documentation Website in Local Environment
We are using [Docus](https://docus.dev) for documentation.
The Nuxt documentation is currently deployed within [nuxt/nuxt.com](https://github.com/nuxt/nuxt.com) as a layer.
- Run `pnpm build:stub` once in the root directory
- Go into the docs directory: `cd docs`
- Install docs dependencies using `yarn install`
- Run `yarn dev` to start docs in development mode
<!-- - Go into the docs directory: `cd docs` -->
<!-- - Install docs dependencies using `yarn install` -->
<!-- - Run `yarn dev` to start docs in development mode -->
- Before opening a PR, run `pnpm docs:lint:fix` to highlight and resolve any lint issues
::alert
🚧 This repository will be open-sourced shortly. Until then, you will need to open a pull request to see a preview of your changes.
::
::alert
We recommend that you install the [MDC extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) for VS Code.
::

View File

@ -88,7 +88,6 @@ Nuxt and Nuxt Modules are now build-time-only.
})
```
::alert
If you are a module author, you can check out [more information about module compatibility](/docs/migration/module-authors) and [our module author guide](/docs/guide/going-further/modules).
::

View File

@ -12,8 +12,8 @@
"example": "./scripts/example.sh dev",
"example:build": "./scripts/example.sh build",
"lint": "eslint --ext .vue,.ts,.js,.mjs .",
"lint:docs": "markdownlint ./docs/content/1.docs && case-police 'docs/content/1.docs/**/*.md'",
"lint:docs:fix": "markdownlint ./docs/content/1.docs --fix && case-police 'docs/content/1.docs/**/*.md' --fix",
"lint:docs": "markdownlint ./docs && case-police 'docs/**/*.md'",
"lint:docs:fix": "markdownlint ./docs --fix && case-police 'docs/**/*.md' --fix",
"nuxi": "JITI_ESM_RESOLVE=1 nuxi",
"nuxt": "JITI_ESM_RESOLVE=1 nuxi",
"play": "pnpm nuxi dev playground",