Migrate from v1 to v2

Word count

992 words

Reading time

7 minutes

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

{
  "devDependencies": {
    "@nolebase/markdown-it-element-transform": "^1.28.0"
  }
}

You can perform the following steps to remove the @nolebase/markdown-it-element-transform package:

@antfu/ni

nun @nolebase/markdown-it-element-transform

pnpm

pnpm uninstall @nolebase/markdown-it-element-transform

yarn

yarn remove @nolebase/markdown-it-element-transform

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

import { defineConfig } from 'vitepress'
import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

export default defineConfig({
  // ...
  markdown: {
    // ...
    config: (md) => {
      md.use(InlineLinkPreviewElementTransform) 
    },
  },
})

to replace the old way of using @nolebase/markdown-it-element-transform.

Full changes:

.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'
import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

export default defineConfig({
  // ...
  markdown: {
    // ...
    config: (md) => {
      md.use(ElementTransform, (() => {
        let transformNextLinkCloseToken = false

        return { 
          transform(token) { 
            switch (token.type) { 
              case 'link_open': 
                if (token.attrGet('class') !== 'header-anchor') { 
                  token.tag = 'VPNolebaseInlineLinkPreview'
                  transformNextLinkCloseToken = true
                }

                break
              case 'link_close': 
                if (transformNextLinkCloseToken) { 
                  token.tag = 'VPNolebaseInlineLinkPreview'
                  transformNextLinkCloseToken = false
                } 

                break
            } 
          }, 
        } as ElementTransformOptions
      })()) 

      md.use(InlineLinkPreviewElementTransform) 
    },
  },
})

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

import {
  NolebaseInlineLinkPreviewPlugin,
} from '@nolebase/vitepress-plugin-inline-link-preview'
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

to replace the old way of using @nolebase/vitepress-plugin-inline-link-preview.

The same applies to the styles:

import '@nolebase/vitepress-plugin-inline-link-preview/dist/style.css'
import '@nolebase/vitepress-plugin-inline-link-preview/client/style.css'

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

import {
  InjectionKey as NolebaseEnhancedReadabilitiesInjectionKey,
  LayoutMode as NolebaseEnhancedReadabilitiesLayoutMode,
  NolebaseEnhancedReadabilitiesMenu,
  NolebaseEnhancedReadabilitiesScreenMenu,
} from '@nolebase/vitepress-plugin-enhanced-readabilities'
} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'

to replace the old way of using @nolebase/vitepress-plugin-enhanced-readabilities.

The same applies to the styles:

import '@nolebase/vitepress-plugin-enhanced-readabilities/dist/style.css'
import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'

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

import {
  NolebaseHighlightTargetedHeading,
} from '@nolebase/vitepress-plugin-highlight-targeted-heading'
} from '@nolebase/vitepress-plugin-highlight-targeted-heading/client'

to replace the old way of using @nolebase/vitepress-plugin-highlight-targeted-heading.

The same applies to the styles:

import '@nolebase/vitepress-plugin-highlight-targeted-heading/dist/style.css'
import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'

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

import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image'
import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image/vitepress'

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!

Contributors

Neko

File History

Last edited 4 days agoView full history

v2.0.0-rc3

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