Chore/refactoring images issue 48 v3

[sgort]

Closes #48
Replaces #51 and #52

Apologies if it seems a bit messy.

BPMN diagram viewer

I'm in the middle of testing my migration efforts and came accross this issue.

The special tag <div data-bpmn-diagram="../bpmn/catchandthrowpattern"></div> in docs\documentation\reference\bpmn20\events\error-events.md is meant to render it as an interactive BPMN diagram in the browser.

Operaton docs

For Operaton docs state to date, that is not the case though. See screenshot from live.

Camunda docs

On still existing Camunda docs it is working...

Known issue

Is this a known issue? Will I give it a try to get this fixed while testing my migration efforts?

[a-m-zill]

@sgort i know about the issue with BPMN diagram rendering.
You can give this a trial or we can put them in an own issue.

Thx

[sgort]

@sgort i know about the issue with BPMN diagram rendering. You can give this a trial or we can put them in an own issue.

Thx

I created #56 for this and will give it a try.

[sgort]

Concering BPMN files: BPMN files are documentation content, not static assets. They should stay with the markdown files.

Reasoning:

• BPMN files are viewed inline (like code examples)
• They're documentation content, not decorative images
• They're versioned with docs (should stay together)
• The BPMN viewer plugin copies them to build automatically
• Contributors expect them next to the markdown they document

In the script we now search for:

  // All file extensions to migrate
  assetExtensions: [
    // Images
    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp', '.ico',
    // BPMN & Process files
    // Note:.bpmn, .dmn, .cmmn are intentionally excluded
    // Documents (not markdown - those stay in docs/)
    '.pdf', '.odg', '.odt',
    // Scripts & Data
    '.js', '.json', '.xml', '.csv',

[sgort]

Manually checking 22 orphaned assets in the dry run, I came across a false positive.

"Orphaned" asset documentation\reference\dmn\decision-table\img\map.js is referenced as <script type="text/javascript" src="./img/map.js"></script> in docs\documentation\reference\dmn\decision-table\index.md

Decided to exclude .js files from migration:

• They're code/scripts used by documentation
• Should stay with the markdown that uses them
• Similar logic to BPMN files

[sgort]

Before and after analysis:

PNG BEFORE: 437 (docs) + 9 (static) = 446 total
PNG AFTER:  0 (docs) + 441 (static) = 441 total
MISSING:    446 - 441 = 5 PNG

SVG BEFORE: 86 (docs) + 4 (static) = 90 total  
SVG AFTER:  0 (docs) + 90 (static) = 90 total
MISSING:    0 SVG ✅

These 5 are among the PNG files in toolkit/orphaned-backup/ and not counted in the after report.

[sgort]

Changes

Migration Process

1. ✅ Pre-migration verification (0 broken references)
2. ✅ Manual review of 22 orphaned assets
3. ✅ Dry-run migration test
4. ✅ Live migration execution
5. ✅ Fixed 16 broken references (path corrections)
6. ✅ Post-migration verification (0 broken references)

Path Changes

• Before: ./img/example.png (relative paths)
• After: /img/documentation/section/example.png (absolute paths)

Fixed Issues

• 16 broken references caused by directory structure flattening
• 12 SVG event symbols in BPMN reference
• 4 PNG images with incorrect paths after migration

Testing

✅ Verification Steps Completed

• All 541 asset references verified working
• 0 broken references confirmed
• BPMN diagrams render correctly and are interactive
• All documentation pages load with images displaying
• Dev server runs without errors (npm start)

📸 Test Pages

• BPMN Reference: /docs/documentation/reference/bpmn20
• Variables: /docs/documentation/user-guide/process-engine/variables
• Cockpit Plugins: /docs/documentation/webapps/cockpit/extend/plugins
• Quick Start: /docs/get-started/quick-start/user-task
• BPMN Viewer: /docs/documentation/reference/bpmn20/events/error-events

Migration Toolkit

Added comprehensive toolkit in toolkit/ directory:

• Migration scripts with dry-run capability
• Broken reference checker
• File counter for verification
• Fix scripts for post-migration corrections
• Complete migration logs

Checklist

• Migration tested with dry-run
• All assets migrated successfully
• All references updated and verified
• Zero broken references
• Documentation renders correctly
• BPMN diagrams work
• Orphaned assets reviewed manually

[sgort]

🧰 Migration Toolkit (Review Only - Remove Before Merge)

Please do not merge the toolkit directory!

The toolkit/ directory contains scripts and logs used during the migration process. It's included in this PR to help you review the migration script(s) and verify results, but should be removed before merging.

[a-m-zill]

Thx @sgort for your work.
I have checked a bunch of files and thinks it looks good to me. I have started it local on my computer and can not find broken images. When i miss something, so we can fix it later.

You can now remove the toolkit folder and then we can merge it.