Ashton (AttributedStringHTMLTransformation) is an iOS and macOS library for fast conversion of NSAttributedStrings into HTML, and back. Ashton is battle-tested and used in MindNode, for persisting formatted strings.
The latest release is a complete rewrite in Swift focusing on improved performance and functional backwards compatibility to Ashton 1.x. The new codebase has a comprehensive test suite with a test coverage of > 90% and additional tests against the legacy 1.0 output.
Find out more about the launch of Ashton 2.0 in our Blog Post.
NSAttributedString.Key attributes are supported, when converting to
- ☑ .backgroundColor (persisted as RGBA)
- ☑ .foregroundColor (persisted as RGBA)
- ☑ .underlineStyle (single, double, thick)
- ☑ .underlineColor (persisted as RGBA)
- ☑ .strikethroughColor (persisted as RGBA)
- ☑ .strikethroughStyle (single, double, thick)
- ☑ .font
- ☑ .paragraphStyle (text alignment)
- ☑ .baselineOffset
- ☑ NSSuperScript
- ☑ .link
Supported HTML Tags & Attributes
As Ashton supports only tags which are necessary to persist the attributes mentioned above, not all HTML tags are supported when converting
AttributedString. Basically, Ashton converts an AttributedString into a concatenation of
a tags with style attributes.
Supported HTML Tags:
- ☑ span
- ☑ p
- ☑ a
- ☑ em
- ☑ strong
The following style attribute keys are supported:
- ☑ background-color
- ☑ color
- ☑ text-decoration
- ☑ font
- ☑ text-align
- ☑ vertical-align
- ☑ Additional custom attributes (-cocoa-strikethrough-color, -cocoa-underline-color, -cocoa-baseline-offset, -cocoa-vertical-align, -cocoa-font-postscriptname, -cocoa-underline, -cocoa-strikethrough, -cocoa-fontFeatures)
Colors have to be formatted as rgba like
rgba(0, 0, 0, 1.000000).
Add this line to your Cartfile.
Integration with the Swift Package Manager
The Swift Package Manager is a dependency manager integrated with the Swift build system. To learn how to use the Swift Package Manager for your project, please read the official documentation.
To add ZIP Foundation as a dependency, you have to add it to the
dependencies of your
Package.swift file and refer to that dependency in your
// swift-tools-version:5.1 import PackageDescription let package = Package( name: "<Your Product Name>", dependencies: [ .package(url: "https://github.com/IdeasOnCanvas/Ashton/", .upToNextMajor(from: "2.0.0")) ], targets: [ .target( name: "<Your Target Name>", dependencies: ["Ashton"]), ] )
After adding the dependency, you can fetch the library with:
$ swift package resolve
let htmlString = Ashton.encode(attributedString)
let attributedString = Ashton.decode(htmlString)
An example app can be found in the
/Example directory. It can be used to test
NSAttributedString -> HTML ->
NSAttributedString roundtrips and also to extract the HTML representation of an `NSAttributedString.
You may find interesting
- [Chore] Update project settings (Xcode 12)
- [Chore] Update ruby gems
- [Bugfix] Fixes skipping single style attributes after parsing text-decoration attributes (#30)
[Enhancement] Add parsing completion handler for reporting unknown fonts (#23)