Skip to content

Docpress action 🤖 ​

Automate your portfolio or documentation website with Docpress. This GitHub Action collects the documentation of your repositories from GitHub or GitLab, builds the website with Vitepress, and can deploy it to GitHub Pages.

Usage ​

The following workflow builds the website of the repository owner on each push to main, with a contributions page, and deploys it to GitHub Pages:

yml
name: Website

on:
  push:
    branches:
    - main
  workflow_dispatch:

jobs:
  website:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.docpress.outputs.page_url }}
    steps:
    - name: Checkout repository
      uses: actions/checkout@v7

    - name: Build and deploy the website
      id: docpress
      uses: this-is-tobi/docpress-action@v0
      with:
        contributions: true
        deploy: true

TIP

GitHub Pages has to deploy from GitHub Actions: in the repository settings, under Pages, set Source to GitHub Actions.

Without deploy: true, the website is still built in docpress/.vitepress/dist and uploaded as a GitHub Pages artifact, for the next steps or for a later job using actions/deploy-pages.

The action runs the docpress image, so it needs a Linux runner with Docker, such as ubuntu-latest.

Inputs ​

Every docpress command line option has an input, named like the matching key of the configuration file. Only the inputs that are set are passed to docpress.

InputDescriptionDefault
acronymsComma-separated words kept exactly as written in generated sidebar labels and home page titles, such as CLI or API.-
branchBranch used to collect Git provider data. Defaults to each repository's own default branch.-
configPath to the docpress configuration file, relative to the repository root. Only the inputs that are set are passed to docpress, and they take precedence over the file.-
contributionsSet to true to create the contributions page, listing the public repositories owned by others where the user's pull requests were merged.-
contributionsFilterComma-separated owners (owner) or repositories (owner/repo) shown on the contributions page. Prefix an entry with ! to hide it instead.-
extraHeaderPagesComma-separated list of additional files or directories for Vitepress header pages.-
extraPublicContentComma-separated list of additional files or directories for Vitepress public folder.-
extraThemeComma-separated list of additional files or directories for Vitepress theme.-
forksDeprecated alias of contributions.-
gitProviderGit provider used to retrieve data, github or gitlab. Defaults to github.-
lastUpdatedSet to true to show the date of each page's last Git commit.-
logLevelVerbosity of the docpress output, among error, warn, info, trace and debug. Defaults to info.-
reposFilterComma-separated repositories to retrieve from Git provider. Defaults to all user's public repositories.-
sidebarCollapsedCollapse behaviour of the generated sidebar groups. true collapses them, false expands them, null makes them non-collapsible.-
sidebarModeShape of the generated sidebar. single lists every repository in one sidebar, multi gives each repository its own.-
tokenToken used to collect data from the Git provider. Defaults to the workflow token for GitHub.-
usernamesComma-separated list of git provider usernames to collect data. Defaults to the repository owner, unless a configuration file is given.-
vitepressConfigPath to the Vitepress configuration file.-
websiteTaglineWebsite tagline.-
websiteTitleWebsite title.-
versionDocpress version, a tag of the ghcr.io/this-is-tobi/docpress image. Defaults to the release pinned by this version of the action; 0 follows the latest 0.x release instead.pinned release
deployWhether or not to deploy generated website to GitHub Pages.false
artifactNameName of the uploaded GitHub Pages artifact, to tell apart several builds in one workflow run.github-pages

Outputs ​

OutputDescription
page_urlURL of the deployed website, when deploy is true.

Configuration file ​

A docpress configuration file holds the same options and more, such as the home page hero or the Vitepress configuration. Give its path with config:

yml
- name: Build and deploy the website
  id: docpress
  uses: this-is-tobi/docpress-action@v0
  with:
    config: ./docpress.config.json
    deploy: true
  • Paths, in the inputs and in the file, are relative to the repository root.
  • Inputs that are set take precedence over the file, so keep each option in one place.
  • With a configuration file, the usernames no longer default to the repository owner: set them in the file or with usernames.

Docpress version ​

Each release of the action runs an exact docpress release, so a workflow pinned to a version of the action always builds with the same docpress, and @v0 moves to a new docpress through a new release of the action. Set version to run another tag of the docpress image: an exact release such as 0.14.0, or 0 to follow the latest 0.x release.

Token ​

The action passes docpress the workflow token, so its GitHub API requests are authenticated. Set token to use another one, such as a personal access token for a higher rate limit, or a GitLab token: GitLab never receives the workflow token. docpress reads the token from the environment since version 0.10.2, so an older version builds without one.

Manual and scheduled runs ​

yml
name: Website

on:
  schedule:
  - cron: "0 2 * * *"
  workflow_dispatch:
    inputs:
      deploy:
        description: Deploy the website to GitHub Pages
        type: boolean
        default: false

jobs:
  website:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.docpress.outputs.page_url }}
    steps:
    - name: Checkout repository
      uses: actions/checkout@v7

    - name: Build the website
      id: docpress
      uses: this-is-tobi/docpress-action@v0
      with:
        config: ./docpress.config.json
        # Scheduled runs always deploy, manual runs only when asked
        deploy: ${{ github.event_name == 'schedule' || inputs.deploy }}

Troubleshooting ​

  • Cannot read config file: the path is relative to the repository root, and the repository has to be checked out before the action runs.
  • The deployment fails: the job needs the pages: write and id-token: write permissions and the github-pages environment, and GitHub Pages has to deploy from GitHub Actions.
  • A repository is missing: docpress only lists public repositories, and reads each one from its own default branch unless branch says otherwise.

Contributing ​

Contributions are welcome! If you have a feature or bugfix to propose, please create an issue or submit a pull request.

Sources ​

Take a look at the project sources.

Released under the MIT License.