swift-remove-markdown

📝 A zero-dependency Swift package inspired by the popular remove-markdown package

A Swift package that removes (strips) Markdown formatting from text.

What is it?

RemoveMarkdown is a lightweight text-extraction utility. It removes common Markdown markers while keeping readable content, links, image alt text, and code. It is designed for previews, excerpts, search indexing, and notifications—not as a validating CommonMark parser.

The package has no dependencies and supports older Apple platform versions where newer Markdown APIs may not be available.

When do I need it?

The typical use case is to display an excerpt from some Markdown text, without any of the actual Markdown syntax - for example in a list of posts.

Installation

Swift Package Manager

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/yvente/swift-remove-markdown.git", from: "1.0.0")
]

Or in Xcode:

1. File > Add Package Dependencies...
2. Enter the repository URL
3. Select your version requirements

Usage

Basic Usage

import RemoveMarkdown

let markdown = """
# This is a heading

This is a paragraph with [a link](http://www.disney.com/) in it.
"""

let plainText = removeMarkdown(markdown)
// Result: "This is a heading\n\nThis is a paragraph with a link in it."

With Options

You can customize the behavior by passing a RemoveMarkdownOptions struct:

import RemoveMarkdown

let options = RemoveMarkdownOptions(
    stripListLeaders: true,    // strip list leaders (default: true)
    listUnicodeChar: nil,      // char to insert instead of stripped list leaders (default: nil)
    gfm: true,                 // support GitHub-Flavored Markdown (default: true)
    useImgAltText: true,       // replace images with alt-text, if present (default: true)
    abbr: false,               // remove abbreviations (default: false)
    replaceLinksWithURL: false, // replace links with URL instead of text (default: false)
    htmlTagsToSkip: []         // HTML tags to preserve (default: [])
)

let plainText = removeMarkdown(markdown, options: options)

Options Explained

• stripListLeaders: When true, removes list markers like *, -, +, and numbered lists like 1.
• listUnicodeChar: If provided, replaces list leaders with this character instead of removing them entirely
• gfm: Enables GitHub-Flavored Markdown support (strikethrough, fenced code blocks, etc.)
• useImgAltText: When true, replaces image syntax with the alt text; when false, removes images entirely
• abbr: Removes abbreviation definitions when true
• replaceLinksWithURL: When true, replaces [text](url) with url instead of text
• htmlTagsToSkip: Array of HTML tag names to preserve in the output

Error Handling

The standard API returns the original input if an internal processing error occurs. Call the throwing API when you need to handle that error explicitly:

do {
    let plainText = try removeMarkdownThrowing(markdown)
    print(plainText)
} catch {
    print("Unable to process Markdown: \(error)")
}

The former throwError option is deprecated because a runtime option cannot change a non-throwing Swift function into a throwing one.

Examples

Stripping Emphasis

let text = "I italicized an *I* and it _made_ me *sad*."
let result = removeMarkdown(text)
// Result: "I italicized an I and it made me sad."

Removing Headers

let text = "## This is a heading"
let result = removeMarkdown(text)
// Result: "This is a heading"

Handling Lists

let text = """
* Item 1
* Item 2
* Item 3
"""
let result = removeMarkdown(text)
// Result: "Item 1\nItem 2\nItem 3"

Preserving Specific HTML Tags

let text = "<div>Content <sub>subscript</sub> <span>text</span></div>"
let options = RemoveMarkdownOptions(htmlTagsToSkip: ["sub"])
let result = removeMarkdown(text, options: options)
// Result: "Content <sub>subscript</sub> text"

Platform Support

• macOS 10.15+
• iOS 13.0+
• tvOS 13.0+
• watchOS 6.0+

Testing

Run tests using Swift Package Manager:

cd swift-remove-markdown
swift test

Or in Xcode:

1. Open Package.swift
2. Press ⌘U to run tests

Credits

This package is inspired by the remove-markdown package:

• Original JavaScript implementation: Stian Grytøyr (creator)
• Current maintainer: zuchka
• Original inspiration: Markdown Service Tools by Brett Terpstra

The initial rules and tests were ported from the original package. The Swift implementation also contains platform-specific fixes for Unicode ranges, balanced link delimiters, literal backslashes, and HTML-like comparison text. Exact behavior may differ as both projects evolve.

License

MIT License - see LICENSE file for details.

This Swift port maintains the same MIT License as the original remove-markdown package.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

To work on this package:

1. Clone the repository
2. Open Package.swift in Xcode
3. Make your changes
4. Run tests to ensure everything works
5. Submit a pull request

Future Enhancements

• Allow customization of regex patterns per rule
• Expand CommonMark edge-case coverage where it benefits plain-text extraction
• Performance optimizations