From 30b323d6e7c63a9599a09c9046629ff40721a4d1 Mon Sep 17 00:00:00 2001 From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> Date: Wed, 19 Jul 2023 14:26:15 +0530 Subject: [PATCH] docs: rewrite github/gitlab deploying guide (closes #2205) --- docs/guide/deploy.md | 119 ++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 58 deletions(-) diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md index 6ab0773c..7ebbc314 100644 --- a/docs/guide/deploy.md +++ b/docs/guide/deploy.md @@ -119,66 +119,87 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f ### GitHub Pages -1. In your theme config file, `docs/.vitepress/config.js`, set the `base` property to the name of your GitHub repository. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash. - -2. Create a file named `deploy.yml` inside `.github/workflows` directory of your project with the following content: +1. Create a file named `deploy.yml` inside `.github/workflows` directory of your project with some content like this: ```yaml - name: Deploy + # Sample workflow for building and deploying a VitePress site to GitHub Pages + # + name: Deploy VitePress site to Pages + on: - workflow_dispatch: {} + # Runs on pushes targeting the `main` branch. Change this to `master` if you're + # using the `master` branch as the default branch. push: - branches: - - main + branches: [main] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + + # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages + permissions: + contents: read + pages: write + id-token: write + + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + concurrency: + group: pages + cancel-in-progress: false + jobs: - deploy: + # Build job + build: runs-on: ubuntu-latest - permissions: - contents: read - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} steps: - - uses: actions/checkout@v3 + - name: Checkout + uses: actions/checkout@v3 with: - fetch-depth: 0 - - uses: actions/setup-node@v3 + fetch-depth: 0 # Not needed if lastUpdated is not enabled + # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm + - name: Setup Node + uses: actions/setup-node@v3 with: - node-version: 16 - cache: npm - - run: npm ci - - name: Build - run: npm run docs:build - - uses: actions/configure-pages@v2 - - uses: actions/upload-pages-artifact@v1 + node-version: 18 + cache: npm # or pnpm / yarn + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Install dependencies + run: npm ci # or pnpm install / yarn install + - name: Build with VitePress + run: npm run docs:build # or pnpm docs:build / yarn docs:build + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 with: path: docs/.vitepress/dist - - name: Deploy + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v1 + uses: actions/deploy-pages@v2 ``` - ::: tip - Please replace the corresponding branch name. For example, if the branch you want to build is `master`, then you should replace `main` with `master` in the above file. + ::: warning + Make sure the `base` option in your VitePress is properly configured. See [Setting a Public Base Path](#setting-a-public-base-path) for more details. ::: -3. In your repository's Settings under Pages menu item, select `GitHub Actions` in Build and deployment's Source. - -4. Now commit your code and push it to the `main` branch. +2. In your repository's settings under "Pages" menu item, select "GitHub Actions" in "Build and deployment > Source". -5. Wait for actions to complete. - -6. In your repository's Settings under Pages menu item, click `Visit site`, then you can see your site. Your docs will automatically deploy each time you push. +3. Push your changes to the `main` branch and wait for the GitHub Actions workflow to complete. You should see your site deployed to `https://.github.io/[repository]/` or `https:///` depending on your settings. Your site will automatically be deployed on every push to the `main` branch. ### GitLab Pages -1. Set `outDir` in `docs/.vitepress/config.js` to `../public`. - -2. Still in your config file, `docs/.vitepress/config.js`, set the `base` property to the name of your GitLab repository. If you plan to deploy your site to `https://foo.gitlab.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash. +1. Set `outDir` in VitePress config to `../public`. Configure `base` option to `'//'` if you want to deploy to `https://.gitlab.io//`. -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: +2. Create a file named `.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 @@ -187,25 +208,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f paths: - node_modules/ script: - - npm install - - npm run docs:build - artifacts: - paths: - - public - only: - - main - ``` - -4. Alternatively, if you want to use an _alpine_ version of node, you have to install `git` manually. In that case, the code above modifies to this: - ```yaml - image: node:16-alpine - pages: - cache: - paths: - - node_modules/ - before_script: - - apk add git - script: + # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled - npm install - npm run docs:build artifacts: