@5minds/processcube_docflow/README.md

Create webpage to view process documentation

# ProcessCube DocFlow

## Table of Contents

- [ProcessCube DocFlow](#processcube-docflow)
  - [Table of Contents](#table-of-contents)
  - [Description](#description)
  - [Usage](#usage)
    - [with NPM](#with-npm)
    - [with Docker](#with-docker)
    - [Options](#options)
  - [Development](#development)
    - [Requirements](#requirements)
    - [Start app locally](#start-app-locally)
  - [Running in the CI](#running-in-the-ci)

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

```bash
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](https://nextjs.org/docs/app/api-reference/next-config-js/basePath)
- `PROCESSES_DIR`: Custom path for processes
- `README_PATH`: Custom path to a README.md

## Development

### Requirements

If you want to run the app locally, you need [Docker-Desktop](https://docs.docker.com/desktop/) and [Node.js](https://nodejs.org/en) installed.

### Start app locally

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

1. Clone the repository.
2. Run `docker compose up -d` to start the ProcessCube®-Containers
3. Run `npm i` to install the dependencies.
4. Run `npm run dev` to start the Development-Server of the DocFlow-App
5. Visit `http://localhost:3000` in your browser.

## 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:

```yaml
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
```