# Werkbaum
**English** Β· [Deutsch](README.de.md)
**βΆ Try it live: ** (stable) Β· (latest build π§)
A textual, Markdown-like notation for work breakdown structures with
and/or decomposition β plus a live editor that renders it as a diagram.
```
[~] Werkbaum (XL) https://wiki.example.de/relaunch
- [~] Document store
| [x] Text file with copy+paste in the frontend (S)
- [x] Parser
- [x] Text input field in the frontend
| [ ] Backend
- [~] Display/rendering (XL)
- [/] H (S) @anna
- [ ] CMS integration (M)
| [ ] WordPress
| [?] Headless CMS
```
`-` = mandatory sub-package (all of, side by side in the diagram) Β·
`|` = alternative (any of, stacked) Β· `[β¦]` = status Β·
`(M)` = T-shirt effort Β· `@name` = responsibility Β· `%%` = comment.
## Usage
Open the [hosted editor](https://werkbaum.javagil.de) β edit text on
the left, the diagram is built live on the right. Toggles: transposed (narrow)
layout, show discarded elements.
### Loading a diagram from a URL
The editor can pull its notation text from an external text file via the
`sourceUrl` query parameter β handy for sharing a plan or keeping the source in
Git or a wiki:
**βΆ [Live example](https://werkbaum.javagil.de/?sourceUrl=https://raw.githubusercontent.com/mhoennig/werkbaum/main/docs/example-plan.txt)**
β loads [`docs/example-plan.txt`](docs/example-plan.txt):
```
https://werkbaum.javagil.de/?sourceUrl=https://raw.githubusercontent.com/mhoennig/werkbaum/main/docs/example-plan.txt
```
The loaded text becomes its own document whose **name is the URL**, so your own
documents stay untouched; the same link updates that one document instead of
piling up copies. The URL is the source of truth β it is re-fetched on every
load, so local edits to it do not survive a reload.
**Caveat β CORS:** the browser only fetches a foreign host if it sends
`Access-Control-Allow-Origin`. `raw.githubusercontent.com` and GitLab raw links
do; an arbitrary web server often does not. If loading fails the previous
content stays and a warning explains why. Only `http`/`https` are allowed.
### Running it locally
The editor source now lives as ES modules under `frontend/src/`, bundled by
[Vite](https://vitejs.dev/) (see `docs/DECISIONS.md` D19). Because browsers block
ES-module imports over `file://`, opening `frontend/index.html` directly no
longer works β use one of:
```bash
cd frontend
npm install # once
npm run dev # dev server at http://localhost:8137
npm test # Vitest unit tests
npm run build # -> frontend/dist/index.html (single self-contained file)
```
The built `dist/index.html` inlines all JS, CSS and the favicon, so **that** file
does open standalone via `file://` and is what gets deployed.
### Build hint & your own production install
Non-production builds carry a small hint next to the title (symbol + tooltip) so
it's clear this is **not** the stable instance:
- **Dev server** (`npm run dev`) β π§ "Preview β local development build"
- **Default build** (`npm run build`, incl. the GitHub Pages deploy) β π§
"Latest build β may still be buggy"
For **your own production install** the hint is switched off:
```bash
cd frontend
npm ci # or: npm install
npm run build:prod # -> frontend/dist/index.html WITHOUT the hint
```
`build:prod` runs Vite in mode `prod`; `frontend/.env.prod` sets
`VITE_BUILD_BADGE=none`, so the badge code is tree-shaken away entirely (it isn't
even present in the output source). Drop the resulting `dist/index.html` onto your
web space/server (standalone, `file://`-capable). Details: `app.js`
(`mountBuildBadge`), `docs/DECISIONS.md` D16.
Two things otherwise handled only by the Pages workflow, to fix up yourself when
self-hosting: the footer **MIT-License** link is relative to `../LICENSE` (place
that file one level above `index.html`, or adjust the link), and the **version
number** stays the source placeholder `1.0` (the workflow otherwise replaces it
from `VERSION` + commit count).
**Easier: `scripts/deploy-prod.sh`.** The script runs exactly that prod build
**and** both fix-ups (drop `LICENSE` alongside + straighten the link, footer
version + commit link just like the Pages workflow) and mirrors the result to a
server via rsync/SSH:
```bash
scripts/deploy-prod.sh mih00@mih00.hostsharing.net:~/doms/werkbaum.javagil.de/htdocs-ssl
```
The target is either this argument or β with no argument β the `DEPLOY_TARGET`
variable from the **git-ignored** file `.env` (template:
`.env.example`, copy it once and fill in the path). An argument
takes precedence.
Without `-y` it first shows a `--dry-run` preview and asks for confirmation.
`rsync --delete` ensures **nothing old** is left at the target β so the target
directory is treated as exclusive to Werkbaum (an in-flight Let's Encrypt
challenge under `.well-known/` is spared via `--filter=protect`, and web-friendly
755/644 permissions are enforced). (Hostsharing: a **directly-served** domain is
served from `β¦/htdocs-ssl/`; as a **subdomain** under another domain the web
directory would be `β¦/subs-ssl//`.)
## Project documents
- `frontend/` β editor Β· `backend/` β Kotlin/Spring (scaffold to follow, see backend/README.md)
- `docs/SPEC.md` β normative language definition
- `docs/DECISIONS.md` β design decisions with rationale
- `docs/ROADMAP.md` β Mermaid plugin, Taiga integration, Tenzu
- `docs/TASKS.md` β open tasks (checkboxes)
- `docs/brand/BRAND.md` β logo, wordmark, usage rules
- `docs/design/` β design derivation of the brand
- `CLAUDE.md` β project context for Claude Code
> **Note:** The detailed project documentation under `docs/` is maintained in
> German, the project's source language (see `CLAUDE.md`). This README is
> available in [English](README.md) and [German](README.de.md).
## Deployment
The editor is published as a static page on **GitHub Pages** via GitHub
Actions (workflow: `.github/workflows/pages.yml`). Triggered on every push to
`main` and manually (`workflow_dispatch`).
The workflow sets up Node, runs `npm ci`, `npm test` (Vitest) and `npm run build`
(Vite), then publishes the bundled `frontend/dist/index.html` as `index.html` at
the root URL, plus `LICENSE` for the MIT link in the footer. The favicon is
already inlined into the build, so nothing else needs copying; only the runtime
`../LICENSE` link is straightened on the copy. A failing test blocks the deploy.
`backend/` and the remaining `docs/` are not published.
While assembling the site, the workflow also stamps the version into the footer:
**major.minor** comes from the `VERSION` file (bumped by an explicit "bump
commit"), and the **micro** part is the number of commits since that last bump β
so it grows with every commit and resets to `0` right after a bump
(`Werkbaum 1.0.0`, `1.0.1`, β¦ then bump `VERSION` to `1.1` β `1.1.0`). Nothing is
written back to the repo. In the footer the name **Werkbaum** links to the
repository, while the **version number** links to that exact commit
(`β¦/commit/`). Opened locally, the editor shows the source placeholder
(`Werkbaum 1.0`).
**One-time setup:** In the repo settings under **Pages**, select **Source** =
"GitHub Actions". The repo must be **public** for this (GitHub Pages via Actions
is only available for private repos on a paid plan).
## License
MIT β see [LICENSE](LICENSE). Β© 2026 Michael HΓΆnnig. The bundled IBM Plex fonts
are under the SIL Open Font License 1.1 (see [LICENSE](LICENSE) and
`frontend/src/fonts/OFL.txt`).