docs: update to latest docus and various improvements (#975)

* docs: update to latest docus * 1 update by Nuxt Studio
nitrojs · Feb 22, 2023 · e0a7fa4 · e0a7fa4
1 parent 05839c4
commit e0a7fa4
Show file tree

Hide file tree

Showing 37 changed files with 2,782 additions and 2,460 deletions.
diff --git a/docs/app.config.ts b/docs/app.config.ts
@@ -0,0 +1,34 @@
+export default defineAppConfig({
+  docus: {
+    title: '⚗️ Nitro',
+    header: {
+      title: false,
+      logo: true
+    },
+    description: 'Build and Deploy Universal JavaScript Servers.',
+    url: 'https://nitro.unjs.io',
+    image: '/cover.png',
+    socials: {
+      twitter: 'unjsio',
+      github: 'unjs/nitro'
+    },
+    github: {
+      owner: 'unjs',
+      repo: 'nitro',
+      branch: 'main',
+      dir: 'docs/content',
+      edit: true
+    },
+    aside: {
+      level: 1
+    },
+    footer: {
+      credits: {
+        icon: '',
+        text: 'Made with 💛',
+        href: 'https://github.com/unjs/nitro'
+      },
+      icons: []
+    }
+  }
+})
diff --git a/docs/content/1.guide/1.introduction/0.getting-started.md b/docs/content/1.guide/1.introduction/0.getting-started.md
@@ -1,9 +1,12 @@
----
-title: Getting Started
-description: "Let's create a new Nitro app!"
----
+# Getting Started
 
-🏀 [Online playground](https://stackblitz.com/github/unjs/nitro/tree/main/examples/hello-world) on StackBlitz
+Let's create a new Nitro app!
+
+## Play online
+
+:button-link[Play on Stackblitz]{href="https://stackblitz.com/github/unjs/nitro/tree/main/examples/hello-world" icon="simple-icons:stackblitz" blank}
+
+## Create locally
 
 Create an empty directory `nitro-app`
 

diff --git a/docs/content/1.guide/1.introduction/1.configuration.md b/docs/content/1.guide/1.introduction/1.configuration.md
@@ -1,19 +1,18 @@
----
-title: Configuration
-description: Customize your Nitro app with a configuration file!
----
+# Configuration
 
-In order to customize nitro's behavior, we can use `nitro.config`.
+Customize your Nitro app with a configuration file.
 
-It is powerful enough that all deployment providers are built on the same options API!!
+In order to customize nitro's behavior, we can use `nitro.config.ts`.
+
+It is powerful enough that all deployment providers are built on the same options API.
 
 Create a new `nitro.config.ts` file to provide options:
 
-```js
-// nitro.config.ts
+```ts [nitro.config.ts]
 import { defineNitroConfig } from 'nitropack'
 
 export default defineNitroConfig({
+  // Your options
 })
 ```
 

diff --git a/docs/content/1.guide/1.introduction/2.auto-imports.md b/docs/content/1.guide/1.introduction/2.auto-imports.md
@@ -1,9 +1,6 @@
----
-title: Auto Imports
-description: You might be surprised why in the documentation there are no import statements.
----
+# Auto Imports
 
-This is because Nitro is integrated with [unjs/unimport](https://github.com/unjs/unimport) and automatically imports utilities by usage with full tree-shaking support!
+Nitro is integrated with [unjs/unimport](https://github.com/unjs/unimport) and automatically imports utilities by usage with full tree-shaking support.
 
 ## Available Auto Imports
 
@@ -21,6 +18,6 @@ For some edge cases (IDE support and libraries in `node_modules`) it is impossib
 
 You can import them from virtual `#imports` file. It will be still tree-shaken:
 
-```js
+```js [plugins/test.ts]
 import { useStorage } from '#imports'
 ```
diff --git a/docs/content/1.guide/1.introduction/3.routing.md b/docs/content/1.guide/1.introduction/3.routing.md
@@ -1,11 +1,10 @@
----
-title: Route Handling
-description: Nitro supports file-based routing for your API routes.
----
+# Route Handling
+
+Nitro supports file-based routing for your API routes.
 
 Handler files inside `routes/` and `api/` directory will be automatically mapped to [unjs/h3](https://github.com/unjs/h3) routes.
 
-**Note:** `api/` is a shortcut for `routes/api` as a common prefix. However, please note that some deployment providers use `app/` directory for their API format. You can simply use the `routes/api` or `srcDir` option to move everything under `src/` or `server/` directory.
+**Note:** `api/` is a shortcut for `routes/api` as a common prefix. However, please note that some deployment providers use `api/` directory for their API format. You can simply use the `routes/api` or `srcDir` option to move everything under `src/` or `server/` directory.
 
 ## Usage
 
@@ -15,7 +14,7 @@ Check out [h3 JSDocs](https://www.jsdocs.io/package/h3#package-index-functions)
 
 **Example:** Simple API route
 
-```js
+```ts
 // routes/test.ts
 export default eventHandler(() => 'Hello World!')
 ```

diff --git a/docs/content/1.guide/1.introduction/4.storage.md b/docs/content/1.guide/1.introduction/4.storage.md
@@ -1,7 +1,6 @@
----
-title: Storage Layer
-description: Nitro provides a built-in storage layer that can abstract filesystem or database or any other data source.
----
+# Storage Layer
+
+Nitro provides a built-in storage layer that can abstract filesystem or database or any other data source.
 
 See [unjs/unstorage](https://github.com/unjs/unstorage) for more usage information.
 

diff --git a/docs/content/1.guide/1.introduction/5.cache.md b/docs/content/1.guide/1.introduction/5.cache.md
@@ -1,7 +1,6 @@
----
-title: Cache API
-description: Nitro provides a powerful caching system built on top of the storage layer.
----
+# Cache API
+
+Nitro provides a powerful caching system built on top of the storage layer.
 
 ## Usage
 

diff --git a/docs/content/1.guide/1.introduction/6.assets.md b/docs/content/1.guide/1.introduction/6.assets.md
@@ -1,7 +1,6 @@
----
-title: Assets Handling
-description: Nitro handles assets via the public directory.
----
+# Assets Handling
+
+Nitro handles assets via the public directory.
 
 ## Public Assets
 

diff --git a/docs/content/1.guide/1.introduction/7.typescript.md b/docs/content/1.guide/1.introduction/7.typescript.md
@@ -1,11 +1,10 @@
----
-title: TypeScript Support
-description: Nitro supports TypeScript by default.
----
+# TypeScript Support
+
+Nitro supports TypeScript by default.
 
 To add type hints within your project, you should add the following to your `tsconfig.json` file:
 
-```json
+```json [tsconfig.json]
 {
   "extends": "./.nitro/types/tsconfig.json"
 }

diff --git a/docs/content/1.guide/2.advanced/1.plugins.md b/docs/content/1.guide/2.advanced/1.plugins.md
@@ -1,26 +1,14 @@
----
-title: Plugins
-description: To extend nitro's runtime behavior, we can register plugins.
----
+#  Plugins
 
-They will be synchronously on the first nitro initialization given `nitroApp` context, which can be used to hook into lifecycle events.
+Use plugins to extend nitro's runtime behavior.
+
+Plugins are auto-registered (filename ordering) and run synchronously on the first nitro initialization. They receive `nitroApp` context, which can be used to hook into lifecycle events.
 
 **Example:** Simple plugin
 
-```js
+```ts
 // plugins/test.ts
 export default defineNitroPlugin((nitroApp) => {
   console.log('Nitro plugin', nitroApp)
 })
 ```
-
-```js
-// nitro.config.ts
-import { defineNitroConfig } from 'nitropack'
-
-export default defineNitroConfig({
-  plugins: [
-    '~/plugins/test'
-  ]
-})
-```
diff --git a/docs/content/1.guide/2.advanced/2.custom-presets.md b/docs/content/1.guide/2.advanced/2.custom-presets.md
@@ -1,6 +1,4 @@
----
-title: Custom Presets
----
+# Custom Presets
 
 ::alert{type="warning"}
 **Work in Progress**

diff --git a/docs/content/1.guide/3.community/contribution.md b/docs/content/1.guide/3.community/contribution.md
@@ -1,7 +1,6 @@
----
-title: Contribution
-description: Thank you for all your contributions! 💛
----
+# Contribution
+
+Thank you for all your contributions! 💛
 
 **Before everything, please make sure there is an option issue either confirming issue/bug 🐛 and there is already a dicussion with 👍 to add an enhancement.**
 

diff --git a/docs/content/2.deploy/0.index.md b/docs/content/2.deploy/0.index.md
@@ -1,7 +1,6 @@
----
-title: Overview
-description: Nitro can generate different output formats suitable for different hosting providers from the same code base.
----
+# Overview
+
+Nitro can generate different output formats suitable for different hosting providers from the same code base.
 
 Using built-in presets, you can easily configure Nitro to adjust it's output format with almost no additional code or configuration!
 

diff --git a/docs/content/2.deploy/1.node.md b/docs/content/2.deploy/1.node.md
@@ -1,7 +1,6 @@
----
-title: Node.js
-description: Node.js deployment is the default Nitro preset.
----
+# Node.js
+
+Node.js deployment is the default Nitro preset.
 
 ## Node.js Server
 

diff --git a/docs/content/2.deploy/2.workers.md b/docs/content/2.deploy/2.workers.md
@@ -1,7 +1,6 @@
----
-title: Workers
-description: Nitro provides out of the box support for deploying to Edge Workers.
----
+# Workers
+
+Nitro provides out of the box support for deploying to Edge Workers.
 
 ## Deploy to Workers
 

diff --git a/docs/content/2.deploy/providers/aws.md b/docs/content/2.deploy/providers/aws.md
@@ -1,7 +1,6 @@
----
-title: AWS Lambda
-description: 'Discover AWS Lambda preset for Nitro!'
----
+# AWS Lambda
+
+Deploy Nitro apps to AWS Lambda.
 
 **Preset:** `aws-lambda` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 

diff --git a/docs/content/2.deploy/providers/azure.md b/docs/content/2.deploy/providers/azure.md
@@ -1,7 +1,6 @@
----
-title: Azure
-description: 'Discover Azure preset for Nitro!'
----
+# Azure
+
+Deploy Nitro apps to Azure.
 
 ## Azure Static Web Apps
 

diff --git a/docs/content/2.deploy/providers/cleavr.md b/docs/content/2.deploy/providers/cleavr.md
@@ -1,9 +1,6 @@
----
-title: Cleavr
-description: 'Discover Cleavr preset for Nitro!'
----
+# Cleavr
 
-## Cleavr
+Deploy Nitro apps to Cleavr.
 
 **Preset:** `cleavr` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 

diff --git a/docs/content/2.deploy/providers/cloudflare.md b/docs/content/2.deploy/providers/cloudflare.md
@@ -1,7 +1,6 @@
----
-title: Cloudflare
-description: 'Discover Cloudflare preset for Nitro!'
----
+# Cloudflare
+
+Deploy Nitro apps to CloudFlare.
 
 ## Cloudflare Workers
 

diff --git a/docs/content/2.deploy/providers/digitalocean.md b/docs/content/2.deploy/providers/digitalocean.md
@@ -1,7 +1,6 @@
----
-title: DigitalOcean
-description: 'Discover DigitalOcean preset for Nitro!'
----
+# DigitalOcean
+
+Deploy Nitro apps to DigitalOcean.
 
 **Preset:** `digital-ocean` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 
@@ -30,7 +29,7 @@ Nitro supports deploying on the [Digital Ocean App Platform](https://docs.digita
    ```
 
    [See more information](https://docs.digitalocean.com/products/app-platform/languages-frameworks/nodejs/#node-version).
-   
+
 
 1. You'll also need to add a run command so Digital Ocean knows what command to run after a build. You can do so by adding a start script to your `package.json`:
 
@@ -41,7 +40,7 @@ Nitro supports deploying on the [Digital Ocean App Platform](https://docs.digita
       }
    }
    ```
-   
+
 1. Finally, you'll need to add this start script to your Digital Ocean app's run command. Go to `Components > Settings > Commands`, click "Edit", then add `npm run start`
 
 Your app should be live at a Digital Ocean generated URL and you can now follow [the rest of the Digital Ocean deployment guide](https://docs.digitalocean.com/products/app-platform/how-to/manage-deployments/).
diff --git a/docs/content/2.deploy/providers/edgio.md b/docs/content/2.deploy/providers/edgio.md
@@ -1,7 +1,6 @@
----
-title: Edgio
-description: 'Discover Edgio (formerly Layer0) preset for Nitro!'
----
+# Edgio
+
+Deploy Nitro apps to Edgio (formerly Layer0).
 
 **Preset:** `edgio` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 

diff --git a/docs/content/2.deploy/providers/firebase.md b/docs/content/2.deploy/providers/firebase.md
@@ -1,7 +1,6 @@
----
-title: Firebase
-description: "Discover Firebase preset for Nitro!"
----
+# Firebase
+
+Deploy Nitro apps to Firebase.
 
 **Preset:** `firebase` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 

diff --git a/docs/content/2.deploy/providers/heroku.md b/docs/content/2.deploy/providers/heroku.md
@@ -1,7 +1,6 @@
----
-title: Heroku
-description: 'Discover Heroku preset for Nitro!'
----
+# Heroku
+
+Deploy Nitro apps to Heroku.
 
 **Preset:** `heroku` ([switch to this preset](/deploy/#changing-the-deployment-preset))
 

diff --git a/docs/content/2.deploy/providers/lagon.md b/docs/content/2.deploy/providers/lagon.md
@@ -1,7 +1,6 @@
----
-title: Lagon
-description: "Discover Lagon preset for Nitro!"
----
+# Lagon
+
+Deploy Nitro apps to Lagon.
 
 > Lagon is an open source platform that allows you to run TypeScript and JavaScript close to your users.
 

diff --git a/docs/content/2.deploy/providers/layer0.md b/docs/content/2.deploy/providers/layer0.md
@@ -1,3 +1,4 @@
 ---
 redirect: /deploy/providers/edgio
+navigation: false
 ---
diff --git a/docs/content/2.deploy/providers/netlify.md b/docs/content/2.deploy/providers/netlify.md
@@ -1,7 +1,6 @@
----
-title: Netlify
-description: 'Discover Netlify preset for Nitro!'
----
+# Netlify
+
+Deploy Nitro apps to Netlify.
 
 **Preset:** `netlify` ([switch to this preset](/deploy/#changing-the-deployment-preset))