diff --git a/CHANGELOG.md b/CHANGELOG.md index d94ea05c..75b438e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,30 @@ +## [1.0.0-alpha.4](https://github.com/vuejs/vitepress/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2022-06-22) + +### Bug Fixes + +* **theme:** home image style is broken in big view port ([2bd960d](https://github.com/vuejs/vitepress/commit/2bd960d5f5a84df614035a4fb941331fdf9d84f2)) + +## [1.0.0-alpha.3](https://github.com/vuejs/vitepress/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2022-06-22) + +### Bug Fixes + +* **theme:** italic fonts are missing ([#759](https://github.com/vuejs/vitepress/issues/759)) ([#777](https://github.com/vuejs/vitepress/issues/777)) ([fa00c83](https://github.com/vuejs/vitepress/commit/fa00c83af4aa5fa619cf2e3da8d5aab77984ba7c)) +* **theme:** copy code in non-secure contexts ([#792](https://github.com/vuejs/vitepress/issues/792)) ([2935ed2](https://github.com/vuejs/vitepress/commit/2935ed22954010fa0d48d0625e5f2b0136991e0b)) +* **theme:** copy code button has wrong tag closing syntax ([#816](https://github.com/vuejs/vitepress/issues/816)) ([75ca9e4](https://github.com/vuejs/vitepress/commit/75ca9e4302c65e3bcc9518f7df928318380f6cf6)) +* **theme:** edit link gets hidden when a page don't have siblings ([#751](https://github.com/vuejs/vitepress/issues/751)) ([9bc4330](https://github.com/vuejs/vitepress/commit/9bc43306a1fe7bfd54b738642fd1737917a3af41)) +* **theme:** nav close icon not working correctly ([#744](https://github.com/vuejs/vitepress/issues/744)) ([75c9d80](https://github.com/vuejs/vitepress/commit/75c9d809d21c0484c0ae8ce691d598cf229c9525)) +* **theme:** sidebar is shown on home layout ([#825](https://github.com/vuejs/vitepress/issues/825)) ([#829](https://github.com/vuejs/vitepress/issues/829)) ([42cbd31](https://github.com/vuejs/vitepress/commit/42cbd31327b789ff9525919afb39b3092f1d445b)) +* **theme:** sidebar collapsed option not working on layout change ([#809](https://github.com/vuejs/vitepress/issues/809)) ([#811](https://github.com/vuejs/vitepress/issues/811)) ([7737699](https://github.com/vuejs/vitepress/commit/773769926b74cabfbb3577d6c6e654fe976c0b76)) +* **theme:** `DefaultTheme` type causes error in some cases ([#804](https://github.com/vuejs/vitepress/issues/804)) ([107724a](https://github.com/vuejs/vitepress/commit/107724ac6f24e5272964d3bdbff54169fa4d91ae)) + +### Features + +* **build:** allow setting `base` from command line ([2952638](https://github.com/vuejs/vitepress/commit/295263807df5a0cdff3b04d5131a3cebc76ec491)) +* **theme:** add active status to nav menu group ([#820](https://github.com/vuejs/vitepress/issues/820)) ([fdb5720](https://github.com/vuejs/vitepress/commit/fdb5720acda9f8f2dd1e4f33d0810a6e9ca9e7de)) +* **theme:** add global layout slots ([#760](https://github.com/vuejs/vitepress/issues/760)) ([#812](https://github.com/vuejs/vitepress/issues/812)) ([1f1e298](https://github.com/vuejs/vitepress/commit/1f1e298864f7b8af9672b55251958ba766678e0b)) +* **theme:** support themeable images for logo and hero ([#745](https://github.com/vuejs/vitepress/issues/745)) ([42813ce](https://github.com/vuejs/vitepress/commit/42813ce936d9fb141241969651cb0e3a02345442)) +* **theme:** add team page feature ([#828](https://github.com/vuejs/vitepress/issues/828)) ([7cfe0f0](https://github.com/vuejs/vitepress/commit/7cfe0f05ab013904c66c48d8529d2ba4747869cb)) + ## [1.0.0-alpha.2](https://github.com/vuejs/vitepress/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2022-06-14) ### Bug Fixes diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 23eeac47..30a0fcd5 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,5 +1,7 @@ import { defineConfig } from '../../src/node' +import { version } from '../../package.json' + export default defineConfig({ lang: 'en-US', title: 'VitePress', @@ -47,9 +49,18 @@ function nav() { { text: 'Guide', link: '/guide/what-is-vitepress', activeMatch: '/guide/' }, { text: 'Configs', link: '/config/introduction', activeMatch: '/config/' }, { - text: 'Changelog', - link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md' - } + text: version, + items: [ + { + text: 'Changelog', + link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md' + }, + { + text: 'Contributing', + link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md' + }, + ], + }, ] } @@ -87,7 +98,8 @@ function sidebarGuide() { { text: 'Edit Link', link: '/guide/theme-edit-link' }, { text: 'Last Updated', link: '/guide/theme-last-updated' }, { text: 'Layout', link: '/guide/theme-layout' }, - { text: 'Homepage', link: '/guide/theme-homepage' }, + { text: 'Home Page', link: '/guide/theme-home-page' }, + { text: 'Team Page', link: '/guide/theme-team-page' }, { text: 'Footer', link: '/guide/theme-footer' }, { text: 'Search', link: '/guide/theme-search' }, { text: 'Carbon Ads', link: '/guide/theme-carbon-ads' } diff --git a/docs/config/app-configs.md b/docs/config/app-configs.md index 96d3b118..54657e3f 100644 --- a/docs/config/app-configs.md +++ b/docs/config/app-configs.md @@ -12,6 +12,21 @@ export default { } ``` +## appearance + +- Type: `boolean` +- Default: `true` + +Whether to enable "Dark Mode" or not. If the option is set to `true`, it adds `.dark` class to the `` tag depending on the users preference. + +It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode. + +```ts +export default { + appearance: true +} +``` + ## base - Type: `string` @@ -27,57 +42,55 @@ export default { } ``` -## lang +## description - Type: `string` -- Default: `en-US` +- Default: `A VitePress site` -The lang attribute for the site. This will render as a `` tag in the page HTML. +Description for the site. This will render as a `` tag in the page HTML. ```ts export default { - lang: 'en-US' + description: 'A VitePress site' } ``` -## title +## ignoreDeadLinks -- Type: `string` -- Default: `VitePress` +- Type: `boolean` +- Default: `false` -Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined. +When set to `true`, VitePress will not fail builds due to dead links. ```ts export default { - title: 'VitePress' + ignoreDeadLinks: true } ``` -## titleTemplate - -- Type: `string | boolean` +## lang -The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`. +- Type: `string` +- Default: `en-US` -Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used. +The lang attribute for the site. This will render as a `` tag in the page HTML. ```ts export default { - title: 'VitePress', - titleTemplate: 'Vite & Vue powered static site generator' + lang: 'en-US' } ``` -## description +## lastUpdated -- Type: `string` -- Default: `A VitePress site` +- Type: `boolean` +- Default: `false` -Description for the site. This will render as a `` tag in the page HTML. +Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](theme-configs#lastupdatedtext) option. ```ts export default { - description: 'A VitePress site' + lastUpdated: true } ``` @@ -132,30 +145,31 @@ interface MarkdownOptions extends MarkdownIt.Options { } ``` -## appearance - -- Type: `boolean` -- Default: `true` +## title -Whether to enable "Dark Mode" or not. If the option is set to `true`, it adds `.dark` class to the `` tag depending on the users preference. +- Type: `string` +- Default: `VitePress` -It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode. +Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined. ```ts export default { - appearance: true + title: 'VitePress' } ``` -## lastUpdated +## titleTemplate -- Type: `boolean` -- Default: `false` +- Type: `string | boolean` -Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](theme-configs#lastupdatedtext) option. +The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`. + +Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used. ```ts export default { - lastUpdated: true + title: 'VitePress', + titleTemplate: 'Vite & Vue powered static site generator' } ``` + diff --git a/docs/config/theme-configs.md b/docs/config/theme-configs.md index 37564b78..b1b63151 100644 --- a/docs/config/theme-configs.md +++ b/docs/config/theme-configs.md @@ -83,6 +83,7 @@ type NavItemWithLink = { interface NavItemWithChildren { text?: string items: NavItemWithLink[] + activeMatch?: string } ``` @@ -129,6 +130,22 @@ interface SidebarItem { } ``` + +## outlineTitle + +- Type: `string` +- Default: `On this page` + +Can be used to customize the title of the right sidebar (on the top of outline links). This is useful when writing documentation in another language. + +```js +export default { + themeConfig: { + outlineTitle: 'In hac pagina' + } +} +``` + ## socialLinks - Type: `SocialLink` @@ -246,9 +263,33 @@ export default { ```ts export interface CarbonAds { - code: string, + code: string placement: string } ``` Learn more in [Theme: Carbon Ads](../guide/theme-carbon-ads) + +## docFooter + +- Type: `DocFooter` + +Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. + +```js +export default { + themeConfig: { + docFooter: { + prev: 'Pagina prior', + next: 'Proxima pagina' + } + } +} +``` + +```ts +export interface DocFooter { + prev?: string + next?: string +} +``` diff --git a/docs/guide/deploying.md b/docs/guide/deploying.md index 3c7a2867..2cb1c493 100644 --- a/docs/guide/deploying.md +++ b/docs/guide/deploying.md @@ -2,287 +2,184 @@ The following guides are based on some shared assumptions: -- You are placing your docs inside the `docs` directory of your project; -- You are using the default build output location (`.vitepress/dist`); -- VitePress is installed as a local dependency in your project, and you have setup the following npm scripts: - -```json -{ - "scripts": { - "docs:build": "vitepress build docs", - "docs:serve": "vitepress serve docs" +- You are placing your docs inside the `docs` directory of your project. +- You are using the default build output location (`.vitepress/dist`). +- VitePress is installed as a local dependency in your project, and you have set up the following scripts in your `package.json`: + + ```json + { + "scripts": { + "docs:build": "vitepress build docs", + "docs:serve": "vitepress serve docs" + } } -} -``` + ``` -## Build and test locally - -You may run `yarn docs:build` command to build the docs. - -```bash -$ yarn docs:build -``` - -By default, the build output will be placed at `.vitepress/dist`. You may deploy this `dist` folder to any of your preferred platforms. - -Once you've built the docs, you may test them locally by running `yarn docs:serve` command. - -```bash -$ 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. +::: tip -You may configure the port of the server by passing `--port` flag as an argument. +If your site is to be served at a subdirectory (`https://example.com/subdir/`), then you have to set `'/subdir/'` as the [`base`](../config/app-configs#base) in your `docs/.vitepress/config.js`. -```json -{ - "scripts": { - "docs:serve": "vitepress serve docs --port 8080" - } -} -``` +::: -Now the `docs:serve` method will launch the server at `http://localhost:8080`. +## Build and Test Locally -## GitHub Pages +- You may run this command to build the docs: -1. Set the correct `base` in `docs/.vitepress/config.js`. + ```sh + $ yarn docs:build + ``` - If you are deploying to `https://.github.io/`, you can omit `base` as it defaults to `'/'`. +- Once you've built the docs, you can test them locally by running: - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. + ```sh + $ yarn docs:serve + ``` -2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy: + The `serve` command will boot up a local static web server that will serve the files from `.vitepress/dist` at `http://localhost:5000`. It's an easy way to check if the production build looks fine in your local environment. -```bash{13,20,23} -#!/usr/bin/env sh +- You can configure the port of the server by passing `--port` as an argument. -# abort on errors -set -e + ```json + { + "scripts": { + "docs:serve": "vitepress serve docs --port 8080" + } + } + ``` -# build -npm run docs:build + Now the `docs:serve` method will launch the server at `http://localhost:8080`. -# navigate into the build output directory -cd docs/.vitepress/dist +## Netlify, Vercel, AWS Amplify, Cloudflare Pages, Render -# if you are deploying to a custom domain -# echo 'www.example.com' > CNAME +Set up a new project and change these settings using your dashboard: -git init -git add -A -git commit -m 'deploy' +- **Build Command:** `yarn docs:build` +- **Output Directory:** `docs/.vitepress/dist` -# if you are deploying to https://.github.io -# git push -f git@github.com:/.github.io.git main +::: warning +Don't enable options like _Auto Minify_ for HTML code. It will remove comments from output which have meaning to Vue. You may see hydration mismatch errors if they get removed. +::: -# if you are deploying to https://.github.io/ -# git push -f git@github.com:/.git main:gh-pages +## GitHub Pages -cd - -``` +### Using GitHub Actions -::: tip -You can also run the above script in your CI setup to enable automatic deployment on each push. -::: +1. Create a file named `deploy.yml` inside `.github/workflow` directory of your project with the following content: -## GitHub Pages and Travis CI + ```yaml + name: Deploy -1. Set the correct `base` in `docs/.vitepress/config.js`. + on: + push: + branches: + - main - If you are deploying to `https://.github.io/`, you can omit `base` as it defaults to `'/'`. + jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v3 + with: + node-version: 16 + cache: yarn + - run: yarn install --frozen-lockfile - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. + - name: Build + run: yarn docs:build -2. Create a file named `.travis.yml` in the root of your project. + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/.vitepress/dist + ``` -3. Run `yarn` or `npm install` locally and commit the generated lockfile (that is `yarn.lock` or `package-lock.json`). +2. Now commit your code and push it to the `main` branch. -4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages). +3. Wait for actions to complete. Then select `gh-pages` branch as GitHub Pages source in your repository settings. Now your docs will automatically deploy each time you push. -```yaml -language: node_js -node_js: - - lts/* -install: - - yarn install # npm ci -script: - - yarn docs:build # npm run docs:build -deploy: - provider: pages - skip_cleanup: true - local_dir: docs/.vitepress/dist - # A token generated on GitHub allowing Travis to push code on you repository. - # Set in the Travis settings page of your repository, as a secure variable. - github_token: $GITHUB_TOKEN - keep_history: true - on: - branch: main -``` +## GitLab Pages -## GitLab Pages and GitLab CI +### Using 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//`, for example your repository is at `https://gitlab.com//`, then set `base` to `'//'`. + If you are deploying to `https://.gitlab.io//` (your repository is at `https://gitlab.com//`), then set `base` to `'//'`. -2. Set `outDir` in `.vitepress/config.js` to `../public`. +2. Set `outDir` in `docs/.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: -```yaml -image: node:16 -pages: - cache: - paths: - - node_modules/ - script: - - yarn install # npm install - - yarn docs:build # npm run docs:build - artifacts: - paths: - - public - only: - - main -``` - -## Netlify - -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` - -2. Hit the deploy button. - -## Google Firebase - -1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed. - -2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content: - -`firebase.json`: - -```json -{ - "hosting": { - "public": "./docs/.vitepress/dist", - "ignore": [] - } -} -``` - -`.firebaserc`: - -```js -{ - "projects": { - "default": "" - } -} -``` - -3. After running `yarn docs:build` or `npm run docs:build`, deploy using the command `firebase deploy`. + ```yaml + image: node:16 + pages: + cache: + paths: + - node_modules/ + script: + - yarn install + - yarn docs:build + artifacts: + paths: + - public + only: + - main + ``` + +## Firebase + +1. Create `firebase.json` and `.firebaserc` at the root of your project: + + `firebase.json`: + + ```json + { + "hosting": { + "public": "docs/.vitepress/dist", + "ignore": [] + } + } + ``` + + `.firebaserc`: + + ```json + { + "projects": { + "default": "" + } + } + ``` + +2. After running `yarn docs:build`, run this command to deploy: + + ```sh + firebase deploy + ``` ## Surge -1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already. +1. After running `yarn docs:build`, run this command to deploy: -2. Run `yarn docs:build` or `npm run docs:build`. - -3. Deploy to surge by typing `surge docs/.vitepress/dist`. - -You can also deploy to a [custom domain](https://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vitepress/dist yourdomain.com`. + ```sh + npx surge docs/.vitepress/dist + ``` ## Heroku -1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). - -2. Create a Heroku account by [signing up](https://signup.heroku.com). - -3. Run `heroku login` and fill in your Heroku credentials: - -```bash -$ heroku login -``` - -4. Create a file called `static.json` in the root of your project with the below content: - -`static.json`: - -```json -{ - "root": "./docs/.vitepress/dist" -} -``` - -This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static). - -5. Set up your Heroku git remote: - -```bash -# version change -$ git init -$ git add . -$ git commit -m "My site ready for deployment." - -# creates a new app with a specified name -$ heroku apps:create example - -# set buildpack for static sites -$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git -``` - -6. Deploy your site: - -```bash -# publish site -$ git push heroku main +1. Folow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). -# opens a browser to view the Dashboard version of Heroku CI -$ heroku open -``` +2. Create a file called `static.json` in the root of your project with the below content: -## Vercel - -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/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) - -After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly "main") will result in a Production Deployment. - -Once deployed, you will get a URL to see your app live, such as the following: https://vitepress.vercel.app + ```json + { + "root": "docs/.vitepress/dist" + } + ``` ## Layer0 -See [Creating and Deploying a VitePress App with Layer0](https://docs.layer0.co/guides/vitepress). - -## Cloudflare Pages - -1. Go to [Cloudflare dashboard](https://dash.cloudflare.com/) > Account Home > Pages and selecting **Create a project**. -2. You will see three options, just select first **Connect to a git provider**. -3. Click Connect GitHub or Connect GitLab. Then select the repo you want to deploy. -4. Set up build docs command, like `npm run build` or `npm run docs:build`. -5. Now deploy, you will get a domain like `my-project.pages.dev`. - -::: warning Do not Auto Minify HTML -If you want or are using Cloudflare's Auto minify feature, you should not check the html box. - -With Auto Minify, Cloudflare will automatically remove the comments in the html file, however, html comments for Vue has meanings. For example, it works as a placeholder for `v-if`. - -If it gets removed, then you will probably see a hydration mismatch error. -::: - -## Render -1. On [Render dashboard](https://dashboard.render.com), setup a new [static site](https://render.com/docs/static-sites) 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 - -2. Hit the **Create Static Site** button +Refer [Creating and Deploying a VitePress App with Layer0](https://docs.layer0.co/guides/vitepress). diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index b751b33c..6bf5b20c 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -28,6 +28,39 @@ Add VitePress and Vue as dev dependencies for the project. $ yarn add --dev vitepress vue ``` +::: details Getting missing peer deps warnings? +`@docsearch/js` has certain issues with its peer dependencies. If you see some commands failing due to them, you can try this workaround for now: + +On Yarn v2/v3, add this inside your rc file (`.yarnrc.yml` by default): + +```yaml +packageExtensions: + '@docsearch/react@*': + peerDependenciesMeta: + '@types/react': + optional: true + 'react': + optional: true + 'react-dom': + optional: true +``` + +On PNPM, add this in your `package.json`: + +```json +"pnpm": { + "peerDependencyRules": { + "ignoreMissing": [ + "@types/react", + "react", + "react-dom" + ] + } +} +``` + +::: + Create your first document. ```bash diff --git a/docs/guide/migration-from-vitepress-0.md b/docs/guide/migration-from-vitepress-0.md index 80c5803f..f7041dc8 100644 --- a/docs/guide/migration-from-vitepress-0.md +++ b/docs/guide/migration-from-vitepress-0.md @@ -19,5 +19,5 @@ If you're coming from VitePress 0.x version, there're several breaking changes d ## Frontmatter Config -- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Homepage guide](./theme-homepage) for details. +- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](./theme-home-page) for details. - `footer` option is moved to [`themeConfig.footer`](../config/theme-configs#footer). diff --git a/docs/guide/theme-homepage.md b/docs/guide/theme-home-page.md similarity index 99% rename from docs/guide/theme-homepage.md rename to docs/guide/theme-home-page.md index 4de188ad..80a88008 100644 --- a/docs/guide/theme-homepage.md +++ b/docs/guide/theme-home-page.md @@ -1,4 +1,4 @@ -# Homepage +# Home Page VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter). diff --git a/docs/guide/theme-introduction.md b/docs/guide/theme-introduction.md index f886cf8b..09d56d66 100644 --- a/docs/guide/theme-introduction.md +++ b/docs/guide/theme-introduction.md @@ -8,16 +8,17 @@ VitePress comes with its default theme providing many features out of the box. L - [Edit Link](./theme-edit-link) - [Last Updated](./theme-last-updated) - [Layout](./theme-layout) -- [Homepage](./theme-homepage) +- [Home Page](./theme-home-page) +- [Team Page](./theme-team-page) - [Footer](./theme-footer) - [Search](./theme-search) - [Carbon Ads](./theme-carbon-ads) -If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements. +If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements. In the following sections, we'll go through each way of customizing the VitePress theme. ## Using a Custom Theme -You can enable a custom theme by adding the `.vitepress/theme/index.js` file (the "theme entry file"). +You can enable a custom theme by adding the `.vitepress/theme/index.js` or `.vitepress/theme/index.ts` file (the "theme entry file"). ``` . @@ -53,6 +54,7 @@ The theme entry file should export the theme as its default export: import Layout from './Layout.vue' export default { + // root component to wrap each page Layout, // this is a Vue 3 functional component diff --git a/docs/guide/theme-layout.md b/docs/guide/theme-layout.md index 8ea0c5f6..33033102 100644 --- a/docs/guide/theme-layout.md +++ b/docs/guide/theme-layout.md @@ -35,4 +35,4 @@ Note that even in this layout, sidebar will still show up if the page has a matc ## Home Layout -Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-homepage) for more details. +Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-home-page) for more details. diff --git a/docs/guide/theme-nav.md b/docs/guide/theme-nav.md index 92413974..81575e9b 100644 --- a/docs/guide/theme-nav.md +++ b/docs/guide/theme-nav.md @@ -51,7 +51,7 @@ export default { } ``` -The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and alsways start with `/`. +The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`. Nav links can also be dropdown menus. To do this, set `items` key on link option. diff --git a/docs/guide/theme-prev-next-link.md b/docs/guide/theme-prev-next-link.md index c248d1f3..e52f9057 100644 --- a/docs/guide/theme-prev-next-link.md +++ b/docs/guide/theme-prev-next-link.md @@ -1,3 +1,29 @@ # Prev Next Link -Documentation coming soon... +You can customize the text of previous and next links. This is helpful if you want to show different text on previous/next links than what you have on your sidebar. + +## prev + +- Type: `string` + +- Details: + + Specify the text to show on the link to the previous page. + + If you don't set this in frontmatter, the text will be inferred from the sidebar config. + +- Example: + +```yaml +--- +prev: 'Get Started | Markdown' +--- +``` + +## next + +- Type: `string` + +- Details: + + Same as `prev` but for the next page. diff --git a/docs/guide/theme-sidebar.md b/docs/guide/theme-sidebar.md index 1433c05d..74cbb47b 100644 --- a/docs/guide/theme-sidebar.md +++ b/docs/guide/theme-sidebar.md @@ -110,7 +110,7 @@ export default { { text: 'Config', items: [ - // This shows `/guide/index.md` page. + // This shows `/config/index.md` page. { text: 'Index', link: '/config/' }, // /config/index.md { text: 'Three', link: '/config/three' }, // /config/three.md { text: 'Four', link: '/config/four' } // /config/four.md diff --git a/docs/guide/theme-team-page.md b/docs/guide/theme-team-page.md new file mode 100644 index 00000000..f19b52d5 --- /dev/null +++ b/docs/guide/theme-team-page.md @@ -0,0 +1,255 @@ + + +# Team Page + +If you would like to introduce your team, you may use Team components to construct the Team Page. There're 2 ways of using these components. One is to embbed it in doc page, and another is to create a full Team Page. + +## Show team members in a page + +You may use `` component exposed from `vitepress/theme` to display a list of team members on any page. + +```html + + +# Our Team + +Say hello to our awesome team. + + +``` + +The above will display a team member in card looking element. It should display something similar to below. + + + +`` component comes in 2 different sizes, `small` and `medium`. While it boiles down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [``](#vpteammembers). + +Embbeding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a refference to documenation context. + +If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page). + +## Create a full Team Page + +Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./theme-home-page). + +To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components. + +```html +--- +layout: page +--- + + + + + + + + + +``` + +When creating a full team page, remember to wrap all components with `` component. This component will ensure all nested team related components get the proper layout structure like spacings. + +`` component adds the page title section. The title being `

` heading. Use `#title` and `#lead` slot to document about your team. + +`` works as same as when used in a doc page. It will display list of members. + +### Add sections to divide team members + +You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can devide these members into sections to better explain the roles of each group. + +To do so, add `` component to the `team.md` file we created previously. + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +The `` component can have `#title` and `#lead` slot similar to `VPTeamPageTitle` component, and also `#members` slot for displaying team members. + +Remember to put in `` component within `#members` slot. + +## `` + +The `` component displays a given list of members. + +```html + +``` + +```ts +interface Props { + // Size of each members. Defaults to `medium`. + size?: 'small' | 'meidum' + + // List of members to display. + members: TeamMember[] +} + +interface TeamMember { + // Avatar image for the member. + avatar: string + + // Name of the member. + name: string + + // Title to be shown below member's name. + // e.g. Developer, Software Engineer, etc. + title?: string + + // Organization that the member belongs. + org?: string + + // URL for the organization. + orgLink?: string + + // Description for the member. + desc?: string + + // Social links. e.g. GitHub, Twitter, etc. You may pass in + // the Social Links object here. + // See: https://vitepress.vuejs.org/config/theme-configs.html#sociallinks + links?: SocialLink[] + + // URL for the sponsor page for the member. + sponsor?: string +} +``` + +## `` + +The root component when creating a full team page. It only accepts a single slot. It's will style all passed in team related components. + +## `` + +Adds "title" section of the page. Best use at the very beginning under ``. It accepts `#title` and `#lead` slot. + +```html + + + + + + +``` + +## `` + +Creates a "section" with in team page. It accepts `#title`, `#lead`, and `#members` slot. You may add as many sections as you like inside ``. + +```html + + ... + + + + + + +``` diff --git a/docs/images/line-numbers-desktop.png b/docs/images/line-numbers-desktop.png deleted file mode 100644 index e16e6707..00000000 Binary files a/docs/images/line-numbers-desktop.png and /dev/null differ diff --git a/docs/images/line-numbers-mobile.gif b/docs/images/line-numbers-mobile.gif deleted file mode 100644 index 87af6cf0..00000000 Binary files a/docs/images/line-numbers-mobile.gif and /dev/null differ diff --git a/docs/images/vercel-configuration.png b/docs/images/vercel-configuration.png deleted file mode 100644 index 51874e15..00000000 Binary files a/docs/images/vercel-configuration.png and /dev/null differ diff --git a/package.json b/package.json index 6aa478d5..3c499689 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "vitepress", - "version": "1.0.0-alpha.2", + "version": "1.0.0-alpha.4", "description": "Vite & Vue powered static site generator", "type": "module", "packageManager": "pnpm@7.1.7", diff --git a/scripts/copyShared.js b/scripts/copyShared.js index ed5f55d9..465f2853 100644 --- a/scripts/copyShared.js +++ b/scripts/copyShared.js @@ -1,7 +1,9 @@ import { copy } from 'fs-extra' import fg from 'fast-glob' -fg.sync('src/shared/**/*.ts').map(async (file) => { - await copy(file, file.replace(/^src\/shared\//, 'src/node/')) - await copy(file, file.replace(/^src\/shared\//, 'src/client/')) +fg.sync('src/shared/**/*.ts').forEach(async (file) => { + await Promise.all([ + copy(file, file.replace(/^src\/shared\//, 'src/node/')), + copy(file, file.replace(/^src\/shared\//, 'src/client/')) + ]) }) diff --git a/src/client/app/data.ts b/src/client/app/data.ts index 3e3fa7a2..cea5a8a8 100644 --- a/src/client/app/data.ts +++ b/src/client/app/data.ts @@ -31,8 +31,10 @@ export const siteDataRef: Ref = shallowRef( // hmr if (import.meta.hot) { - import.meta.hot!.accept('/@siteData', (m) => { - siteDataRef.value = m.default + import.meta.hot.accept('/@siteData', (m) => { + if (m) { + siteDataRef.value = m.default + } }) } diff --git a/src/client/theme-default/Layout.vue b/src/client/theme-default/Layout.vue index d8352a8b..5087ee46 100644 --- a/src/client/theme-default/Layout.vue +++ b/src/client/theme-default/Layout.vue @@ -1,5 +1,6 @@