#Deployment

In this section, we will discuss the deployment of the project. We assume that you have completed the development of the project and now need to deploy the project online. You need to consider the following aspects:

• Production build and preview of the project.
• Static resource prefix configuration.
• Project base path configuration.
• Choose deployment platform for deployment.

#Build and preview

Before deployment, we need to first build the project in the production environment and preview it locally to ensure that the project can run normally. In Rspress projects, we can use the following scripts commands to build and preview:

{
  "scripts": {
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

It is worth noting that the final output will be output to the doc_build directory under the project root directory. The content in this directory is what we need to deploy.

#Static resource prefix configuration

We can divide the deployment output into two parts: HTML files and static resources. HTML files refer to the HTML files in the output directory. These files are the files we finally deploy to the server.

The so-called static resources refer to the static directory in the output directory, which contains the JavaScript, CSS, images and other static resources required by the project. When deploying, if you want to put these static resources on the CDN to ensure better access performance, instead of directly putting them on the server like HTML, then you need to configure the prefix of the static resources so that the project can correctly reference these static resources. You can complete it through builderConfig.output.assetPrefix:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    output: {
      assetPrefix: 'https://cdn.com/',
    },
  },
});

In this way, when referencing static resources in HTML, the prefix will be automatically added, for example:

<script src="https://cdn.com/static/js/app.123.js"></script>

#Project base path configuration

When deploying, we may need to deploy the project to a subpath. For example, if you plan to deploy your site to https://foo.github.io/bar/, then you should set the base parameter to "/bar/":

import { defineConfig } from '@rspress/core';

export default defineConfig({
  base: '/bar/',
});

#Deployment in platform

After completing the above configuration, we can deploy the output to the server. You have many choices, such as Zephyr, GitHub Pages, Netlify, Vercel, etc. Here we take Zephyr, GitHub Pages and Netlify as examples to explain how to deploy.

#Deploy with Zephyr Cloud

Zephyr Cloud is a zero-config deployment platform that integrates directly into your build process and provides global edge distribution.

#How to deploy

Follow the steps in zephyr-rspress-plugin.

During the build process, your Rspress documentation site will be automatically deployed and you'll receive a deployment URL.

Zephyr Cloud handles asset optimization, global CDN distribution, and provides automatic rollback capabilities for your documentation sites.

#Deploy via GitHub actions

If your project is hosted on GitHub, then you can deploy via GitHub Pages. GitHub Pages is a static website hosting service provided by GitHub, which allows you to directly deploy your project to GitHub without having to build your own server.

#1. Create workflow file

First, you need to create a file named .github/workflows/deploy.yml in the project root directory, with the following content:

name: Deploy Rspress site to Pages

on:
  push:
    branches: [main]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      - uses: pnpm/action-setup@v3 # pnpm is optional but recommended, you can also use npm / yarn
        with:
          version: 8
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Install dependencies
        run: pnpm install
      - name: Build with Rspress
        run: |
          pnpm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: doc_build

  # 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@v4

#2. Configure GitHub Actions

In the Pages column of the repository Settings interface, you can choose GitHub Actions as the deployment source.

#3. Push code to main branch

When you push the code to the main branch, GitHub Actions will automatically execute the deployment process. You can view the progress of the deployment in the Actions column. After the deployment is complete, you can access your site through https://<username>.github.io/<repository>/.

#Deploy via Netlify

Netlify is a Web application deployment platform, which allows you to directly deploy your project to Netlify without having to build your own server.

#Basic configuration

Deploying a project on Netlify is very simple. You only need to import your GitHub repository, and then configure some basic information to deploy. Just configure the following two fields:

• Build command: Build command, here we fill in the build command in the project, such as npm run build.
• Publish directory: Output directory, here we fill in the output directory doc_build in the project.

Then click the Deploy site button to complete the deployment.

#Configure custom domain

If you want to bind your site to your own domain, you can configure it in the Domain management column of Netlify. The specific configuration method can refer to the Netlify official documentation.

#Deploy to Kinsta static site hosting

You can deploy your Rspress site on Kinsta.

1. Login or create an account to view your MyKinsta dashboard.

2. Authorize Kinsta with your Git provider.

3. Select Static Sites from the left sidebar and press Add sites.

4. Select the repository and branch you want to deploy.

5. During the build settings, Kinsta will automatically try to fill out the Build command, Node version, and Publish directory. If it won't, fill out the following:

   • Build command: npm run build
   • Node version: 18.16.0
   • Publish directory: doc_build

6. Click the Create site.

#Deploy to Zeabur

Zeabur is a platform for deploying services instantly, which allows you to directly deploy your Rspress site without any other configurations.

#How to deploy

First of all, you need to create a Zeabur account. Then, follow the instructions to create a project and install a GitHub app to authorize Zeabur get your Rspress repository.

Click on Deploy New Service and import your Rspress repository, the deployment will be started automatically and Zeabur will recognize that your site is built with Rspress.

The deployment will be finished in a minute, you can also bind a free sub domain provided by Zeabur or your own domain for this site.