diff --git a/docs/guide/deploying.md b/docs/guide/deploying.md index 91483134..50fb8e81 100644 --- a/docs/guide/deploying.md +++ b/docs/guide/deploying.md @@ -2,321 +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: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 -``` + ```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: -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. +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 -``` +1. Follow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). -4. Create a file called `static.json` in the root of your project with the below content: +2. 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. -::: - -## Azure Static Web App using GitHub Actions - -1. Go to https://portal.azure.com -2. Create [Azure Static Web App](https://azure.microsoft.com/en-us/services/app-service/static/) free tier. -3. Don't connect GitHub to Azure Static Web App. -4. When the resource is deployed open it click on 'Manage deployment token' and copy the token. -5. Open your GitHub repository and go to 'Settings' -> 'Secrets' -> 'Actions' -> 'New repository secret' -6. Enter name 'AZURE_STATIC_WEB_APP_TOKEN' -7. Paste deployment token from Azure Static Web App -8. In GiHub repository create '.github/workflows/cd.yml' and fill it like this: - -``` yaml -name: CI/CD - -on: - push: - branches: - - main - -jobs: - build_and_deploy_job: - runs-on: ubuntu-latest - name: Build and Deploy Job - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: "16.13.2" - - run: | - npm ci - npm run build - - name: Deploy - uses: Azure/static-web-apps-deploy@v1 - with: - skip_app_build: true - app_location: "/dist" - action: "upload" - azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APP_TOKEN }} -``` - -Now with every push to main it will deploy vite press website in Azure Static Web App. +Refer [Creating and Deploying a VitePress App with Layer0](https://docs.layer0.co/guides/vitepress).