If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gonzalezreal/swift-markdown-ui shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4mo ago
• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gonzalezreal/swift-markdown-ui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gonzalezreal/swift-markdown-ui.

What it runs against: a local clone of gonzalezreal/swift-markdown-ui — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gonzalezreal/swift-markdown-ui | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 163 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gonzalezreal/swift-markdown-ui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gonzalezreal/swift-markdown-ui.git
#   cd swift-markdown-ui
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gonzalezreal/swift-markdown-ui and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gonzalezreal/swift-markdown-ui(\\.git)?\\b" \\
  && ok "origin remote is gonzalezreal/swift-markdown-ui" \\
  || miss "origin remote is not gonzalezreal/swift-markdown-ui (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift" \\
  && ok "Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift" \\
  || miss "missing critical file: Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift"
test -f "Sources/MarkdownUI/DSL/Blocks/MarkdownContentBuilder.swift" \\
  && ok "Sources/MarkdownUI/DSL/Blocks/MarkdownContentBuilder.swift" \\
  || miss "missing critical file: Sources/MarkdownUI/DSL/Blocks/MarkdownContentBuilder.swift"
test -f "Sources/MarkdownUI/DSL/Inlines/InlineContent.swift" \\
  && ok "Sources/MarkdownUI/DSL/Inlines/InlineContent.swift" \\
  || miss "missing critical file: Sources/MarkdownUI/DSL/Inlines/InlineContent.swift"
test -f "Sources/MarkdownUI/DSL/Inlines/InlineContentBuilder.swift" \\
  && ok "Sources/MarkdownUI/DSL/Inlines/InlineContentBuilder.swift" \\
  || miss "missing critical file: Sources/MarkdownUI/DSL/Inlines/InlineContentBuilder.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 163 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~133d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gonzalezreal/swift-markdown-ui"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MarkdownUI is a SwiftUI library that renders GitHub Flavored Markdown (GFM) into native SwiftUI views with comprehensive styling support. It handles images, tables, code blocks with syntax highlighting, lists (including task lists), blockquotes, and thematic breaks, enabling developers to display rich markdown content directly in iOS/macOS/tvOS/watchOS apps without external web views. Standard Swift Package with source in Sources/MarkdownUI/ (289KB of Swift code), a comprehensive demo iOS app in Examples/Demo/ showing all markdown features, and CI automation via GitHub Actions. The package uses SwiftPM (.swiftpm/xcode/ workspace) for development and publishes to Swift Package Index (.spi.yml config present).

Swift/SwiftUI developers building iOS, macOS, tvOS, or watchOS apps who need to display formatted markdown content (like READMEs, documentation, or user-generated markdown) and want full styling control without relying on WebKit or HTML rendering.

Production-ready but in maintenance mode. The project has comprehensive CI/CD via .github/workflows/ci.yml and .github/workflows/format.yml, well-structured examples in Examples/Demo/, and DocC documentation in Sources/MarkdownUI/Documentation.docc/. However, the maintainer has frozen new feature development and moved active work to the successor project Textual; expect stable bug fixes but no major new capabilities.

Low risk for existing users but high risk for new adoption. Single maintainer (gonzalezreal) with the project explicitly in maintenance mode per the README. The successor project Textual is the recommended target for new development. No visible breaking changes recently, but lack of active development means dependency vulnerabilities may not be addressed quickly and new Swift/iOS features won't be integrated.

Project is in maintenance mode with no active feature development. The README explicitly directs users to https://github.com/gonzalezreal/textual for new development. Expect only critical bug fixes and maintenance work.

git clone https://github.com/gonzalezreal/swift-markdown-ui.git
cd swift-markdown-ui
# Open in Xcode:
open .swiftpm/xcode/package.xcworkspace
# Or run the demo app:
open Examples/Demo/Demo.xcodeproj

Daily commands: Open Examples/Demo/Demo.xcodeproj in Xcode and run on a simulator or device (iOS 15+). The demo app in Examples/Demo/Demo/ contains multiple view controllers (ContentView.swift, HeadingsView.swift, ListsView.swift, TablesView.swift, etc.) demonstrating all markdown features.

• Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift — Core abstraction defining the primary markdown block types and the foundational MarkdownContent protocol that all block-level elements conform to.
• Sources/MarkdownUI/DSL/Blocks/MarkdownContentBuilder.swift — Result builder enabling SwiftUI-like DSL syntax for composing markdown blocks; essential for understanding how markdown content is declaratively constructed.
• Sources/MarkdownUI/DSL/Inlines/InlineContent.swift — Core abstraction for inline markdown elements (emphasis, links, code, etc.); mirrors MarkdownContent but for inline-level constructs.
• Sources/MarkdownUI/DSL/Inlines/InlineContentBuilder.swift — Result builder for inline content; essential for understanding how inline styling and formatting are composed.
• Package.swift — Swift Package definition; defines dependencies, platforms, and module structure—required reading for build and integration.
• Examples/Demo/Demo/ContentView.swift — Primary demo entry point showing real-world usage patterns of the MarkdownUI DSL and rendering capabilities.

Add a new block-level markdown element

1. Create a new struct conforming to MarkdownContent in Sources/MarkdownUI/DSL/Blocks/ (Sources/MarkdownUI/DSL/Blocks/YourBlock.swift)
2. Add the new case to the MarkdownContent enum in MarkdownContent.swift (Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift)
3. Add builder support if the block contains nested content (e.g., similar to BulletedList) (Sources/MarkdownUI/DSL/Blocks/YourBlockContentBuilder.swift)
4. Add rendering logic by implementing SwiftUI View conformance in the same file (Sources/MarkdownUI/DSL/Blocks/YourBlock.swift)
5. Add usage example to the demo app (Examples/Demo/Demo/DemoView.swift)

Add a new inline markdown element

1. Create a new struct conforming to InlineContent in Sources/MarkdownUI/DSL/Inlines/ (Sources/MarkdownUI/DSL/Inlines/YourInline.swift)
2. Add the new case to the InlineContent enum in InlineContent.swift (Sources/MarkdownUI/DSL/Inlines/InlineContent.swift)
3. Implement SwiftUI Text or View rendering in the same file (Sources/MarkdownUI/DSL/Inlines/YourInline.swift)
4. Add demo and documentation example (Examples/Demo/Demo/TextStylesView.swift)

Customize block styling and themes

1. Create a theme struct or environment key (pattern: use SwiftUI @Environment) (Sources/MarkdownUI/DSL/Blocks/MarkdownContent.swift)
2. Apply .environment() modifier in block rendering implementations (Sources/MarkdownUI/DSL/Blocks/Heading.swift)
3. Inject theme in demo app at root level (Examples/Demo/Demo/ContentView.swift)

• SwiftUI — Declarative, reactive UI framework for Apple platforms; enables markdown rendering with native UIKit/AppKit underneath.
• Result Builders (@MarkdownContent, @InlineContent) — Provide ergonomic, expression-like DSL syntax similar to SwiftUI's @ViewBuilder, hiding implementation details of block/inline composition.
• Swift Package Manager — Standard distribution mechanism for Swift libraries; simpler than CocoaPods/Carthage for SPM-native projects.
• DocC — Apple's native documentation compiler for Swift; integrates with Xcode and Swift Package Index for discoverable, maintainable API docs.

• Maintenance mode; new development in Textual repository

  • Why: MarkdownUI evolved into architecture lessons learned that shaped Textual, a more general-purpose text rendering engine.
  • Consequence: This repo receives only bug fixes and maintenance; cutting-edge features go to Textual. Users requiring advanced features should migrate.

• DSL-based API rather than markdown string parsing

  • Why: Directly composing blocks and inlines in Swift provides type safety, compile-time checks, and IDE autocomplete.
  • Consequence: Requires programmatic construction; does not natively parse raw markdown strings. Trade-off between safety/DX and flexibility.

• SwiftUI-only (no UIView/NSView wrappers for iOS 13 or macOS 10.15 support)

  • Why: Reduces maintenance burden and dependency surface; aligns with Apple's direction.
  • Consequence: Incompatible with legacy iOS/macOS versions; users on older OS versions cannot use this library.

• Does not parse raw markdown strings; focuses on programmatic block/inline construction.
• Not a real-time collaborative editor; view-only rendering library.
• Does not provide web rendering (HTML export); SwiftUI-only output.
• Not a drop-in replacement for system Text or Markdown on iOS/macOS; distinct API surface.

The project is in maintenance mode with active development moved to Textual—contributing major features here will likely be rejected. The demo app uses syntax highlighting via Splash (see Examples/Demo/Demo/SyntaxHighlighter/SplashCodeSyntaxHighlighter.swift) but this is optional for the core library. Some advanced features like multi-image paragraphs and tables require iOS 16.0+/macOS 13.0+ despite the library supporting iOS 15.0+—check platform-specific availability attributes in rendering code. No Makefile targets are documented in the provided data, so make commands may not be obvious.

• GitHub Flavored Markdown (GFM) Spec — MarkdownUI's entire rendering logic is built to conform to GFM—understanding task lists, table syntax, strikethrough, and autolinks is essential to knowing what the library can parse and render
• Abstract Syntax Tree (AST) Parsing — MarkdownUI parses markdown strings into an AST, then recursively renders tree nodes as SwiftUI Views—understanding this two-phase process is key to modifying rendering behavior
• SwiftUI View Hierarchy & Composition — The library composes nested SwiftUI Views (Text, VStack, Image, etc.) to represent markdown structure—mastering SwiftUI's declarative composition model is essential for contributing rendering code
• Markdown Block Elements vs Inline Elements — GFM distinguishes between block-level (paragraphs, lists, code blocks) and inline (bold, links, code spans) elements—MarkdownUI's AST likely mirrors this distinction and rendering differs significantly between them
• Platform-Conditional Availability (@available attribute) — MarkdownUI supports iOS 15.0+ but some features (tables, multi-image layout) require iOS 16.0+—code heavily uses @available checks that a contributor must understand to avoid runtime crashes
• DocC (Documentation Compiler) — The library uses Apple's DocC format for API documentation in Sources/MarkdownUI/Documentation.docc/—understanding DocC syntax is necessary to add or maintain library documentation

• gonzalezreal/textual — The official successor project—new development has moved here; SwiftUI text rendering engine evolved from MarkdownUI lessons learned
• apple/swift-markdown — Apple's official Swift Markdown parser library; MarkdownUI likely depends on or mirrors this for parsing GFM AST
• JohnSundell/Publish — Static site generator in Swift that uses markdown for content; complements MarkdownUI for markdown-heavy applications
• realm/SwiftLint — Swift code linter often used in projects like this for CI automation alongside SwiftFormat
• pointfreeco/swift-composable-architecture — Popular SwiftUI architecture pattern; useful reference for structuring complex markdown rendering state in larger apps

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for DSL block components

The repo has multiple DSL block files (Blockquote.swift, BulletedList.swift, CodeBlock.swift, Heading.swift, NumberedList.swift) but there's no visible Tests directory in the file structure. Given the repo is in maintenance mode with focused API surface, adding targeted unit tests for each DSL component would improve reliability and serve as regression tests for future maintainers.

• [ ] Create Tests/MarkdownUITests directory structure
• [ ] Add unit tests for Sources/MarkdownUI/DSL/Blocks/Blockquote.swift covering rendering and styling edge cases
• [ ] Add unit tests for Sources/MarkdownUI/DSL/Blocks/BulletedList.swift and NumberedList.swift testing nesting and formatting
• [ ] Add unit tests for Sources/MarkdownUI/DSL/Blocks/CodeBlock.swift testing syntax highlighting integration
• [ ] Update .github/workflows/ci.yml to run 'swift test' if not already present

Document custom syntax highlighter integration pattern with working example

The Examples/Demo/SyntaxHighlighter/ directory contains SplashCodeSyntaxHighlighter.swift and TextOutputFormat.swift, suggesting a plugin pattern exists, but there's no dedicated documentation explaining how to implement custom syntax highlighters. This is a concrete feature gap that would help users extend the library.

• [ ] Create Sources/MarkdownUI/Documentation.docc/SyntaxHighlighting.md documenting the highlighter protocol/interface
• [ ] Add inline code comments to Sources/MarkdownUI/DSL/Blocks/CodeBlock.swift explaining the customization points
• [ ] Create a minimal example markdown file in Examples/ showing before/after of custom highlighter usage
• [ ] Reference the new documentation in README.md in a 'Customization' or 'Advanced Usage' section

Add SwiftUI Preview snapshots for all demo views

The Examples/Demo directory has multiple view files (HeadingsView.swift, ListsView.swift, TablesView.swift, etc.) but likely lack proper SwiftUI previews for rapid development and visual regression detection. Adding comprehensive #Preview macros would improve the contributor experience and serve as visual documentation.

• [ ] Add #Preview blocks to Examples/Demo/Demo/HeadingsView.swift with various heading levels
• [ ] Add #Preview blocks to Examples/Demo/Demo/ListsView.swift showing bulleted and numbered lists
• [ ] Add #Preview blocks to Examples/Demo/Demo/TablesView.swift, QuotesView.swift, and ImagesView.swift
• [ ] Update Examples/Demo/Demo/CodeView.swift and CodeSyntaxHighlightView.swift with syntax highlighting previews
• [ ] Verify all previews render without errors in Xcode canvas

• Add comprehensive unit tests for markdown parsing edge cases (task list parsing, nested blockquotes, mixed list types) since test presence is not mentioned in the file list—start by creating Tests/MarkdownUITests/ParserTests.swift
• Document the theming API with worked examples in DocC showing how to create custom themes beyond the built-in ones—add new guides to Sources/MarkdownUI/Documentation.docc/Guides/
• Create a compatibility matrix in the README or wiki showing exactly which markdown features work on which OS versions (iOS 15 vs 16+, tvOS 15 vs 16+, etc.) since this is mentioned but not fully specified

The codebase appears to have a strong security posture with no critical or high-severity vulnerabilities detected. The Swift/SwiftUI project follows standard package management practices with no evident hardcoded secrets, injection vulnerabilities, or dangerous configurations visible in the file structure. The primary concern is that the project is in maintenance mode, meaning it may not receive timely security updates. No external dependencies are visible in the provided Package.swift content, which reduces the attack surface. Code organization follows Swift best practices with clear separation of concerns (DSL, Blocks, Inlines). GitHub Actions CI/CD pipeline is in place for automated testing.

• Low · Project in Maintenance Mode — README.md, Package.swift. The project is explicitly stated to be in maintenance mode with new development moved to Textual. This means security updates and bug fixes may not be actively developed or released for this codebase. Fix: Users should consider migrating to the Textual project (https://github.com/gonzalezreal/textual) for active security support and new features.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.