docs: enable twoslash for some code snippets (#25679)

nuxt · Feb 7, 2024 · 3c27141 · 3c27141
1 parent ae83df8
commit 3c27141
Show file tree

Hide file tree

Showing 11 changed files with 68 additions and 59 deletions.
diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md
@@ -34,7 +34,7 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/
 
   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`](/docs/guide/directory-structure/nuxt-config) file:
 
-  ```ts [nuxt.config.ts]
+  ```ts twoslash [nuxt.config.ts]
   export default defineNuxtConfig({
     typescript: {
       shim: false

diff --git a/docs/1.getting-started/3.configuration.md b/docs/1.getting-started/3.configuration.md
@@ -13,7 +13,7 @@ The [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file is loca
 
 A minimal configuration file exports the `defineNuxtConfig` function containing an object with your configuration. The `defineNuxtConfig` helper is globally available without import.
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   // My Nuxt config
 })
@@ -33,7 +33,7 @@ You don't have to use TypeScript to build an application with Nuxt. However, it
 
 You can configure fully typed, per-environment overrides in your nuxt.config
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   $production: {
     routeRules: {
@@ -58,7 +58,7 @@ Those values should be defined in `nuxt.config` and can be overridden using envi
 
 ::code-group
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   runtimeConfig: {
     // The private keys which are only available server-side
@@ -164,7 +164,7 @@ If you need to pass options to `@vitejs/plugin-vue` or `@vitejs/plugin-vue-jsx`,
 - `vite.vue` for `@vitejs/plugin-vue`. Check available options [here](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue).
 - `vite.vueJsx` for `@vitejs/plugin-vue-jsx`. Check available options [here](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx).
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   vite: {
     vue: {
@@ -183,7 +183,7 @@ export default defineNuxtConfig({
 
 If you use webpack and need to configure `vue-loader`, you can do this using `webpack.loaders.vue` key inside your `nuxt.config` file. The available options are [defined here](https://github.com/vuejs/vue-loader/blob/main/src/index.ts#L32-L62).
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   webpack: {
     loaders: {
@@ -201,7 +201,7 @@ export default defineNuxtConfig({
 
 You may need to enable experimental features in Vue, such as `propsDestructure`. Nuxt provides an easy way to do that in `nuxt.config.ts`, no matter which builder you are using:
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   vue: {
     propsDestructure: true

diff --git a/docs/1.getting-started/3.views.md b/docs/1.getting-started/3.views.md
@@ -138,7 +138,7 @@ If you only need to modify the `<head>`, you can refer to the [SEO and meta sect
 You can have full control over the HTML template by adding a Nitro plugin that registers a hook.
 The callback function of the `render:html` hook allows you to mutate the HTML before it is sent to the client.
 
-```ts [server/plugins/extend-html.ts]
+```ts twoslash [server/plugins/extend-html.ts]
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('render:html', (html, { event }) => { 
     // This will be an object representation of the html template.

diff --git a/docs/1.getting-started/4.assets.md b/docs/1.getting-started/4.assets.md
@@ -73,7 +73,7 @@ In your `nuxt.config`
 
 ::code-group
 
-```ts [SCSS]
+```ts twoslash [SCSS]
 export default defineNuxtConfig({
   vite: {
     css: {
@@ -87,7 +87,7 @@ export default defineNuxtConfig({
 })
 ```
 
-```ts [SASS]
+```ts twoslash [SASS]
 export default defineNuxtConfig({
   vite: {
     css: {

diff --git a/docs/1.getting-started/4.styling.md b/docs/1.getting-started/4.styling.md
@@ -107,7 +107,7 @@ You can include external stylesheets in your application by adding a link elemen
 
 You can manipulate the head with the [`app.head`](/docs/api/nuxt-config#head) property of your Nuxt configuration:
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   app: {
     head: {
@@ -122,7 +122,7 @@ You can use the useHead composable to dynamically set a value in your head in yo
 
 :read-more{to="/docs/api/composables/use-head"}
 
-```ts
+```ts twoslash
 useHead({
   link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }]
 })
@@ -136,7 +136,7 @@ If you need more advanced control, you can intercept the rendered html with a ho
 
 Create a plugin in `~/server/plugins/my-plugin.ts` like this:
 
-```ts [server/plugins/my-plugin.ts]
+```ts twoslash [server/plugins/my-plugin.ts]
 export default defineNitroPlugin((nitro) => {
   nitro.hooks.hook('render:html', (html) => {
     html.head.push('<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">')
@@ -177,7 +177,7 @@ You can then import your source files in your `app.vue` (or layouts files) using
 
 Alternatively, you can use the `css` property of your Nuxt configuration.
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   css: ['~/assets/scss/main.scss']
 })
@@ -209,7 +209,7 @@ Then in your `nuxt.config` :
 
 ::code-group
 
-```ts [SCSS]
+```ts twoslash [SCSS]
 export default defineNuxtConfig({
   vite: {
     css: {
@@ -223,7 +223,7 @@ export default defineNuxtConfig({
 })
 ```
 
-```ts [SASS]
+```ts twoslash [SASS]
 export default defineNuxtConfig({
   vite: {
     css: {

diff --git a/docs/1.getting-started/5.routing.md b/docs/1.getting-started/5.routing.md
@@ -71,7 +71,7 @@ When a [`<NuxtLink>`](/docs/api/components/nuxt-link) enters the viewport on the
 
 The [`useRoute()`](/docs/api/composables/use-route) composable can be used in a `<script setup>` block or a `setup()` method of a Vue component to access the current route details.
 
-```vue [pages/posts/[id\\].vue]
+```vue twoslash [pages/posts/[id\\].vue]
 <script setup lang="ts">
 const route = useRoute()
 
@@ -100,7 +100,9 @@ Example of an `auth` middleware protecting the `/dashboard` page:
 
 ::code-group
 
-```ts [middleware/auth.ts]
+```ts twoslash [middleware/auth.ts]
+function isAuthenticated(): boolean { return false }
+// ---cut---
 export default defineNuxtRouteMiddleware((to, from) => {
   // isAuthenticated() is an example method verifying if a user is authenticated
   if (isAuthenticated() === false) {
@@ -109,7 +111,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
 })
 ```
 
-```html [pages/dashboard.vue]
+```vue twoslash [pages/dashboard.vue]
 <script setup lang="ts">
 definePageMeta({
   middleware: 'auth'
@@ -133,7 +135,7 @@ The `validate` property accepts the `route` as an argument. You can return a boo
 
 If you have a more complex use case, then you can use anonymous route middleware instead.
 
-```vue [pages/posts/[id\\].vue]
+```vue twoslash [pages/posts/[id\\].vue]
 <script setup lang="ts">
 definePageMeta({
   validate: async (route) => {

diff --git a/docs/1.getting-started/5.seo-meta.md b/docs/1.getting-started/5.seo-meta.md
@@ -8,7 +8,7 @@ navigation.icon: i-ph-file-search-duotone
 
 Out-of-the-box, Nuxt provides sane defaults, which you can override if needed.
 
-```ts [nuxt.config.ts]
+```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   app: {
     head: {
@@ -34,7 +34,7 @@ powered by [Unhead](https://unhead.unjs.io).
 
 As with all composables, it can only be used with a components `setup` and lifecycle hooks.
 
-```vue [app.vue]
+```vue twoslash [app.vue]
 <script setup lang="ts">
 useHead({
   title: 'My App',
@@ -57,7 +57,7 @@ The [`useSeoMeta`](/docs/api/composables/use-seo-meta) composable lets you defin
 
 This helps you avoid typos and common mistakes, such as using `name` instead of `property`.
 
-```vue [app.vue]
+```vue twoslash [app.vue]
 <script setup lang="ts">
 useSeoMeta({
   title: 'My Amazing Site',
@@ -92,7 +92,7 @@ const title = ref('Hello World')
     <Head>
       <Title>{{ title }}</Title>
       <Meta name="description" :content="title" />
-      <Style type="text/css" children="body { background-color: green; }" />
+      <Style type="text/css" children="body { background-color: green; }" ></Style>
     </Head>
 
     <h1>{{ title }}</h1>
@@ -132,7 +132,7 @@ It's recommended to use getters (`() => value`) over computed (`computed(() => v
 
 ::code-group
 
-  ```vue [useHead]
+  ```vue twoslash [useHead]
   <script setup lang="ts">
   const description = ref('My amazing site.')
 
@@ -144,7 +144,7 @@ It's recommended to use getters (`() => value`) over computed (`computed(() => v
   </script>
   ```
 
-  ```vue [useSeoMeta]
+  ```vue twoslash [useSeoMeta]
   <script setup lang="ts">
   const description = ref('My amazing site.')
 
@@ -178,7 +178,7 @@ If you want to use a function (for full control), then this cannot be set in you
 
 ::code-group
 
-  ```vue [useHead]
+  ```vue twoslash [useHead]
   <script setup lang="ts">
   useHead({
     titleTemplate: (titleChunk) => {
@@ -198,7 +198,7 @@ You can use the `tagPosition: 'bodyClose'` option on applicable tags to append t
 
 For example:
 
-```vue
+```vue twoslash
 <script setup lang="ts">
 useHead({
   script: [
@@ -220,7 +220,7 @@ Within your [`pages/` directory](/docs/guide/directory-structure/pages), you can
 
 For example, you can first set the current page title (this is extracted at build time via a macro, so it can't be set dynamically):
 
-```vue [pages/some-page.vue]
+```vue twoslash [pages/some-page.vue]
 <script setup lang="ts">
 definePageMeta({
   title: 'Some Page'
@@ -230,7 +230,7 @@ definePageMeta({
 
 And then in your layout file, you might use the route's metadata you have previously set:
 
-```vue [layouts/default.vue]
+```vue twoslash [layouts/default.vue]
 <script setup lang="ts">
 const route = useRoute()
 
@@ -248,13 +248,20 @@ useHead({
 
 In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app:
 
-```vue [app.vue]
+```vue twoslash [app.vue]
 <script setup lang="ts">
 useHead({
   // as a string,
   // where `%s` is replaced with the title
   titleTemplate: '%s - Site Title',
-  // ... or as a function
+})
+</script>
+```
+
+```vue twoslash [app.vue]
+<script setup lang="ts">
+useHead({
+  // or as a function
   titleTemplate: (productCategory) => {
     return productCategory
       ? `${productCategory} - Site Title`
@@ -272,7 +279,7 @@ The example below shows how you might enable Google Fonts using either the `link
 
 ::code-group
 
-  ```vue [useHead]
+  ```vue twoslash [useHead]
   <script setup lang="ts">
   useHead({
     link: [