Requirements Analysis for Issue #18

Problem Summary

MacDown 3000 is experiencing Mermaid gantt diagram rendering issues:

Today's indicator line disappears when date format isn't set
X-axis date labels overlap in gantt charts

Root Cause Analysis

Investigation Findings

PR #1156 Not Applied: The fix from the original MacDownApp/macdown repo (PR #1156) has NOT been applied to MacDown 3000. The mermaid.forest.css file is still being loaded.
Current Implementation (in MPRenderer.m):
- Lines 437-445: mermaidStylesheets method loads mermaid.forest.css
- Lines 490-493: CSS is added to stylesheets array when Mermaid is enabled
- Lines 685-689: Same CSS loaded during HTML export

Missing Modern Theme Configuration: The mermaid.init.js file initializes Mermaid but does NOT specify a theme:

mermaid.initialize({
  startOnLoad: false,
  flowchart: {
    htmlLabels: false,
    useMaxWidth: true
  }
  // Missing: theme: 'forest'
});

Why This Causes Problems:
- Newer Mermaid versions (8.0+) use the theme API, not separate CSS files
- Loading forest.css externally interferes with Mermaid's internal theming
- This was also causing Graphviz rendering issues (per original issue #1138)
- Gantt-specific CSS rules in forest.css may conflict with Mermaid's layout engine

Solution Approach

Following the intent of PR #1156 but using the modern API approach:

Remove forest.css loading from MPRenderer.m:
- Remove/comment out lines 441-442 in mermaidStylesheets method
- Verify removal in both preview path (lines 490-493) and export path (lines 685-689)
Add theme configuration to mermaid.init.js:
- Add theme: 'forest' to the mermaid.initialize() call
- This uses Mermaid's built-in forest theme via the modern API
Optional: Add gantt-specific configuration:
- Consider adding gantt: { todayMarker: 'on' } to ensure today indicator is visible
- May add axisFormat if date overlap issues persist

Test Cases

Test Case 1: Gantt with date format

gantt
    dateFormat YYYY-MM-DD
    title Project Timeline
    section Planning
    Requirements    :a1, 2025-11-01, 30d
    Design         :a2, after a1, 20d
    section Development
    Implementation :a3, after a2, 45d

Expected: Today's indicator line (red vertical line) should appear if today falls within the date range.

Test Case 2: Gantt without explicit date format (uses default)

gantt
    title Simple Project
    section Phase 1
    Task A :2025-11-01, 2025-11-15
    Task B :2025-11-16, 2025-11-30

Expected:

Today's indicator should still appear
X-axis date labels should not overlap

Test Case 3: Verify other diagram types still work

Flow charts
Sequence diagrams
Graphviz diagrams

Assumptions

Since no additional information was provided:

Preserve visual appearance: Use Mermaid's built-in forest theme to maintain the green color scheme users expect
Backward compatibility: Ensure existing Mermaid diagrams continue to render correctly
Manual testing required: As a macOS application, visual verification will be done via GitHub Actions CI
Modern API preferred: Use the initialize() configuration rather than external CSS files

Next Steps

Wait for user confirmation on this approach
Consult Groucho (architect) for implementation guidance
Apply the fix (remove CSS loading, add theme config)
Test via CI on macOS runners
Get code review from Chico
Create pull request

Note: This analysis is based on the codebase investigation, the original issue #1157, and PR #1156 from MacDownApp/macdown. The Mermaid version appears to be from late 2019 (likely 8.4.x), which supports the theme API.

Mermaid issue on latest release 0.8.0d71 #18

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions