feat(og-image): migrated to /vitepress entry (#165)

Signed-off-by: Neko Ayaka <[email protected]>

docs/.vitepress/config.ts

@@ -8,9 +8,11 @@ import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 
 import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'
 import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'
-import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image'
+import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image/vitepress'
 import { UnlazyImages } from '@nolebase/markdown-it-unlazy-img'
 
+import packageJSON from '../../package.json'
+
 export const sidebars: Record<string, DefaultTheme.Sidebar> = {
   'en': {
     '/': [
@@ -59,6 +61,20 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
           { text: 'Overview', link: '/pages/en/ui/' },
         ],
       },
+      {
+        text: 'Releasing',
+        items: [
+          {
+            text: 'Migration guides',
+            items: [
+              {
+                text: 'Migrate from v1 to v2',
+                link: '/pages/en/releases/migrations/v1-to-v2',
+              },
+            ],
+          },
+        ],
+      },
     ],
     '/pages/en/integrations/': [
       {
@@ -202,6 +218,20 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
           { text: '概览', link: '/pages/zh-CN/ui/' },
         ],
       },
+      {
+        text: '版本发布',
+        items: [
+          {
+            text: '迁移指南',
+            items: [
+              {
+                text: '自 v1 迁移至 v2',
+                link: '/pages/zh-CN/releases/migrations/v1-to-v2',
+              },
+            ],
+          },
+        ],
+      },
     ],
     '/pages/zh-CN/integrations/': [
       {
@@ -378,6 +408,20 @@ export default defineConfig({
           { text: 'Guide', link: '/pages/en/guide/getting-started' },
           { text: 'Integrations', link: '/pages/en/integrations/' },
           { text: 'UI Components', link: '/pages/en/ui/' },
+          {
+            text: packageJSON.version,
+            items: [
+              {
+                text: 'Migrations',
+                items: [
+                  {
+                    text: 'Migrate from v1 to v2',
+                    link: '/pages/en/releases/migrations/v1-to-v2',
+                  },
+                ],
+              },
+            ],
+          },
         ],
         sidebar: sidebars.en,
       },
@@ -393,6 +437,20 @@ export default defineConfig({
           { text: '指南', link: '/pages/zh-CN/guide/getting-started' },
           { text: '集成', link: '/pages/zh-CN/integrations/' },
           { text: 'UI 组件', link: '/pages/zh-CN/ui/' },
+          {
+            text: packageJSON.version,
+            items: [
+              {
+                text: '迁移指南',
+                items: [
+                  {
+                    text: '自 v1 迁移至 v2',
+                    link: '/pages/zh-CN/releases/migrations/v1-to-v2',
+                  },
+                ],
+              },
+            ],
+          },
         ],
         sidebar: sidebars['zh-CN'],
       },
@@ -466,7 +524,7 @@ export default defineConfig({
     },
   },
   async buildEnd(siteConfig) {
-    await buildEndGenerateOpenGraphImages({
+    const newBuilder = buildEndGenerateOpenGraphImages({
       baseUrl: 'https://nolebase-integrations.ayaka.io',
       category: {
         byPathPrefix: [
@@ -495,6 +553,8 @@ export default defineConfig({
         ],
         fallbackWithFrontmatter: true,
       },
-    })(siteConfig)
+    })
+
+    await newBuilder(siteConfig)
   },
 })

docs/pages/en/releases/migrations/index.md

@@ -0,0 +1,7 @@
+# Migration
+
+Currently the **ongoing developing version** of the project is: `v2`.
+
+You can find the migration guides here:
+
+- [Migrate from `v1` to `v2`](v1-to-v2.md)

docs/pages/en/releases/migrations/v1-to-v2.md

@@ -0,0 +1,232 @@
+# Migrate from `v1` to `v2`
+
+The primary goal of the version update to `v2` is:
+
+1. Update to VitePress `1.0.0`.
+2. Enforce all packages and modules follow the same code structure, naming conventions, imports/exports pattern.
+
+Therefore,
+
+1. All the updated packages will not compatible with VitePress RC versions anymore.
+2. All the updated packages will follow:
+  - Exported entry file is `{packageName}/client` if it is a Vue component, Vue plugin, client side code, styles, etc.
+  - Exported entry file is `{packageName}/locales` if it is a i18n module.
+  - Exported entry file is `{packageName}/vitepress` if it is a VitePress specific plugin (e.g. build hook, `buildEnd`, `transformHTML`, etc.)
+  - Exported entry file is `{packageName}/markdown-it` if it is a markdown-it plugin.
+  - Exported entry file is `{packageName}/vite` if it is a Vite plugin.
+3. All the updated packages will follow the same i18n guidelines across Nolebase packages.
+4. All the updated packages will try to re-use their Vue components from `@nolebase/ui` package.
+
+And breaking changes will be introduced, but with a migration guide, and less migration effort.
+
+## Inline links previewing
+
+There are some breaking changes in the `@nolebase/vitepress-plugin-inline-link-preview` plugin.
+
+1. No longer require the use of `@nolebase/markdown-it-element-transform` package, the new `@nolebase/vitepress-plugin-inline-link-preview/markdown-it` plugin will export the needed markdown-it plugin as a function that exported from `@nolebase/vitepress-plugin-inline-link-preview/markdown-it`.
+2. By following the new structure, the new `@nolebase/vitepress-plugin-inline-link-preview/client` will export the Vue component for the inline link previewing instead of the direct import from the package root.
+
+### Remove `@nolebase/markdown-it-element-transform`
+
+```json
+{
+  "devDependencies": {
+    "@nolebase/markdown-it-element-transform": "^1.28.0" // [!code --]
+  }
+}
+```
+
+You can perform the following steps to remove the `@nolebase/markdown-it-element-transform` package:
+
+::: code-group
+
+```shell [@antfu/ni]
+nun @nolebase/markdown-it-element-transform
+```
+
+```shell [pnpm]
+pnpm uninstall @nolebase/markdown-it-element-transform
+```
+
+```shell [yarn]
+yarn remove @nolebase/markdown-it-element-transform
+```
+
+```shell [npm]
+npm uninstall @nolebase/markdown-it-element-transform
+```
+
+:::
+
+### Update VitePress config to use the new markdown-it plugin exported from `@nolebase/vitepress-plugin-inline-link-preview/markdown-it`
+
+You can now use
+
+```ts
+import { defineConfig } from 'vitepress'
+import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it' // [!code ++]
+
+export default defineConfig({
+  // ...
+  markdown: {
+    // ...
+    config: (md) => {
+      md.use(InlineLinkPreviewElementTransform) // [!code ++]
+    },
+  },
+})
+```
+
+to replace the old way of using `@nolebase/markdown-it-element-transform`.
+
+Full changes:
+
+::: code-group
+
+```ts [.vitepress/config.ts]
+import { defineConfig } from 'vitepress'
+import { ElementTransform } from '@nolebase/markdown-it-element-transform'
+import type { Options as ElementTransformOptions } from '@nolebase/markdown-it-element-transform' // [!code --]
+import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it' // [!code ++]
+
+export default defineConfig({
+  // ...
+  markdown: {
+    // ...
+    config: (md) => {
+      md.use(ElementTransform, (() => {// [!code --]
+        let transformNextLinkCloseToken = false// [!code --]
+        // [!code --]
+        return { // [!code --]
+          transform(token) { // [!code --]
+            switch (token.type) { // [!code --]
+              case 'link_open': // [!code --]
+                if (token.attrGet('class') !== 'header-anchor') { // [!code --]
+                  token.tag = 'VPNolebaseInlineLinkPreview'// [!code --]
+                  transformNextLinkCloseToken = true // [!code --]
+                }
+                // [!code --]
+                break // [!code --]
+              case 'link_close': // [!code --]
+                if (transformNextLinkCloseToken) { // [!code --]
+                  token.tag = 'VPNolebaseInlineLinkPreview' // [!code --]
+                  transformNextLinkCloseToken = false // [!code --]
+                } // [!code --]
+                // [!code --]
+                break // [!code --]
+            } // [!code --]
+          }, // [!code --]
+        } as ElementTransformOptions // [!code --]
+      })()) // [!code --]
+
+      md.use(InlineLinkPreviewElementTransform) // [!code ++]
+    },
+  },
+})
+```
+
+:::
+
+### Update VitePress theme config to use the new Vue component exported from `@nolebase/vitepress-plugin-inline-link-preview/client`
+
+Since all the Vue components are now exported from the `client` entry file, you can now use
+
+```ts
+import {
+  NolebaseInlineLinkPreviewPlugin,
+} from '@nolebase/vitepress-plugin-inline-link-preview' // [!code --]
+} from '@nolebase/vitepress-plugin-inline-link-preview/client' // [!code ++]
+```
+
+to replace the old way of using `@nolebase/vitepress-plugin-inline-link-preview`.
+
+The same applies to the styles:
+
+```ts
+import '@nolebase/vitepress-plugin-inline-link-preview/dist/style.css' // [!code --]
+import '@nolebase/vitepress-plugin-inline-link-preview/client/style.css' // [!code ++]
+```
+
+## Enhanced readabilities
+
+There are some breaking changes in the `@nolebase/vitepress-plugin-enhanced-readabilities` plugin.
+
+1. By following the new structure, the new `@nolebase/vitepress-plugin-enhanced-readabilities/client` will export the Vue components for the enhanced readabilities instead of the direct import from the package root.
+
+### Update VitePress theme config to use the new Vue components exported from `@nolebase/vitepress-plugin-enhanced-readabilities/client`
+
+Since all the Vue components are now exported from the `client` entry file, you can now use
+
+```ts
+import {
+  InjectionKey as NolebaseEnhancedReadabilitiesInjectionKey,
+  LayoutMode as NolebaseEnhancedReadabilitiesLayoutMode,
+  NolebaseEnhancedReadabilitiesMenu,
+  NolebaseEnhancedReadabilitiesScreenMenu,
+} from '@nolebase/vitepress-plugin-enhanced-readabilities'  // [!code --]
+} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'  // [!code ++]
+```
+
+to replace the old way of using `@nolebase/vitepress-plugin-enhanced-readabilities`.
+
+The same applies to the styles:
+
+```ts
+import '@nolebase/vitepress-plugin-enhanced-readabilities/dist/style.css'  // [!code --]
+import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'  // [!code ++]
+```
+
+## Highlight targeted heading
+
+There are some breaking changes in the `@nolebase/vitepress-plugin-highlight-targeted-heading` plugin.
+
+1. By following the new structure, the new `@nolebase/vitepress-plugin-highlight-targeted-heading/client` will export the Vue components for the highlight targeted heading instead of the direct import from the package root.
+
+### Update VitePress theme config to use the new Vue components exported from `@nolebase/vitepress-plugin-highlight-targeted-heading/client`
+
+Since all the Vue components are now exported from the `client` entry file, you can now use
+
+```ts
+import {
+  NolebaseHighlightTargetedHeading,
+} from '@nolebase/vitepress-plugin-highlight-targeted-heading' // [!code --]
+} from '@nolebase/vitepress-plugin-highlight-targeted-heading/client' // [!code ++]
+```
+
+to replace the old way of using `@nolebase/vitepress-plugin-highlight-targeted-heading`.
+
+The same applies to the styles:
+
+```ts
+import '@nolebase/vitepress-plugin-highlight-targeted-heading/dist/style.css' // [!code --]
+import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css' // [!code ++]
+```
+
+## Previewing image (social media card) generation
+
+There are some breaking changes in the `@nolebase/vitepress-plugin-og-image` plugin.
+
+1. By following the new structure, the new `@nolebase/vitepress-plugin-og-image/vitepress` will export the VitePress specific plugin instead of the direct import from the package root.
+
+### Update VitePress config to use the new VitePress specific plugin exported from `@nolebase/vitepress-plugin-og-image/vitepress`
+
+You can now use
+
+```ts
+import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image' // [!code --]
+import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image/vitepress' // [!code ++]
+```
+
+to replace the old way of using `@nolebase/vitepress-plugin-og-image`.
+
+## Conclusion
+
+1. Rewrite all the import paths to follow the new structure.
+2. Remove the old packages that are no longer needed.
+
+That's it! Nothing else were impacted for the migration from `v1` to `v2`.
+
+We have improved the code structure, naming conventions, imports/exports pattern, and made the packages more consistent across the Nolebase ecosystem.
+Happy writing! 🎉
+
+See you next time in the `v3` migration guide!

docs/pages/zh-CN/releases/migrations/index.md

@@ -0,0 +1,7 @@
+# 迁移
+
+目前，该项目的**正在进行的开发版本**是：`v2`。
+
+您可以在这里找到迁移指南：
+
+- [自 `v1` 迁移至 `v2`](v1-to-v2.md)