chore(docs): add code format using markdownlint (#1498)

nuxt · pi0 · Oct 29, 2021 · Oct 29, 2021 · Oct 29, 2021 · Oct 29, 2021
commit 233745457756f5c050a499b7c997daea4361251b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -30,6 +30,9 @@ jobs:
       - name: Lint
         run: yarn lint
 
+      - name: Lint (docs)
+        run: yarn lint:docs
+
   test:
     runs-on: ${{ matrix.os }}
 

diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -0,0 +1,12 @@
+# Default state for all rules
+default: true
+# Disable max line length
+MD013: false
+# Allow duplicated heading for different sections
+MD024:
+  allow_different_nesting: true
+  siblings_only: true
+# Allow multiple top-level headings
+MD025: false
+# Allow inline HTML
+MD033: false
diff --git a/.markdownlintignore b/.markdownlintignore
@@ -0,0 +1,4 @@
+**/node_modules
+
+docs/content/index.md
+docs/content/**/15.nuxt.config.md
diff --git a/docs/content/1.getting-started/1.introduction.md b/docs/content/1.getting-started/1.introduction.md
@@ -28,9 +28,10 @@ Next, decide whether to start from scratch or upgrade an existing Nuxt 2 project
 ### Starting a fresh Nuxt project
 
 ::list{type=info}
-- Enjoy using Vue 3
-- All the new composables are available
-- New templating system and conventions are enabled
+
+* Enjoy using Vue 3
+* All the new composables are available
+* New templating system and conventions are enabled
 ::
 
 ::alert{icon=👉}
@@ -42,12 +43,13 @@ Checkout the [Installation section](/getting-started/installation).
 If you have an existing Nuxt 2 project, we **strongly recommend** you begin by using Nuxt Bridge. This way you can try most new features while keeping breaking changes to a minimum.
 
 ::list{type=info}
-- It's risk free! You can always remove the module from your config
-- Makes your project (almost) ready for Nuxt 3
-- Enjoy new DX improvements without major rewrites for Vue 3
-- Use Nitro engine for platform-agnostic and optimized deployments
-- Help us stabilize Nuxt 3 and discover flaws
-- Nuxt Bridge is more stable than Nuxt 3 at the moment
+
+* It's risk free! You can always remove the module from your config
+* Makes your project (almost) ready for Nuxt 3
+* Enjoy new DX improvements without major rewrites for Vue 3
+* Use Nitro engine for platform-agnostic and optimized deployments
+* Help us stabilize Nuxt 3 and discover flaws
+* Nuxt Bridge is more stable than Nuxt 3 at the moment
 ::
 
 ::alert{icon=👉}
@@ -56,7 +58,7 @@ Checkout the [Bridge installation section](/getting-started/bridge).
 
 ### ‍Comparison
 
-In the table below, there is a quick comparison between 3 versions of nuxt:
+In the table below, there is a quick comparison between 3 versions of Nuxt:
 
 Feature / Version        | Nuxt 2          | Nuxt Bridge      | Nuxt 3
 -------------------------|-----------------|------------------|---------

diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md
@@ -11,8 +11,8 @@ Learn more in [Introduction](/getting-started/introduction).
 
 You can start playing with Nuxt 3 in your browser using our online sandboxes:
 
-:button-link[Play on StackBlitz]{href=https://stackblitz.com/github/nuxt/starter/tree/v3-stackblitz blank}
-:button-link[Play on CodeSandBox]{href=https://codesandbox.io/s/github/nuxt/starter/tree/v3-codesandbox blank}
+:button-link[Play on StackBlitz]{href="https://stackblitz.com/github/nuxt/starter/tree/v3-stackblitz" blank}
+:button-link[Play on CodeSandBox]{href="https://codesandbox.io/s/github/nuxt/starter/tree/v3-codesandbox" blank}
 
 ## New project
 
@@ -31,29 +31,35 @@ code -r nuxt3-app
 Install the dependencies:
 
 ::code-group
+
 ```bash [Yarn]
 yarn install
 ```
+
 ```bash [NPM]
 npm install
 ```
+
 ::
 
 ## Development server
 
 Now you'll be able to use `yarn dev` to start your nuxt app in development mode:
 
 ::code-group
+
 ```bash [Yarn]
 yarn dev -o
 ```
+
 ```bash [NPM]
 npm run dev -- -o
 ```
+
 ::
 
 ::alert{type=success icon=✨ .font-bold}
-Well done! A browser window should automatically open for http://localhost:3000
+Well done! A browser window should automatically open for <http://localhost:3000>
 ::
 
 ## Next steps

diff --git a/docs/content/1.getting-started/3.bridge.md b/docs/content/1.getting-started/3.bridge.md
@@ -11,67 +11,70 @@ Bridge is a forward-compatibility layer that allows you to experience many of ne
 
 Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and have the best developer experience without needing a major rewrite or risk breaking changes.
 
+## Upgrade Nuxt 2
 
-### Upgrade Nuxt 2
+Remove any package lock files (`package-lock.json` and `yarn.lock`) and use the latest `nuxt-edge`:
 
-Remove any package lockfiles (`package-lock.json` and `yarn.lock`) and use the latest `nuxt-edge`:
-
-**package.json**
-
-```diff
+```diff [package.json]
 - "nuxt": "^2.15.0"
 + "nuxt-edge": "latest"
 ```
 
 Then, reinstall your dependencies:
 
 ::code-group
+
 ```bash [Yarn]
 yarn install
 ```
+
 ```bash [NPM]
 npm install
 ```
+
 ::
 
 ::alert
 Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
 ::
 
-### Install Nuxt Bridge
+## Install Nuxt Bridge
 
 Install `@nuxt/bridge-edge` as a development dependency:
 
 ::code-group
+
 ```bash [Yarn]
 yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
 ```
+
 ```bash [NPM]
 npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
 ```
+
 ::
 
-### Update your scripts
+## Update your scripts
 
 You will also need to update your scripts within your `package.json` to reflect the fact that Nuxt will now produce a Nitro server as build output.
 
-#### Static target
+### Static target
 
 If you have set `target: 'static'` in your `nuxt.config` then you need to ensure that you update your build script to be `nuxt generate`.
 
-```json
+```json [package.json]
 {
   "scripts": {
     "build": "nuxt generate"
   }
 }
 ```
 
-#### Server target
+### Server target
 
 For all other situations, you can use the normal `nuxt build` command.
 
-```json
+```json [package.json]
 {
   "scripts": {
     "build": "nuxt build",
@@ -80,7 +83,7 @@ For all other situations, you can use the normal `nuxt build` command.
 }
 ```
 
-### Update `nuxt.config`
+## Update `nuxt.config`
 
 Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in your config file. It will soon be deprecated and unsupported.
 
@@ -94,53 +97,60 @@ export default defineNuxtConfig({
 })
 ```
 
-### Update `tsconfig.json`
+## Update `tsconfig.json`
 
-If you are using TypeScript, you can edit your `tsconfig.json` to benefit from autogenerated Nuxt types:
+If you are using TypeScript, you can edit your `tsconfig.json` to benefit from auto-generated Nuxt types:
 
-**tsconfig.json**
-
-```diff
+```diff [tsconfig.json]
 {
 +    "extends": "./.nuxt/tsconfig.json",
      "compilerOptions": {
+       ...
+     }
+}
 ```
 
-### Avoid CommonJS syntax
+## Avoid CommonJS syntax
 
 Nuxt 3 natively supports TypeScript and ECMAScript Modules.
 
-#### Update the imports
+### Update the imports
 
 ::code-group
+
 ```js [Before]
 const lib = require('lib')
 ```
+
 ```js [After]
 import lib from 'lib'
 // or using code-splitting
 const lib = await import('lib').then(e => e.default || e)
 ```
+
 ::
 
-#### Update the exports
+### Update the exports
 
 ::code-group
+
 ```js [Before]
 module.exports = ...
 ```
+
 ```js [After]
 export default ...
 // or using named export
 export const hello = ...
 ```
+
 ::
 
-#### Avoid using specific CJS syntax
+### Avoid using specific CJS syntax
 
 Avoid the usage of `__dirname` and `__filename` as much as possible.
 
-### Remove incompatible and obsolete modules
+## Remove incompatible and obsolete modules
 
 - Remove `@nuxt/content` (1.x). A rewrite for nuxt 3 is planned (2.x)
 - Remove `nuxt-vite`: Bridge enables same functionality
@@ -149,11 +159,11 @@ Avoid the usage of `__dirname` and `__filename` as much as possible.
 - Remove `@nuxt/nitro`: Bridge injects same functionality
 - Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`). Bridge provides a legacy composition API layer that handles imports within your files from `@nuxtjs/composition-api` until you've fully finished migrating to native Bridge/Nuxt 3 composables (which you will import from by `#app`, or via auto-imports).
 
-### Exclude Nuxt build folder from git
+## Exclude Nuxt build folder from git
 
 Add the folder `.output` to the `.gitignore` file.
 
-### Ensure everything goes well
+## Ensure everything goes well
 
 ✔️ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.
 

diff --git a/docs/content/1.getting-started/4.commands.md b/docs/content/1.getting-started/4.commands.md
@@ -6,7 +6,7 @@ Nuxt 3 has two main commands, one to start development server and one to make pr
 
 Since Nuxt 3 becomes a dev dependency thanks to the new [Nitro server](/concepts/server-engine), you only need to add two commands in your `package.json`:
 
-```json
+```json [package.json]
 "scripts": {
   "dev": "nuxi dev",
   "build": "nuxi build",
@@ -17,28 +17,34 @@ Then, you can run each command using `npm run <command>` or `yarn <command>`.
 
 ## Development Server
 
-To start Nuxt in development mode with hot module replacement on http://localhost:3000:
+To start Nuxt in development mode with hot module replacement on <http://localhost:3000>:
 
 ::code-group
-```bash[Yarn]
+
+```bash [Yarn]
 yarn dev
 ```
-```bash[NPM]
+
+```bash [NPM]
 npm run dev
 ```
+
 ::
 
 ## Building for production
 
 To build your Nuxt application for production, run:
 
 ::code-group
-```bash[Yarn]
+
+```bash [Yarn]
 yarn build
 ```
-```bash[NPM]
+
+```bash [NPM]
 npm run build
 ```
+
 ::
 
 Nuxt will create a [`.output`](/docs/directory-structure/output) directory with all your application, server and dependencies ready to be deployed. Checkout the [deployment](/docs/deployment) section to learn where and how you can deploy a Nuxt application using Nitro.