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

.markdownlint.yml

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

.markdownlintignore

@@ -1,5 +1,5 @@
 **/node_modules
 
-docs/content/index.md
+docs/0.index.md
-docs/content/**/*.nuxt.config.md
+docs/1.getting-started/1.introduction.md
-docs/content/changelog.md
+docs/**/*.nuxt.config.md

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)

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
 
+<!-- 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
+::details
-    :summary[Additional notes for an optimal setup:]
+:summary[Additional notes for an optimal setup:]
-    - **Node.js**: Make sure to use an even numbered version (16, 18, etc)
+- **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]
+```ts [nuxt.config.ts]
-    export default defineNuxtConfig({
+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)

docs/1.getting-started/8.error-handling.md

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

docs/2.guide/1.concepts/1.auto-imports.md

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

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.

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

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 {}
 ```
-

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

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

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

docs/3.api/5.commands/devtools.md

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

docs/5.community/5.framework-contribution.md

@@ -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`
+<!-- - Go into the docs directory: `cd docs` -->
-- Install docs dependencies using `yarn install`
+<!-- - Install docs dependencies using `yarn install` -->
-- Run `yarn dev` to start docs in development mode
+<!-- - 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.
+::

docs/7.migration/2.configuration.md

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

package.json

@@ -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": "markdownlint ./docs && case-police 'docs/**/*.md'",
-    "lint:docs:fix": "markdownlint ./docs/content/1.docs --fix && case-police 'docs/content/1.docs/**/*.md' --fix",
+    "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",