diff --git a/docs/guide/deploying.md b/docs/guide/deploying.md index 90b62dba..6da04b07 100644 --- a/docs/guide/deploying.md +++ b/docs/guide/deploying.md @@ -2,308 +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. +::: tip -Once you've built the docs, you may test them locally by running `yarn docs:serve` command. +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`. -```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. +## Build and Test Locally -You may configure the port of the server by passing `--port` flag as an argument. +- You may run this command to build the docs: -```json -{ - "scripts": { - "docs:serve": "vitepress serve docs --port 8080" - } -} -``` + ```sh + $ yarn docs:build + ``` -Now the `docs:serve` method will launch the server at `http://localhost:8080`. +- Once you've built the docs, you can test them locally by running: -## GitHub Pages + ```sh + $ yarn docs:serve + ``` -1. Set the correct `base` in `docs/.vitepress/config.js`. + 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. - If you are deploying to `https://.github.io/`, you can omit `base` as it defaults to `'/'`. +- You can configure the port of the server by passing `--port` as an argument. - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. + ```json + { + "scripts": { + "docs:serve": "vitepress serve docs --port 8080" + } + } + ``` -2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy: + Now the `docs:serve` method will launch the server at `http://localhost:8080`. -```bash{13,20,23} -#!/usr/bin/env sh +## Netlify, Vercel, AWS Amplify, Cloudflare Pages -# abort on errors -set -e +Set up a new project and change these settings using your dashboard: -# build -npm run docs:build +- **Build Command:** `yarn docs:build` +- **Output Directory:** `docs/.vitepress/dist` -# navigate into the build output directory -cd docs/.vitepress/dist +::: 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 a custom domain -# echo 'www.example.com' > CNAME +## GitHub Pages -git init -git add -A -git commit -m 'deploy' +### Using GitHub Actions -# if you are deploying to https://.github.io -# git push -f git@github.com:/.github.io.git main +1. Create a file named `deploy.yml` inside `.github/workflow` directory of your project with the following content: -# if you are deploying to https://.github.io/ -# git push -f git@github.com:/.git main:gh-pages + ```yaml + name: Deploy -cd - -``` + on: + push: + branches: + - main -::: tip -You can also run the above script in your CI setup to enable automatic deployment on each push. -::: - -## GitHub Pages and Travis CI + 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 -1. Set the correct `base` in `docs/.vitepress/config.js`. + - name: Build + run: yarn docs:build - If you are deploying to `https://.github.io/`, you can omit `base` as it defaults to `'/'`. + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/.vitepress/dist + ``` - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. +2. Now commit your code and push it to the `main` branch. -2. Create a file named `.travis.yml` in the root of your project. +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. -3. Run `yarn` or `npm install` locally and commit the generated lockfile (that is `yarn.lock` or `package-lock.json`). +## GitLab 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 -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 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. - -2. Run `yarn docs:build` or `npm run docs:build`. +1. After running `yarn docs:build`, run this command to deploy: -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: +1. Folow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). -```bash -# publish site -$ git push heroku main +2. Create a file called `static.json` in the root of your project with the below content: -# 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. -::: - - -## AWS Amplify - -Follow the getting started guide for [Git-based Deployments](https://docs.amplify.aws/guides/hosting/git-based-deployments/q/platform/js/#4-deploy-your-app-to-aws-amplify) to deploy your VitePress app with Amplify Hosting. - -During the deployment process, **edit** the default build settings: - -- **`build > commands`**: `yarn run docs:build` -- **`baseDirectory`**: `docs/.vitepress/dist` - -```yaml{9,11} -version: 1 -frontend: - phases: - preBuild: - commands: - - yarn install - build: - commands: - - yarn run docs:build - artifacts: - baseDirectory: docs/.vitepress/dist - files: - - '**/*' - cache: - paths: - - node_modules/**/* -``` \ No newline at end of file +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