Migrate from v1 to v2

Word count

1306 words

Reading time

9 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'

Git-based page histories

UI config

1. mapContributors now deprecated, please use mapAuthors instead since it's more neutral for writers.
2. nameAliases now deprecated, please use mapByNameAliases instead, which is more clear and consistent with other plugins.
3. emailAliases now deprecated, please use mapByEmailAliases instead, which is more clear and consistent with other plugins.
4. Added new username field, which is the username of the author on GitHub used to fetch the avatar.
5. The locales in the original Vite plugin GitChangelogMarkdownSection no longer need to be configured and have been migrated to the UI configuration under locales:
   1. changelog.title
   2. contributors.title;
6. In order to better structure the organization of the i18n fields, the original
   1. noLogs i18n configuration changed to changelog.noData;
   2. noContributors i18n configuration was changed to contributors.noData.
   3. lastEdited i18n Configuration changed to lastEdited.
   4. lastEditedDateFnsLocaleName configuration changed to changelog.lastEditedDateFnsLocaleName
   5. viewFullHistory i18n Configuration changed to changelog.viewFullHistory
   6. committedOn i18n configuration changed to changelog.committedOn

Vite config

1. There is no longer a need to configure the locales field for GitChangelogMarkdownSection, and all of the internationalized i18n configuration has been migrated to the UI configuration.
2. includeDirs and includeExtensions have been deprecated and merged into include, which is a list of glob modes with ! negation.
3. If a renderable page file located outside of the VitePress root (where .vitepress lives), please configure the cwd (current working directory) to the parent directory of the page files. (For example, in a Monorepo, if the source file that rendered a page s located outside of docs/, you need to set cwd to the root directory of the Monorepo instead of the root of VitePress.)
4. No longer needed to configure rewritePaths, therefor rewritePaths is now deprecated, can be safely removed.
5. rewritePathsBy pattern should be configured in the against to filesystem paths, not the URL route paths.

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 Northword

BeiyanYunyi

Changelog

Last edited 2 days agoView full history

04fb1-refactor(git-changelog): migrate i18n to ui config (#213)

2fcfe-refactor: simplify mapContributors configuration (#210)

ee449-docs: migration guide for 2.0.0-rc11

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