Document

Prerequisites

(Local authoring) Writerside IDE plugin
- Download Writerside Jetbrains Plugin
- See how to add a Writerside instance
Writerside project exists in the repository under Writerside/
- Writerside/<instance_id>.tree (example: Writerside/dcs.tree)
- Writerside/writerside.cfg
- Writerside/topics/**
GitHub Pages enabled for the repository
- Settings → Pages → Build and deployment → Source: GitHub Actions

Secrets

GH_TOKEN — required Used for repository access and GitHub API interactions.
NPM_TOKEN — optional Required only if private packages must be installed.

How to Call This Workflow

This workflow is consumed as a reusable workflow. Applications explicitly opt in by invoking it from their local CI configuration.

Minimal Usage (Single Repository)

jobs:
  document:
    uses: kurocado-studio/platform/.github/workflows/workflow.document.yml@main
    secrets:
      GH_TOKEN: ${{ secrets.GH_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    with:
      instance_id: dcs

Execution Sequence

The diagram below illustrates how documentation is built and deployed when the workflow is triggered.

Purpose

This workflow centralizes documentation builds and GitHub Pages deployments across all Platform consumers.

It ensures every repo uses the same build tooling, artifact format, and deployment steps without duplicating YAML in each project. By owning documentation publishing at the Platform level, drift is prevented and fixes propagate to all applications automatically.

If this workflow is removed or bypassed, documentation deployments become inconsistent across repositories.

When to Use / When Not to Use

Use this workflow when:

you use Writerside and want a standardized GitHub Pages deployment
docs should only deploy when Writerside/** changes
you want a single canonical workflow for all repos

Do not use this workflow when:

docs are not Writerside-based
you must deploy docs from non-main branches
you need a custom documentation pipeline (different artifacts, hosting, or build system)

Repository Expectations

A valid Writerside instance exists under Writerside/.
GitHub Pages is configured to use GitHub Actions as the source.

Inputs & Outputs

Inputs

instance_id (string, required) The Writerside instance id (maps to Writerside/<instance_id>.tree).

Outputs

None

This workflow is intended to publish documentation to GitHub Pages when documentation changes.

Internal Dependencies

Platform Actions

.github/actions/install

External Dependencies

actions/checkout
JetBrains/writerside-github-action
actions/upload-artifact
actions/configure-pages
actions/upload-pages-artifact
actions/deploy-pages
unzip

Structural Topology

The following diagram shows the static dependency structure of the document workflow.

Failure Modes

Common failure cases include:

Missing secrets Dependency installation fails if required tokens are unavailable.
Invalid instance_id Writerside build fails if Writerside/<instance_id>.tree is missing.
GitHub Pages not configured Deploy steps fail if Pages is not set to GitHub Actions.
No Writerside changes The workflow intentionally skips deployment unless Writerside/** is modified.
Artifact/unzip failure Uploading or extracting the generated archive fails, blocking deployment.

Last modified: 18 December 2025