docs: add vitepress-plugin-group-icons (#4437) [lunaria-ignore]

Co-authored-by: Divyansh Singh <[email protected]>

docs/.vitepress/config/shared.ts

@@ -5,6 +5,11 @@ import { search as koSearch } from './ko'
 import { search as ptSearch } from './pt'
 import { search as ruSearch } from './ru'
 import { search as zhSearch } from './zh'
+import {
+  groupIconMdPlugin,
+  groupIconVitePlugin,
+  localIconLoader
+} from 'vitepress-plugin-group-icons'
 
 export const shared = defineConfig({
   title: 'VitePress',
@@ -55,6 +60,7 @@ export const shared = defineConfig({
           `<button title="${codeCopyButtonTitle}" class="copy"></button>`
         )
       }
+      md.use(groupIconMdPlugin)
     }
   },
 
@@ -104,5 +110,18 @@ export const shared = defineConfig({
     },
 
     carbonAds: { code: 'CEBDT27Y', placement: 'vuejsorg' }
+  },
+  vite: {
+    plugins: [
+      groupIconVitePlugin({
+        customIcon: {
+          vitepress: localIconLoader(
+            import.meta.url,
+            '../../public/vitepress-logo-mini.svg'
+          ),
+          firebase: 'logos:firebase'
+        }
+      })
+    ]
   }
 })

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import Theme from 'vitepress/theme'
+import 'virtual:group-icons.css'
+
+export default Theme

docs/en/guide/custom-theme.md

@@ -49,8 +49,7 @@ interface EnhanceAppContext {
 
 The theme entry file should export the theme as its default export:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 
 // You can directly import Vue files in the theme entry
 // VitePress is pre-configured with @vitejs/plugin-vue.
@@ -72,8 +71,7 @@ Inside your layout component, it works just like a normal Vite + Vue 3 applicati
 
 The most basic layout component needs to contain a [`<Content />`](../reference/runtime-api#content) component:
 
-```vue
-<!-- .vitepress/theme/Layout.vue -->
+```vue [.vitepress/theme/Layout.vue]
 <template>
   <h1>Custom Layout!</h1>
 
@@ -172,17 +170,15 @@ If you wish to distribute the theme as an npm package, follow these steps:
 
 To consume an external theme, import and re-export it from the custom theme entry:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import Theme from 'awesome-vitepress-theme'
 
 export default Theme
 ```
 
 If the theme needs to be extended:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import Theme from 'awesome-vitepress-theme'
 
 export default {
@@ -195,8 +191,7 @@ export default {
 
 If the theme requires special VitePress config, you will need to also extend it in your own config:
 
-```ts
-// .vitepress/config.ts
+```ts [.vitepress/config.ts]
 import baseConfig from 'awesome-vitepress-theme/config'
 
 export default {
@@ -207,8 +202,7 @@ export default {
 
 Finally, if the theme provides types for its theme config:
 
-```ts
-// .vitepress/config.ts
+```ts [.vitepress/config.ts]
 import baseConfig from 'awesome-vitepress-theme/config'
 import { defineConfigWithTheme } from 'vitepress'
 import type { ThemeConfig } from 'awesome-vitepress-theme'

docs/en/guide/data-loading.md

@@ -8,8 +8,7 @@ Data loaders can be used to fetch remote data, or generate metadata based on loc
 
 A data loader file must end with either `.data.js` or `.data.ts`. The file should provide a default export of an object with the `load()` method:
 
-```js
-// example.data.js
+```js [example.data.js]
 export default {
   load() {
     return {
@@ -84,8 +83,7 @@ export default {
 
 When building a content focused site, we often need to create an "archive" or "index" page: a page where we list all available entries in our content collection, for example blog posts or API pages. We **can** implement this directly with the data loader API, but since this is such a common use case, VitePress also provides a `createContentLoader` helper to simplify this:
 
-```js
-// posts.data.js
+```js [posts.data.js]
 import { createContentLoader } from 'vitepress'
 
 export default createContentLoader('posts/*.md', /* options */)
@@ -135,8 +133,7 @@ import { data as posts } from './posts.data.js'
 
 The default data may not suit all needs - you can opt-in to transform the data using options:
 
-```js
-// posts.data.js
+```js [posts.data.js]
 import { createContentLoader } from 'vitepress'
 
 export default createContentLoader('posts/*.md', {
@@ -162,8 +159,7 @@ Check out how it is used in the [Vue.js blog](https://github.com/vuejs/blog/blob
 
 The `createContentLoader` API can also be used inside [build hooks](../reference/site-config#build-hooks):
 
-```js
-// .vitepress/config.js
+```js [.vitepress/config.js]
 export default {
   async buildEnd() {
     const posts = await createContentLoader('posts/*.md').load()

docs/en/guide/deploy.md

@@ -10,7 +10,7 @@ The following guides are based on some shared assumptions:
 - You are using the default build output directory (`.vitepress/dist`).
 - VitePress is installed as a local dependency in your project, and you have set up the following scripts in your `package.json`:
 
-  ```json
+  ```json [package.json]
   {
     "scripts": {
       "docs:build": "vitepress build docs",
@@ -121,7 +121,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
 
 1. Create a file named `deploy.yml` inside `.github/workflows` directory of your project with some content like this:
 
-   ```yaml
+   ```yaml [.github/workflows/deploy.yml]
    # Sample workflow for building and deploying a VitePress site to GitHub Pages
    #
    name: Deploy VitePress site to Pages
@@ -204,7 +204,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
 
 2. Create a file named `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
 
-   ```yaml
+   ```yaml [.gitlab-ci.yml]
    image: node:18
    pages:
      cache:
@@ -237,7 +237,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
 
    `firebase.json`:
 
-   ```json
+   ```json [firebase.json]
    {
      "hosting": {
        "public": "docs/.vitepress/dist",
@@ -248,7 +248,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
 
    `.firebaserc`:
 
-   ```json
+   ```json [.firebaserc]
    {
      "projects": {
        "default": "<YOUR_FIREBASE_ID>"
@@ -276,7 +276,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
 
 2. Create a file called `static.json` in the root of your project with the below content:
 
-   ```json
+   ```json [static.json]
    {
      "root": "docs/.vitepress/dist"
    }

docs/en/guide/extending-default-theme.md

@@ -22,8 +22,7 @@ Before proceeding, make sure to first read [Using a Custom Theme](./custom-theme
 
 The default theme CSS is customizable by overriding root level CSS variables:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme'
 import './custom.css'
 
@@ -46,8 +45,7 @@ VitePress uses [Inter](https://rsms.me/inter/) as the default font, and will inc
 
 To avoid including Inter in the build output, import the theme from `vitepress/theme-without-fonts` instead:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme-without-fonts'
 import './my-fonts.css'
 
@@ -68,8 +66,7 @@ If you are using optional components like the [Team Page](../reference/default-t
 
 If your font is a local file referenced via `@font-face`, it will be processed as an asset and included under `.vitepress/dist/assets` with hashed filename. To preload this file, use the [transformHead](../reference/site-config#transformhead) build hook:
 
-```js
-// .vitepress/config.js
+```js [.vitepress/config.js]
 export default {
   transformHead({ assets }) {
     // adjust the regex accordingly to match your font
@@ -94,8 +91,7 @@ export default {
 
 ## Registering Global Components
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme'
 
 /** @type {import('vitepress').Theme} */
@@ -109,8 +105,7 @@ export default {
 ```
 
 If you're using TypeScript:
-```ts
-// .vitepress/theme/index.ts
+```ts [.vitepress/theme/index.ts]
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 
@@ -129,8 +124,7 @@ Since we are using Vite, you can also leverage Vite's [glob import feature](http
 
 The default theme's `<Layout/>` component has a few slots that can be used to inject content at certain locations of the page. Here's an example of injecting a component into the before outline:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme'
 import MyLayout from './MyLayout.vue'
 
@@ -142,8 +136,7 @@ export default {
 }
 ```
 
-```vue
-<!--.vitepress/theme/MyLayout.vue-->
+```vue [.vitepress/theme/MyLayout.vue]
 <script setup>
 import DefaultTheme from 'vitepress/theme'
 
@@ -161,8 +154,7 @@ const { Layout } = DefaultTheme
 
 Or you could use render function as well.
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import { h } from 'vue'
 import DefaultTheme from 'vitepress/theme'
 import MyComponent from './MyComponent.vue'
@@ -224,9 +216,7 @@ Full list of slots available in the default theme layout:
 
 You can extend the default theme to provide a custom transition when the color mode is toggled. An example:
 
-```vue
-<!-- .vitepress/theme/Layout.vue -->
-
+```vue [.vitepress/theme/Layout.vue]
 <script setup lang="ts">
 import { useData } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'

docs/en/guide/getting-started.md

@@ -120,8 +120,7 @@ By default, VitePress stores its dev server cache in `.vitepress/cache`, and the
 
 The config file (`.vitepress/config.js`) allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site:
 
-```js
-// .vitepress/config.js
+```js [.vitepress/config.js]
 export default {
   // site-level options
   title: 'VitePress',
@@ -147,7 +146,7 @@ VitePress also provides the ability to generate clean URLs, rewrite paths, and d
 
 The tool should have also injected the following npm scripts to your `package.json` if you allowed it to do so during the setup process:
 
-```json
+```json [package.json]
 {
   ...
   "scripts": {

docs/en/guide/i18n.md

@@ -13,7 +13,7 @@ docs/
 
 Then in `docs/.vitepress/config.ts`:
 
-```ts
+```ts [docs/.vitepress/config.ts]
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
@@ -77,8 +77,7 @@ However, VitePress won't redirect `/` to `/en/` by default. You'll need to confi
 
 **Pro tip:** If using the above approach, you can use `nf_lang` cookie to persist user's language choice:
 
-```ts
-// docs/.vitepress/theme/index.ts
+```ts [docs/.vitepress/theme/index.ts]
 import DefaultTheme from 'vitepress/theme'
 import Layout from './Layout.vue'
 
@@ -88,9 +87,7 @@ export default {
 }
 ```
 
-```vue
-<!-- docs/.vitepress/theme/Layout.vue -->
-<script setup lang="ts">
+```vue [docs/.vitepress/theme/Layout.vue]<script setup lang="ts">
 import DefaultTheme from 'vitepress/theme'
 import { useData, inBrowser } from 'vitepress'
 import { watchEffect } from 'vue'

docs/en/guide/markdown.md

@@ -905,8 +905,7 @@ This is currently opt-in. To enable it, you need to install `markdown-it-mathjax
 npm add -D markdown-it-mathjax3
 ```
 
-```ts
-// .vitepress/config.ts
+```ts [.vitepress/config.ts]
 export default {
   markdown: {
     math: true

docs/en/guide/routing.md

@@ -178,8 +178,7 @@ packages/pkg-b/src/bar.md    -->  /pkg-b/bar.html
 
 You can achieve this by configuring the [`rewrites`](../reference/site-config#rewrites) option like this:
 
-```ts
-// .vitepress/config.js
+```ts [.vitepress/config.js]
 export default {
   rewrites: {
     'packages/pkg-a/src/index.md': 'pkg-a/index.md',

docs/en/guide/ssr-compat.md

@@ -50,8 +50,7 @@ if (!import.meta.env.SSR) {
 
 Since [`Theme.enhanceApp`](./custom-theme#theme-interface) can be async, you can conditionally import and register Vue plugins that access browser APIs on import:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 /** @type {import('vitepress').Theme} */
 export default {
   // ...
@@ -65,8 +64,7 @@ export default {
 ```
 
 If you're using TypeScript:
-```ts
-// .vitepress/theme/index.ts
+```ts [.vitepress/theme/index.ts]
 import type { Theme } from 'vitepress'
 
 export default {

docs/en/reference/default-theme-nav.md

@@ -165,8 +165,7 @@ Refer [`socialLinks`](./default-theme-config#sociallinks).
 
 You can include custom components in the navigation bar by using the `component` option. The `component` key should be the Vue component name, and must be registered globally using [Theme.enhanceApp](../guide/custom-theme#theme-interface).
 
-```js
-// .vitepress/config.js
+```js [.vitepress/config.js]
 export default {
   themeConfig: {
     nav: [
@@ -192,8 +191,7 @@ export default {
 
 Then, you need to register the component globally:
 
-```js
-// .vitepress/theme/index.js
+```js [.vitepress/theme/index.js]
 import DefaultTheme from 'vitepress/theme'
 
 import MyCustomComponent from './components/MyCustomComponent.vue'