ProcessCube DocFlow

Description

A command to generate a documentation website for BPMN diagrams. The website is generated from a processes directory containing BPMN diagrams and a README.md file in the root directory of your project.

Usage

1. Have your BPMN diagrams in a processes directory.
2. Optional: Have a README.md file in the root directory of your project.

with NPM

1. Run npm i -g @5minds/processcube_docflow in the root directory of your project to install the package.
2. Run docflow build to generate the documentation website.
3. Run docflow serve to start the server.
4. Visit http://localhost:3000 in your browser.

with Docker

1. Run

docker run -p 3000:3000 -t -i -v ./processes:/src/processes -v ./README.md:/src/README.md 5minds/processcube_docflow

2. Visit http://localhost:3000 in your browser.

Options

Running docflow without any arguments will show the help message.

You can set environment variables during build or serve to configure the behavior of the command:

• OUT_DIR: The output directory for the build. Default: .static
• BASE_PATH: The base path for the app. Default: /. Used for Path-Based Routing
• PROCESSES_DIR: Custom path for processes
• README_PATH: Custom path to a README.md

Development

If you want to develop and test the package locally, you can do the following:

1. Clone the repository.
2. Run npm i to install the dependencies.
3. Run npm link to link the package. docflow should be available now.
4. Use the package as described in the usage section.

Running in the CI

If you want to automatically generate and deploy the documentation website in your CI workflow, you can use the following template:

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches:
      - main

# 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:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup Pages
        id: setup-pages
        uses: actions/configure-pages@v5

      - name: Install DocFlow
        run: npm i -g @5minds/processcube_docflow@develop

      - name: Build Documentation
        run: docflow build
        env:
          BASE_PATH: ${{ steps.setup-pages.outputs.base_path }}

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./.static

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4