diff --git a/docs/config/theme-configs.md b/docs/config/theme-configs.md index eb40afdf..b1b63151 100644 --- a/docs/config/theme-configs.md +++ b/docs/config/theme-configs.md @@ -130,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` diff --git a/docs/guide/deploying.md b/docs/guide/deploying.md index efb2ae6b..ff2fa921 100644 --- a/docs/guide/deploying.md +++ b/docs/guide/deploying.md @@ -2,279 +2,194 @@ 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:4173`. 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:4173`. 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 -``` + ```yaml + image: node:16 + pages: + cache: + paths: + - node_modules/ + script: + - yarn install + - yarn docs:build + artifacts: + paths: + - public + only: + - main + ``` -## Netlify +## Azure Static Web Apps -1. On [Netlify](https://www.netlify.com/), setup up a new project from GitHub with the following settings: +1. Follow the [official documentation](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration). -- **Build Command:** `vitepress build docs` or `yarn docs:build` or `npm run docs:build` -- **Publish directory:** `docs/.vitepress/dist` +2. Set these values in your configuration file (and remove the ones you don't require, like `api_location`): -2. Hit the deploy button. + - **`app_location`**: `/` + - **`output_location`**: `docs/.vitepress/dist` + - **`app_build_command`**: `yarn docs:build` -## Google Firebase +## Firebase -1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed. +1. Create `firebase.json` and `.firebaserc` at the root of your project: -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`: + ```json + { + "projects": { + "default": "" + } + } + ``` -```js -{ - "projects": { - "default": "" - } -} -``` +2. After running `yarn docs:build`, run this command to deploy: -3. After running `yarn docs:build` or `npm run docs:build`, deploy using the command `firebase deploy`. + ```sh + firebase deploy + ``` ## Surge -1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already. - -2. Run `yarn docs:build` or `npm run docs:build`. - -3. Deploy to surge by typing `surge docs/.vitepress/dist`. +1. After running `yarn docs:build`, run this command to deploy: -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: +1. Follow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). -```bash -$ heroku login -``` +2. Create a file called `static.json` in the root of your project with the below content: -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 - -# opens a browser to view the Dashboard version of Heroku CI -$ heroku open -``` - -## 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. -::: +Refer [Creating and Deploying a VitePress App with Layer0](https://docs.layer0.co/guides/vitepress). 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/src/client/theme-default/components/VPNavBarHamburger.vue b/src/client/theme-default/components/VPNavBarHamburger.vue index e243552f..89a27247 100644 --- a/src/client/theme-default/components/VPNavBarHamburger.vue +++ b/src/client/theme-default/components/VPNavBarHamburger.vue @@ -49,7 +49,7 @@ defineEmits<{ } .VPNavBarHamburger:hover .top { top: 0; left: 0; transform: translateX(4px); } -.VPNavBarHamburger:hover .middle { top: 6; left: 0; transform: translateX(0); } +.VPNavBarHamburger:hover .middle { top: 6px; left: 0; transform: translateX(0); } .VPNavBarHamburger:hover .bottom { top: 12px; left: 0; transform: translateX(8px); } .VPNavBarHamburger.active .top { top: 6px; transform: translateX(0) rotate(225deg); } diff --git a/src/node/config.ts b/src/node/config.ts index f5999ab0..096440e5 100644 --- a/src/node/config.ts +++ b/src/node/config.ts @@ -196,14 +196,9 @@ async function resolveUserConfig( mode: string ): Promise<[UserConfig, string | undefined]> { // load user config - let configPath - for (const ext of supportedConfigExtensions) { - const p = resolve(root, `config.${ext}`) - if (await fs.pathExists(p)) { - configPath = p - break - } - } + const configPath = supportedConfigExtensions + .map((ext) => resolve(root, `config.${ext}`)) + .find(fs.pathExistsSync) const userConfig: RawConfigExports = configPath ? ( diff --git a/src/node/markdown/plugins/image.ts b/src/node/markdown/plugins/image.ts index 59dadcc1..c61eadf8 100644 --- a/src/node/markdown/plugins/image.ts +++ b/src/node/markdown/plugins/image.ts @@ -4,21 +4,13 @@ import MarkdownIt from 'markdown-it' import { EXTERNAL_URL_RE } from '../../shared' export const imagePlugin = (md: MarkdownIt) => { + const imageRule = md.renderer.rules.image! md.renderer.rules.image = (tokens, idx, options, env, self) => { const token = tokens[idx] const url = token.attrGet('src') if (url && !EXTERNAL_URL_RE.test(url) && !/^\.?\//.test(url)) { token.attrSet('src', './' + url) } - - if (token.attrIndex('alt') && token.children != null) { - token.attrs![token.attrIndex('alt')][1] = self.renderInlineAsText( - token.children, - options, - env - ) - } - - return self.renderToken(tokens, idx, options) + return imageRule(tokens, idx, options, env, self) } }