From 9a3cacd19141f5a88cfdce923375b06466fc4dbb Mon Sep 17 00:00:00 2001 From: Matias Capeletto Date: Wed, 16 Dec 2020 11:34:44 +0100 Subject: [PATCH] docs: improve migrating from vuepress guide --- docs/guide/migrating-from-vuepress.md | 132 ++++++++++++++------------ 1 file changed, 72 insertions(+), 60 deletions(-) diff --git a/docs/guide/migrating-from-vuepress.md b/docs/guide/migrating-from-vuepress.md index dc450586..5df44fc8 100644 --- a/docs/guide/migrating-from-vuepress.md +++ b/docs/guide/migrating-from-vuepress.md @@ -1,6 +1,6 @@ # Migrating from VuePress -VitePress follows VuePress config and default theme API where possible to ease the migration path. There are although some features that are not present in vitepress because of differences in the [design goals](../index.md) of the two projects. VitePress aims to have bare minimal features for authoring docs and most features are pushed to the Themes, where else VuePress has those features enabled by plugins. +VitePress follows VuePress config and default theme API where possible to ease the migration path. However, there are some features that are not present in VitePress because of differences in the [design goals](../index.md) of the two projects. VitePress aims to have bare minimal features for authoring docs and most features are pushed to the Themes, whereas VuePress has those features enabled by plugins. This is a list of changes and removed features compared to [VuePress v1.7.1](https://github.com/vuejs/vuepress/releases/tag/v1.7.1) @@ -14,92 +14,104 @@ Some of these differences may be gone before Vitepress 1.0 is released. ## General -- YAML and TOML are not supported formats for site config. Only javascript is supported for `.vitepress/config.js` -- removed [Plugins](https://vuepress.vuejs.org/plugin/) support, features are implemented in themes -- removed [permalink support](https://vuepress.vuejs.org/guide/permalinks.html) -- Components in `.vitepress/components` [are not auto registered as global components](https://vuepress.vuejs.org/) -- [Public files](https://vuepress.vuejs.org/guide/assets.html#public-files) that are directly copied to dist root moved from `.vitepress/public/` to `public/` -- Changed [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements moved from `.vitepress/enhanceApp.js` to `.vitepress/theme/index.js`. -- removed [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl`. -- removed `.vitepress/templates` +- Removed + - YAML and TOML are not supported formats for site config. Only javascript is supported for `.vitepress/config.js` + - [Plugins](https://vuepress.vuejs.org/plugin/) support, features are implemented in themes + - [permalink support](https://vuepress.vuejs.org/guide/permalinks.html) + - `.vitepress/templates` + - Components in `.vitepress/components` [are not auto registered as global components](https://vuepress.vuejs.org/) +- Changed + - [Public files](https://vuepress.vuejs.org/guide/assets.html#public-files) that are directly copied to dist root moved from `.vitepress/public/` to `public/` + - [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl` changed to `.vitepress/style.styl` + - [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements moved from `.vitepress/enhanceApp.js` to `.vitepress/theme/index.js`. ## Markdown -- removed support for [toml in frontmatter](https://vuepress.vuejs.org/guide/frontmatter.html#alternative-frontmatter-formats) -- removed [details block](https://vuepress.vuejs.org/guide/markdown.html#custom-containers) -- removed [markdown slots](https://vuepress.vuejs.org/guide/markdown-slot.html) - guide/using-vue.html#using-components). -- removed `~` prefix to explicitly specify a url is a [webpack module request](https://vuepress.vuejs.org/guide/assets.html#relative-urls) +- Removed + - Support for [toml in frontmatter](https://vuepress.vuejs.org/guide/frontmatter.html#alternative-frontmatter-formats) + - [details block](https://vuepress.vuejs.org/guide/markdown.html#custom-containers) + - [markdown slots](https://vuepress.vuejs.org/guide/markdown-slot.html) + guide/using-vue.html#using-components). + - `~` prefix to explicitly specify a url is a [webpack module request](https://vuepress.vuejs.org/guide/assets.html#relative-urls) ## Site Config -- renamed `temp` to `tempDir` -- renamed `dest` to `outDir` -- removed [`theme` from a dependency](https://vuepress.vuejs.org/theme/using-a-theme.html#using-a-theme-from-a-dependency) -- removed `permalink` -- removed [`port`](https://vuepress.vuejs.org/config/#port) -- removed [`shouldPrefetch`](https://vuepress.vuejs.org/config/#shouldprefetch) -- removed [`cache`](https://vuepress.vuejs.org/config/#cache) -- removed [`extraWatchFiles`](https://vuepress.vuejs.org/config/#extrawatchfiles) -- removed [`patterns`](https://vuepress.vuejs.org/config/#patterns) -- removed [`plugins`](https://vuepress.vuejs.org/config/#pluggable) -- removed [`markdown.pageSuffix`](https://vuepress.vuejs.org/config/#markdown-pagesuffix) -- removed [`markdown.slugify`](https://vuepress.vuejs.org/config/#markdown-slugify) -- removed [`markdown.plugins`](https://vuepress.vuejs.org/config/#markdown-plugins) -- removed [`markdown.extractHeaders`](https://vuepress.vuejs.org/config/#markdown-extractheaders) -- renamed `markdown.extendMarkdown` to `markdown.config` -- removed `configureWebpack`, `chainWebpack`, `postcss`, `Stylus`, `scss`, `Sass`, `less` configs -- removed [`evergreen`](https://vuepress.vuejs.org/config/#evergreen) +- Removed + - `temp` + - `dest` + - [`theme` from a dependency](https://vuepress.vuejs.org/theme/using-a-theme.html#using-a-theme-from-a-dependency) + - `permalink` + - [`port`](https://vuepress.vuejs.org/config/#port) + - [`shouldPrefetch`](https://vuepress.vuejs.org/config/#shouldprefetch) + - [`cache`](https://vuepress.vuejs.org/config/#cache) + - [`extraWatchFiles`](https://vuepress.vuejs.org/config/#extrawatchfiles) + - [`patterns`](https://vuepress.vuejs.org/config/#patterns) + - [`plugins`](https://vuepress.vuejs.org/config/#pluggable) + - [`markdown.pageSuffix`](https://vuepress.vuejs.org/config/#markdown-pagesuffix) + - [`markdown.slugify`](https://vuepress.vuejs.org/config/#markdown-slugify) + - [`markdown.plugins`](https://vuepress.vuejs.org/config/#markdown-plugins) + - [`markdown.extractHeaders`](https://vuepress.vuejs.org/config/#markdown-extractheaders) + - `markdown.extendMarkdown` to `markdown.config` + - `configureWebpack`, `chainWebpack`, `postcss`, `Stylus`, `scss`, `Sass`, `less` configs + - [`evergreen`](https://vuepress.vuejs.org/config/#evergreen) ## Default Theme Config -- removed [`smoothScroll`](https://vuepress.vuejs.org/theme/default-theme-config.html#smooth-scrolling) -- removed [`displayAllHeaders`](https://vuepress.vuejs.org/theme/default-theme-config.html#displaying-header-links-of-all-pages) -- removed [`activeHeaderLinks`](https://vuepress.vuejs.org/theme/default-theme-config.html#active-header-links) -- removed `sidebarDepth` and `initialOpenGroupIndex` for [sidebar groups](https://vuepress.vuejs.org/theme/default-theme-config.html#sidebar-groups) -- renamed `searchMaxSuggestions` to `search.maxSuggestions` -- renamed `algolia` to `search.algolia` -- renamed `searchPlaceholder` to `search.placeholder` +- Removed + - [`smoothScroll`](https://vuepress.vuejs.org/theme/default-theme-config.html#smooth-scrolling) + - [`displayAllHeaders`](https://vuepress.vuejs.org/theme/default-theme-config.html#displaying-header-links-of-all-pages) + - [`activeHeaderLinks`](https://vuepress.vuejs.org/theme/default-theme-config.html#active-header-links) + - `sidebarDepth` and `initialOpenGroupIndex` for [sidebar groups](https://vuepress.vuejs.org/theme/default-theme-config.html#sidebar-groups) +- Renamed + - `searchMaxSuggestions` to `search.maxSuggestions` + - `algolia` to `search.algolia` + - `searchPlaceholder` to `search.placeholder` # Default Theme -- removed [`` and ``](https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks) +- Removed + - [`` and ``](https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks) ## Computed Globals -- removed `$lang` -- removed `$localePath` +- Removed + - `$lang` + - `$localePath` ## Frontmatter Predefined Variables -- removed `description` -- removed `meta` -- removed `lang` -- removed [`layout`](https://vuepress.vuejs.org/guide/frontmatter.html#layout) -- removed [`permalink`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) -- removed [`canonicalUrl`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) -- removed [`metaTitle`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) -- removed [`meta`](https://vuepress.vuejs.org/guide/frontmatter.html#meta) +- Removed + - `description` + - [`meta`](https://vuepress.vuejs.org/guide/frontmatter.html#meta) + - [`metaTitle`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) + - `lang` + - [`layout`](https://vuepress.vuejs.org/guide/frontmatter.html#layout) + - [`permalink`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) + - [`canonicalUrl`](https://vuepress.vuejs.org/guide/frontmatter.html#predefined-variables) ## Frontmatter Default Theme Variables -- removed `prev`, `next`, -- removed [`search`](https://vuepress.vuejs.org/guide/frontmatter.html#search) -- removed [`tags`](https://vuepress.vuejs.org/guide/frontmatter.html#tags) -- removed [`pageClass`](https://vuepress.vuejs.org/theme/default-theme-config.html#custom-page-class) -- removed [`layout`](https://vuepress.vuejs.org/theme/default-theme-config.html#custom-layout-for-specific-pages) +- Removed + - `prev`, `next` + - [`search`](https://vuepress.vuejs.org/guide/frontmatter.html#search) + - [`tags`](https://vuepress.vuejs.org/guide/frontmatter.html#tags) + - [`pageClass`](https://vuepress.vuejs.org/theme/default-theme-config.html#custom-page-class) + - [`layout`](https://vuepress.vuejs.org/theme/default-theme-config.html#custom-layout-for-specific-pages) ## siteData -- removed [`pages`](https://vuepress.vuejs.org/theme/writing-a-theme.html#site-and-page-metadata) +- Removed + - [`pages`](https://vuepress.vuejs.org/theme/writing-a-theme.html#site-and-page-metadata) ## pageData -- removed `key` -- removed `path` -- removed `regularPath` +- Removed + - `key` + - `path` + - `regularPath` ## Default Components -- removed [``](https://vuepress.vuejs.org/guide/using-vue.html#browser-api-access-restrictions) -- removed [``](https://vuepress.vuejs.org/guide/using-vue.html#badge) +- Removed + - [``](https://vuepress.vuejs.org/guide/using-vue.html#browser-api-access-restrictions) + - [``](https://vuepress.vuejs.org/guide/using-vue.html#badge)