diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 4cd9cd30..00000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: 'bug: pending triage' -assignees: '' - ---- - - - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**System Info** -- vitepress version: -- vite version: -- Node version: -- OS version: - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..f3bb8f2c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: "\U0001F41E Bug report" +description: Create a report to help us improve +labels: ['bug: pending triage'] +body: + - type: markdown + attributes: + value: | + "Thanks for taking the time to fill out this bug report! + VitePress is still WIP, and it is not compatible with VuePress. + Please do not open issue about default theme missing features or something doesn't work like VuePress." + - type: textarea + id: bug-description + attributes: + label: Describe the bug + description: A clear and concise description of what the bug is. If you intend to submit a PR for this issue, tell us in the description. Thanks! + placeholder: Bug description + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction + description: Steps to reproduce the behavior + placeholder: Reproduction + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: A clear and concise description of what you expected to happen. + placeholder: Expected behavior + validations: + required: true + - type: textarea + id: system-info + attributes: + label: System Info + description: Output of `npx envinfo --system --npmPackages vitepress --binaries --browsers` + render: shell + placeholder: System, Binaries, Browsers + validations: + required: true + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context or screenshots about the bug report here. + - type: checkboxes + id: checkboxes + attributes: + label: Validations + description: Before submitting the issue, please make sure you do the following + options: + - label: Follow our [Code of Conduct](https://vuejs.org/about/coc.html) + required: true + - label: Read the [docs](https://vitepress.vuejs.org). + required: true + - label: Check that there isn't already an issue that reports the same bug to avoid creating a duplicate. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index bbcbbe7d..00000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: '' -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..0750eb76 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,45 @@ +name: "\U0001F680 New feature proposal" +description: Suggest an idea for this project +body: + - type: markdown + attributes: + value: | + Thanks for your interest in the project and taking the time to fill out this feature report! + - type: textarea + id: feature-description + attributes: + label: Is your feature request related to a problem? Please describe. + description: "A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]" + validations: + required: true + - type: textarea + id: suggested-solution + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + id: alternative + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context or screenshots about the feature request here. + - type: checkboxes + id: checkboxes + attributes: + label: Validations + description: Before submitting the issue, please make sure you do the following + options: + - label: Follow our [Code of Conduct](https://vuejs.org/about/coc.html) + required: true + - label: Read the [docs](https://vitepress.vuejs.org). + required: true + - label: Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/main/.github/contributing.md). + required: true + - label: Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate. + required: true diff --git a/.github/commit-convention.md b/.github/commit-convention.md index 40b187d6..e90c02e4 100644 --- a/.github/commit-convention.md +++ b/.github/commit-convention.md @@ -6,7 +6,7 @@ Messages must be matched by the following regex: -``` js +```js /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip)(\(.+\))?: .{1,50}/ ``` @@ -44,7 +44,7 @@ This reverts commit 667ecc1654a317a13331b17617d973392f415f02. ### Full Message Format -A commit message consists of a **header**, **body** and **footer**. The header has a **type**, **scope** and **subject**: +A commit message consists of a **header**, **body** and **footer**. The header has a **type**, **scope** and **subject**: ``` (): @@ -74,9 +74,9 @@ The scope could be anything specifying the place of the commit change. For examp The subject contains a succinct description of the change: -* use the imperative, present tense: "change" not "changed" nor "changes" -* don't capitalize the first letter -* no dot (.) at the end +- use the imperative, present tense: "change" not "changed" nor "changes" +- don't capitalize the first letter +- no dot (.) at the end ### Body diff --git a/.github/contributing.md b/.github/contributing.md index 9604e8ed..11c8617f 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -7,7 +7,7 @@ Hi! We're really excited that you are interested in contributing to VitePress. B ## Pull Request Guidelines -- Checkout a topic branch from the relevant branch, e.g. `master`, and merge back against that branch. +- Checkout a topic branch from the relevant branch, e.g. `main`, and merge back against that branch. - If adding a new feature: @@ -23,26 +23,27 @@ Hi! We're really excited that you are interested in contributing to VitePress. B ## Development Setup -You will need [Yarn](https://classic.yarnpkg.com/en/docs/cli/install/)/ +You will need [pnpm](https://pnpm.io) After cloning the repo, run: ```bash -$ yarn # install the dependencies of the project +# install the dependencies of the project +$ pnpm install ``` ### Setup VitePress Dev Environment -You may start VitePress local dev environment by running `yarn dev`. +You may start VitePress local dev environment by running `pnpm run dev`. ```bash -$ yarn dev +$ pnpm run dev ``` -The easiest way to start testing out VitePress is to tweak the VitePress docs. You may run `yarn docs` folder to boot up VitePress documentation site locally, with live reloading of the source code. +The easiest way to start testing out VitePress is to tweak the VitePress docs. You may run `pnpm run docs` folder to boot up VitePress documentation site locally, with live reloading of the source code. ```bash -$ yarn docs +$ pnpm run docs ``` After executing the above command, visit http://localhost:3000 and try modifying the source code. You'll get live update. diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml new file mode 100644 index 00000000..110e3fd5 --- /dev/null +++ b/.github/workflows/release-tag.yml @@ -0,0 +1,23 @@ +on: + push: + tags: + - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10 + +name: Create Release + +jobs: + build: + name: Create Release + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@master + - name: Create Release for Tag + id: release_tag + uses: yyx990803/release-tag@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + body: | + Please refer to [CHANGELOG.md](https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md) for details. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 488ab91f..3445704c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -7,14 +7,27 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node-version: [14, 15] + node-version: [14, 16] steps: - - uses: actions/checkout@v1 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v1 + - name: Checkout + uses: actions/checkout@v2 + + - name: Install pnpm + uses: pnpm/action-setup@v2.0.1 + with: + version: 6.15.1 + + - name: Set node version to ${{ matrix.node_version }} + uses: actions/setup-node@v2 with: - node-version: ${{ matrix.node-version }} - - name: install and test - run: | - yarn install - yarn test + node-version: ${{ matrix.node_version }} + cache: 'pnpm' + + - name: Install deps + run: pnpm install + + - name: Build + run: pnpm run build + + - name: Test + run: pnpm run test diff --git a/.gitignore b/.gitignore index 5447996f..7c5ac29f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,12 @@ /coverage -/src/client/shared -/src/node/shared +/src/client/shared.ts +/src/node/shared.ts *.log .DS_Store .vite_opt_cache dist node_modules TODOs.md -.idea .vscode +.idea +pnpm-global diff --git a/CHANGELOG.md b/CHANGELOG.md index 52e56213..18f1c036 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,413 @@ +## [0.22.3](https://github.com/vuejs/vitepress/compare/v0.22.2...v0.22.3) (2022-02-22) + +### Bug Fixes + +- append base to links ([#502](https://github.com/vuejs/vitepress/issues/502)) ([804954c](https://github.com/vuejs/vitepress/commit/804954cf4d5417b1abcba9854ed5f064348292c5)), closes [#252](https://github.com/vuejs/vitepress/issues/252) +- avoid minimizing non-javascript inline scripts ([#517](https://github.com/vuejs/vitepress/issues/517)) ([779b789](https://github.com/vuejs/vitepress/commit/779b78902fc7b1f9e7806751c0ca1e229a2161ce)), closes [#538](https://github.com/vuejs/vitepress/issues/538) [#540](https://github.com/vuejs/vitepress/issues/540) +- **client router:** tolerant invalid hash selector typo ([#506](https://github.com/vuejs/vitepress/issues/506)) ([ffe0c40](https://github.com/vuejs/vitepress/commit/ffe0c40ebc42d7769b5378775cdffcab52d3cf11)) +- don't add .html to urls of non-html files ([#515](https://github.com/vuejs/vitepress/issues/515)) ([34d1542](https://github.com/vuejs/vitepress/commit/34d1542f466e2eed28b1be7153d1c3461d84528f)), closes [#265](https://github.com/vuejs/vitepress/issues/265) +- normalize relative img src ([#514](https://github.com/vuejs/vitepress/issues/514)) ([9270477](https://github.com/vuejs/vitepress/commit/9270477fa59545978dc2732ac0a8091bed39625f)), closes [#450](https://github.com/vuejs/vitepress/issues/450) +- require at least node v14 ([#546](https://github.com/vuejs/vitepress/issues/546)) ([7cf7011](https://github.com/vuejs/vitepress/commit/7cf70111a5a00579d46453b682ef33169c7846c5)) +- reset page data on 404 ([#497](https://github.com/vuejs/vitepress/issues/497)) ([28eaa3b](https://github.com/vuejs/vitepress/commit/28eaa3b04ab71674330151d2a9b79d52c382e71e)) + +## [0.22.2](https://github.com/vuejs/vitepress/compare/v0.22.1...v0.22.2) (2022-02-14) + +### Features + +- improve default chunk strategy + page hash stability ([1ef69e2](https://github.com/vuejs/vitepress/commit/1ef69e212f91e43431b4fe4bdba17ca4f29a7b49)) + +## [0.22.1](https://github.com/vuejs/vitepress/compare/v0.22.0...v0.22.1) (2022-02-14) + +### Features + +- automatically update hash map + retry on failed page fetch ([2324948](https://github.com/vuejs/vitepress/commit/23249483d60da1952c64a1f764873652b587c2dc)) +- use git-based lastUpdated data ([d32d8d4](https://github.com/vuejs/vitepress/commit/d32d8d441917dcb480a6735da78c2d6fc3e589c0)) + + Note: lastUpdated data is now disabled by default due to the performance overhead of retrieving the git information. This also means each page's metadata object no longer contains the `lastUpdated` property by default - it will only be present if the new `lastUpdated: true` config option is enabled. + +# [0.22.0](https://github.com/vuejs/vitepress/compare/v0.21.6...v0.22.0) (2022-02-11) + +- Upgrade to Vite 2.8 + +## [0.21.6](https://github.com/vuejs/vitepress/compare/v0.21.5...v0.21.6) (2022-01-19) + +### Perf + +- Avoid wrapping siteData as readonly proxy in production builds + +## [0.21.5](https://github.com/vuejs/vitepress/compare/v0.21.4...v0.21.5) (2022-01-16) + +### Bug Fixes + +- allow overriding title if home is true ([#493](https://github.com/vuejs/vitepress/issues/493)) ([88d57a9](https://github.com/vuejs/vitepress/commit/88d57a93ef2689a8f5344b7f38b26db5ea86759b)) +- **types:** fix vitepress/theme type ([eabf6d2](https://github.com/vuejs/vitepress/commit/eabf6d2aa69d2a5452042bbb59edbbbc95aece87)), closes [#489](https://github.com/vuejs/vitepress/issues/489) [#438](https://github.com/vuejs/vitepress/issues/438) [#494](https://github.com/vuejs/vitepress/issues/494) [#442](https://github.com/vuejs/vitepress/issues/442) + +### Features + +- scrollOffset option ([b66785d](https://github.com/vuejs/vitepress/commit/b66785d68a86c118a7a036f3de8b3e504390f1da)) + +## [0.21.4](https://github.com/vuejs/vitepress/compare/v0.21.3...v0.21.4) (2022-01-07) + +### Bug Fixes + +- set \_\_data in md.render ([dfbc932](https://github.com/vuejs/vitepress/commit/dfbc932fac50d39b047b211cedca0dcce05aebc8)) + +## [0.21.3](https://github.com/vuejs/vitepress/compare/v0.21.2...v0.21.3) (2022-01-06) + +### Bug Fixes + +- prioritize vue installed in user project root ([9b3243b](https://github.com/vuejs/vitepress/commit/9b3243b75752209943af5b247f5d38e641d4ff6d)) + +## [0.21.2](https://github.com/vuejs/vitepress/compare/v0.21.1...v0.21.2) (2022-01-06) + +## [0.21.1](https://github.com/vuejs/vitepress/compare/v0.21.0...v0.21.1) (2022-01-06) + +### Performance Improvements + +- do not include head config in client bundle for production ([6f3a96f](https://github.com/vuejs/vitepress/commit/6f3a96f06daec4baad4420b54137a7afb1512e7f)) + +# [0.21.0](https://github.com/vuejs/vitepress/compare/v0.20.10...v0.21.0) (2022-01-06) + +### Bug Fixes + +- Chinese file link build failed ([#425](https://github.com/vuejs/vitepress/issues/425)) ([ae029ae](https://github.com/vuejs/vitepress/commit/ae029ae9e17fa6df1d2f89043f1891271e9c5b9b)), closes [#424](https://github.com/vuejs/vitepress/issues/424) +- initial render of 404 pages ([#418](https://github.com/vuejs/vitepress/issues/418)) ([a3bf52f](https://github.com/vuejs/vitepress/commit/a3bf52fed53e82b9756c844f6bdd576662d2e726)) +- remove `.` for mjs in `supportedConfigExtensions` ([#447](https://github.com/vuejs/vitepress/issues/447)) ([fb6a4ad](https://github.com/vuejs/vitepress/commit/fb6a4ad3e008af9ce4393fb3ca37645f4efba951)) +- **serve:** respect base config in serve mode ([#470](https://github.com/vuejs/vitepress/issues/470)) ([08a0b12](https://github.com/vuejs/vitepress/commit/08a0b129928cef44e613ff410d769a7ac7bf5fa3)), closes [#416](https://github.com/vuejs/vitepress/issues/416) +- set tempDir outside package root ([#439](https://github.com/vuejs/vitepress/issues/439)) ([bd35451](https://github.com/vuejs/vitepress/commit/bd35451ed42d7b5c47e2b49a7e659807cd7d7a0c)), closes [#435](https://github.com/vuejs/vitepress/issues/435) +- use algolia search lang ([#459](https://github.com/vuejs/vitepress/issues/459)) ([444562c](https://github.com/vuejs/vitepress/commit/444562c3a763bab7a9c0ebfca5eec635e142a61f)) + +### Features + +- add details custom container ([#455](https://github.com/vuejs/vitepress/issues/455)) ([a8f147f](https://github.com/vuejs/vitepress/commit/a8f147f153efdd17989a02eb620c3ae9ab0d13dd)) +- catch localhost links as dead links ([7387649](https://github.com/vuejs/vitepress/commit/7387649ff7c621402e49e26493b4eed25006fb4b)) +- expose `__path` and `__relativePath` on md instance for md plugins ([4cec660](https://github.com/vuejs/vitepress/commit/4cec660401d8d01830e5a11b9c66bc0ac5a935db)) +- improve typescript support for config file, add `defineConfigWithTheme` ([#465](https://github.com/vuejs/vitepress/issues/465)) ([ba41bb9](https://github.com/vuejs/vitepress/commit/ba41bb90551c01b9f84de2d2d3bc1920ce2ebe93)) +- properly remove `{#custom-anchor}` syntax in headers ([6120da2](https://github.com/vuejs/vitepress/commit/6120da25a87f6bec3918be804e95f2b3c8afb6c8)) +- user configurable `outDir` ([#448](https://github.com/vuejs/vitepress/issues/448)) ([5b04bb9](https://github.com/vuejs/vitepress/commit/5b04bb9eb5ced720414f4b0d729fde36432dd451)) + +## [0.20.10](https://github.com/vuejs/vitepress/compare/v0.20.9...v0.20.10) (2021-12-25) + +### Features + +- minify head inline scripts ([e61db62](https://github.com/vuejs/vitepress/commit/e61db62a1c49cb5f368a152221bfa60737dbbc6a)) + +## [0.20.9](https://github.com/vuejs/vitepress/compare/v0.20.8...v0.20.9) (2021-12-15) + +### Features + +- shouldPreload hook ([e721d60](https://github.com/vuejs/vitepress/commit/e721d605851be4e27f4948d96d5c3bab6d23ead2)) +- support array of patterns in data loaders ([f5308d7](https://github.com/vuejs/vitepress/commit/f5308d746f3089ef6818b0139fe249827a47628b)) + +## [0.20.8](https://github.com/vuejs/vitepress/compare/v0.20.7...v0.20.8) (2021-12-14) + +## [0.20.7](https://github.com/vuejs/vitepress/compare/v0.20.6...v0.20.7) (2021-12-14) + +### Features + +- **types:** re-export vite client type ([4caa7b2](https://github.com/vuejs/vitepress/commit/4caa7b231753ddedb83365a37b8c259ae461bd37)) + +## [0.20.6](https://github.com/vuejs/vitepress/compare/v0.20.4...v0.20.6) (2021-12-14) + +### Features + +- support static data loaders ([26fe81c](https://github.com/vuejs/vitepress/commit/26fe81c88618d7df5d623d041ac3df96e7d7ee7b)) + +## [0.20.5](https://github.com/vuejs/vitepress/compare/v0.20.4...v0.20.5) (2021-12-12) + +- Bump vue & vite versions + +## [0.20.4](https://github.com/vuejs/vitepress/compare/v0.20.3...v0.20.4) (2021-12-07) + +### Bug Fixes + +- **build:** fix typing files ([ae11dc0](https://github.com/vuejs/vitepress/commit/ae11dc0b59ac90375079f1ebf0efacf1b1e58e8d)) + +## [0.20.3](https://github.com/vuejs/vitepress/compare/v0.20.2...v0.20.3) (2021-12-07) + +### Features + +- expose createMarkdownRenderer ([d54c7d8](https://github.com/vuejs/vitepress/commit/d54c7d8c56973dac138bfe96ff16dfab162ef64b)) + +## [0.20.2](https://github.com/vuejs/vitepress/compare/v0.20.1...v0.20.2) (2021-12-06) + +### Bug Fixes + +- handle potential string quote mismatch in generated code ([dfa7c05](https://github.com/vuejs/vitepress/commit/dfa7c0525f010994437acb060867d9ca1572867d)) +- improve createStaticVNode match for rollup codegen compat ([abb1b57](https://github.com/vuejs/vitepress/commit/abb1b578cdedf184ae386ce455e60a23672adfcb)) +- lazy require @vitejs/plugin-vue to respect NODE_ENV ([a051e66](https://github.com/vuejs/vitepress/commit/a051e66f1ae211174cf470d4430427dc0189194b)) +- static string strip regex for mulitiline static strings ([bc486aa](https://github.com/vuejs/vitepress/commit/bc486aae563fd77f38da44d9ae3ea28c021f6df0)) + +### Features + +- upgrade docsearch version ([#441](https://github.com/vuejs/vitepress/issues/441)) ([1b245e2](https://github.com/vuejs/vitepress/commit/1b245e22d8a00ea7c01c052ac1ea3d8d94aaeefb)) + +## [0.20.1](https://github.com/vuejs/vitepress/compare/v0.20.0...v0.20.1) (2021-11-05) + +### Bug Fixes + +- **hmr:** avoid relying on revertd vite hmr behavior ([4114674](https://github.com/vuejs/vitepress/commit/4114674c69f917ff2e611ec30eb72d224f175f62)) + +# [0.20.0](https://github.com/vuejs/vitepress/compare/v0.19.2...v0.20.0) (2021-10-07) + +### Bug Fixes + +- fix code line hightlighting ([4c042b6](https://github.com/vuejs/vitepress/commit/4c042b61e7beb70d0a0b77cc9a00d725c7863089)), closes [#408](https://github.com/vuejs/vitepress/issues/408) +- invalid active props when `base` option is added ([#342](https://github.com/vuejs/vitepress/issues/342)) ([383d8ff](https://github.com/vuejs/vitepress/commit/383d8ffbba5283774e0f1e39302a29efc0db7e79)) +- make config hmr work in window ([#364](https://github.com/vuejs/vitepress/issues/364)) ([58663bb](https://github.com/vuejs/vitepress/commit/58663bbd02aa3da0efd939bd27de2ee5c0ab14d8)) +- print urls again ([df69b76](https://github.com/vuejs/vitepress/commit/df69b76427ab2c770010cd79e1076a1c414fb3bc)) +- support vite plugins provided via `config.vite` ([#394](https://github.com/vuejs/vitepress/issues/394)) ([4b76617](https://github.com/vuejs/vitepress/commit/4b7661762143b033e82fad526e256f7bc54df9af)) +- **theme-default/algolia:** avoid creating multiple algolia searches ([#292](https://github.com/vuejs/vitepress/issues/292)) ([389e863](https://github.com/vuejs/vitepress/commit/389e863b4d5e69c856d1e647d4d4c1807bd94c5d)) +- **theme:** fix algolia search filter ([5fd7db2](https://github.com/vuejs/vitepress/commit/5fd7db2b7fcd947d77c97b1e9bdaf83845c1321d)) +- tolerant invalid hash ([#399](https://github.com/vuejs/vitepress/issues/399)) ([efc5e1b](https://github.com/vuejs/vitepress/commit/efc5e1b2566eedc47a9420accae3dfba1a594ba4)) + +### Features + +- support ts/esm config file + defineConfig() helper ([d3b1521](https://github.com/vuejs/vitepress/commit/d3b1521ebef831e0d0307b3b12e4fc1f6ce4721a)), closes [#339](https://github.com/vuejs/vitepress/issues/339) [#376](https://github.com/vuejs/vitepress/issues/376) +- **theme-default:** home slot for customizing the entire homepage easily ([#314](https://github.com/vuejs/vitepress/issues/314)) ([07bf145](https://github.com/vuejs/vitepress/commit/07bf1451909ad615565e01d719e8a350ea07e69e)) + +## [0.19.2](https://github.com/vuejs/vitepress/compare/v0.19.1...v0.19.2) (2021-09-28) + +### Bug Fixes + +- encode urls that conflict w/ vite built-in replacements ([3940625](https://github.com/vuejs/vitepress/commit/3940625121455b7ad6e5ea8ebb3e1cf2faf9c7fc)) + +## [0.19.1](https://github.com/vuejs/vitepress/compare/v0.19.0...v0.19.1) (2021-09-21) + +- Fix build + +# [0.19.0](https://github.com/vuejs/vitepress/compare/v0.18.1...v0.19.0) (2021-09-21) + +### Features + +- upgrade vue, simplify deps ([9030486](https://github.com/vuejs/vitepress/commit/9030486409f10a59115d874b9365f71348ed76c2)) +- use `markdown-it-attrs` for markdown-it plugins ([#393](https://github.com/vuejs/vitepress/issues/393)) ([610e9b7](https://github.com/vuejs/vitepress/commit/610e9b7111462d3aace878017fa4d359cd2ae7ea)) + +## [0.18.1](https://github.com/vuejs/vitepress/compare/v0.18.0...v0.18.1) (2021-09-16) + +### Bug Fixes + +- ensure stable pages entry order across builds ([929bcf5](https://github.com/vuejs/vitepress/commit/929bcf50ee634d9fe73adbe2aae5f7038b048e5a)) + +# [0.18.0](https://github.com/vuejs/vitepress/compare/v0.17.3...v0.18.0) (2021-09-14) + +### Features + +- map mode + remove deprecated options ([b94b163](https://github.com/vuejs/vitepress/commit/b94b163a3a931fe03e69547391d6ac22eb41b789)) +- support ` + + +``` + +### `useRoute` + +Returns the current route object with the following type: + +```ts +interface Route { + path: string + data: PageData + component: Component | null +} +``` + +### `useRouter` + +Returns the VitePress router instance so you can programmatically navigate to another page. + +```ts +interface Router { + route: Route + go: (href?: string) => Promise +} +``` + +### `withBase` + +- **Type**: `(path: string) => string` + + Appends the configured [`base`](../config/basics#base) to a given URL path. Also see [Base URL](./assets#base-url). + +## Global Components + +VitePress comes with few built-in component that can be used globally. You may use these components in your markdown or your custom theme configuration. + +### `` + +The `` component displays the rendered markdown contents. Useful [when creating your own theme](./theming). + +```vue + +``` + +### `` + +The `` component renders its slot only at client side. + +Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser / DOM APIs in beforeMount or mounted hooks. + +If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them inside the `ClientOnly` component. + +```html + + + +``` diff --git a/docs/guide/assets.md b/docs/guide/assets.md index fbd25cc8..20969f9c 100644 --- a/docs/guide/assets.md +++ b/docs/guide/assets.md @@ -26,10 +26,30 @@ Note that you should reference files placed in `public` using root absolute path If your site is deployed to a non-root URL, you will need to set the `base` option in `.vitepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'` (it should always start and end with a slash). -With a base URL, to reference an image in `public`, you'd have to use URLs like `/bar/image.png`. But this is brittle if you ever decide to change the base. To help with that, VitePress provides a built-in helper `$withBase` (injected onto Vue's prototype) that generates the correct path: +All your static asset paths are automatically processed to adjust for different `base` config values. For example, if you have an absolute reference to an asset under `public` in your markdown: -```html -foo +```md +![An image](/image-inside-public.png) +``` + +You do **not** need to update it when you change the `base` config value in this case. + +However, if you are authoring a theme component that links to assets dynamically, e.g. an image whose `src` is based on a theme config value: + +```vue + ``` -Note you can use the above syntax not only in theme components, but in your Markdown files as well. +In this case it is recommended to wrap the path with the [`withBase` helper](./api#withbase) provided by VitePress: + +```vue + + + +``` diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index ab071a5e..bc6e747c 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -1,5 +1,7 @@ # Configuration +## Overview + Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let’s first create a `.vitepress` directory inside your docs directory. This is where all VitePress-specific files will be placed. Your project structure is probably like this: ```bash @@ -9,7 +11,7 @@ Without any configuration, the page is pretty minimal, and the user has no way t │ │ └─ config.js │ └─ index.md └─ package.json -```` +``` The essential file for configuring a VitePress site is `.vitepress/config.js`, which should export a JavaScript object: @@ -20,4 +22,58 @@ module.exports = { } ``` -Check out the [Config Reference](/config/basics) for a full list of options. +Check out the [Config Reference](../config/basics) for a full list of options. + +## Config Intellisense + +Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints: + +```js +/** + * @type {import('vitepress').UserConfig} + */ +const config = { + // ... +} + +export default config +``` + +Alternatively, you can use the `defineConfig` helper at which should provide intellisense without the need for jsdoc annotations: + +```js +import { defineConfig } from 'vitepress' + +export default defineConfig({ + // ... +}) +``` + +VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well. + +## Typed Theme Config + +By default, `defineConfig` helper leverages the theme config type from default theme: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + // Type is `DefaultTheme.Config` + } +}) +``` + +If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument: + +```ts +import { defineConfigWithTheme } from 'vitepress' +import { ThemeConfig } from 'your-theme' + +export default defineConfigWithTheme({ + themeConfig: { + // Type is `ThemeConfig` + } +}) +``` diff --git a/docs/guide/customization.md b/docs/guide/customization.md deleted file mode 100644 index 9caec3be..00000000 --- a/docs/guide/customization.md +++ /dev/null @@ -1,51 +0,0 @@ -# Customization - -You can develop your custom theme by adding the `.vitepress/theme/index.js` file. - -```bash -. -├─ docs -│ ├─ .vitepress -│ │ ├─ theme -│ │ │ └─ index.js -│ │ └─ config.js -│ └─ index.md -└─ package.json -```` - -In `.vitepress/theme/index.js`, you must export theme object and register your own theme layout. Let's say you have your own `Layout` component like this. - -```vue - - -``` - -Then include it in `.vitepress/theme/index.js`. - -```js -// .vitepress/theme/index.js -import Layout from './Layout.vue' - -export default { - Layout, - NotFound: () => 'custom 404', // <- this is a Vue 3 functional component - enhanceApp({ app, router, siteData }) { - // app is the Vue 3 app instance from `createApp()`. router is VitePress' - // custom router. `siteData`` is a `ref`` of current site-level metadata. - } -} -``` - -If you want to extend the default theme, you can import it from `vitepress/theme`. - -```js -// .vitepress/theme/index.js -import DefaultTheme from 'vitepress/theme' - -export default { - ...DefaultTheme -} -``` diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md index 65ac1734..9623e22f 100644 --- a/docs/guide/deploy.md +++ b/docs/guide/deploy.md @@ -1,3 +1,7 @@ +--- +sidebarDepth: 3 +--- + # Deploying The following guides are based on some shared assumptions: @@ -34,7 +38,7 @@ $ yarn docs:build $ yarn docs:serve ``` -The `serve` command will boot up local static web server that serves the files from `.vitepress/dist` at http://localhost:5000. It's an easy way to check if the production build looks OK in your local environment. +The `serve` command will boot up local static web server that serves the files from `.vitepress/dist` at `http://localhost:5000`. It's an easy way to check if the production build looks OK in your local environment. You may configure the port of the server py passing `--port` flag as an argument. @@ -46,7 +50,7 @@ You may configure the port of the server py passing `--port` flag as an argument } ``` -Now the `docs:serve` method will launch the server at http://localhost:8080. +Now the `docs:serve` method will launch the server at `http://localhost:8080`. ## GitHub Pages @@ -78,10 +82,10 @@ git add -A git commit -m 'deploy' # if you are deploying to https://.github.io -# git push -f git@github.com:/.github.io.git master +# git push -f git@github.com:/.github.io.git main # if you are deploying to https://.github.io/ -# git push -f git@github.com:/.git master:gh-pages +# git push -f git@github.com:/.git main:gh-pages cd - ``` @@ -102,7 +106,7 @@ You can also run the above script in your CI setup to enable automatic deploymen 3. Run `yarn` or `npm install` locally and commit the generated lockfile (that is `yarn.lock` or `package-lock.json`). -4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages/). +4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages). ```yaml language: node_js @@ -121,18 +125,18 @@ deploy: github_token: $GITHUB_TOKEN keep_history: true on: - branch: master + branch: main ``` ## GitLab Pages and GitLab CI 1. Set the correct `base` in `docs/.vitepress/config.js`. - If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `'/'`. + If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `'/'`. - If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `'//'`. + If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `'//'`. -2. Set `dest` in `.vitepress/config.js` to `public`. +2. Set `outDir` in `.vitepress/config.js` to `../public`. 3. Create a file called `.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: @@ -149,12 +153,12 @@ pages: paths: - public only: - - master + - main ``` ## Netlify -1. On [Netlify](https://netlify.com), setup up a new project from GitHub with the following settings: +1. On [Netlify](https://www.netlify.com/), setup up a new project from GitHub with the following settings: - **Build Command:** `vitepress build docs` or `yarn docs:build` or `npm run docs:build` - **Publish directory:** `docs/.vitepress/dist` @@ -167,26 +171,26 @@ pages: 2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content: - `firebase.json`: +`firebase.json`: - ```json - { - "hosting": { - "public": "./docs/.vitepress/dist", - "ignore": [] - } +```json +{ + "hosting": { + "public": "./docs/.vitepress/dist", + "ignore": [] } - ``` +} +``` - `.firebaserc`: +`.firebaserc`: - ```js - { - "projects": { - "default": "" - } - } - ``` +```js +{ + "projects": { + "default": "" + } +} +``` 3. After running `yarn docs:build` or `npm run docs:build`, deploy using the command `firebase deploy`. @@ -198,7 +202,7 @@ pages: 3. Deploy to surge by typing `surge docs/.vitepress/dist`. -You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vitepress/dist yourdomain.com`. +You can also deploy to a [custom domain](https://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vitepress/dist yourdomain.com`. ## Heroku @@ -243,7 +247,7 @@ $ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git ```bash # publish site -$ git push heroku master +$ git push heroku main # opens a browser to view the Dashboard version of Heroku CI $ heroku open @@ -251,9 +255,9 @@ $ heroku open ## Vercel -To deploy your VitePress app with a [Vercel for Git](https://vercel.com/docs/git), make sure it has been pushed to a Git repository. +To deploy your VitePress app with a [Vercel for Git](https://vercel.com/docs/concepts/git), make sure it has been pushed to a Git repository. -Go to https://vercel.com/import/git and import the project into Vercel using your Git of choice (GitHub, GitLab or BitBucket). Follow the wizard to select the project root with the project's `packaje.json` and override the build step using `yarn docs:build` or `npm run docs:build` and the output dir to be `./docs/.vitepress/dist` +Go to https://vercel.com/new and import the project into Vercel using your Git of choice (GitHub, GitLab or BitBucket). Follow the wizard to select the project root with the project's `package.json` and override the build step using `yarn docs:build` or `npm run docs:build` and the output dir to be `./docs/.vitepress/dist` ![Override Vercel Configuration](../images/vercel-configuration.png) diff --git a/docs/guide/differences-from-vuepress.md b/docs/guide/differences-from-vuepress.md index 94fdd4c0..b6c6eab5 100644 --- a/docs/guide/differences-from-vuepress.md +++ b/docs/guide/differences-from-vuepress.md @@ -1,3 +1,7 @@ +--- +sidebarDepth: 2 +--- + # Differences from VuePress VitePress and VuePress have different [design goals](../index.md). Both projects share similar config naming conventions. VitePress aims to have the bare minimum features needed for authoring docs. Other features are pushed to Themes. On the other hand, VuePress has more features out-of-the-box or enabled by its ecosystem of plugins. @@ -19,11 +23,11 @@ In case you decide to move your project to VitePress, this is a list of differen - [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/) + - Components in `.vitepress/components` [are not auto registered as global components](https://vuepress.vuejs.org) - Differences - [Public files](https://vuepress.vuejs.org/guide/assets.html#public-files) that are directly copied to dist root moved from `.vitepress/public/` is `public/` - - [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl` is `.vitepress/style.styl` - - [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements `.vitepress/enhanceApp.js` is `.vitepress/theme/index.js`. + - [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl` is not supported. See [Customizing CSS](./theming#customizing-css). + - [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements `.vitepress/enhanceApp.js` is now done in `.vitepress/theme/index.js`. See [Extending the Default Theme](./theming#extending-the-default-theme). ## Markdown @@ -31,7 +35,6 @@ In case you decide to move your project to VitePress, this is a list of differen - 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 @@ -67,7 +70,7 @@ In case you decide to move your project to VitePress, this is a list of differen - `algolia` is `search.algolia` - `searchPlaceholder` is `search.placeholder` -# Default Theme +## Default Theme - Missing - [`` and ``](https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks) diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md index 71f28bee..40fd2691 100644 --- a/docs/guide/frontmatter.md +++ b/docs/guide/frontmatter.md @@ -9,7 +9,7 @@ editLink: true --- ``` -Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the $frontmatter variable. +Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the special $frontmatter variable. Here’s an example of how you could use it in your Markdown file: diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index ae677f1c..eb24902c 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -74,7 +74,7 @@ This section will help you build a basic VitePress documentation site from groun - VitePress will start a hot-reloading development server at http://localhost:3000. + VitePress will start a hot-reloading development server at `http://localhost:3000`. By now, you should have a basic but functional VitePress documentation site. diff --git a/docs/guide/global-component.md b/docs/guide/global-component.md index 8ce0f7b5..ce843322 100644 --- a/docs/guide/global-component.md +++ b/docs/guide/global-component.md @@ -4,7 +4,7 @@ VitePress comes with few built-in component that can be used globally. You may u ## Content -The `Content` component displays the rendered markdown contents. Useful [when creating your own theme](http://localhost:3000/guide/customization.html). +The `Content` component displays the rendered markdown contents. Useful [when creating your own theme](./theming). ```vue