{"id":2035,"url":"https://github.com/indragiek/CocoaMarkdown","last_synced_at":"2025-08-02T23:31:15.254Z","repository":{"id":25727417,"uuid":"29164546","full_name":"indragiek/CocoaMarkdown","owner":"indragiek","description":"Markdown parsing and rendering for iOS and OS X","archived":false,"fork":false,"pushed_at":"2019-12-13T20:01:41.000Z","size":1132,"stargazers_count":1202,"open_issues_count":9,"forks_count":158,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-12-01T15:08:11.398Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indragiek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-13T00:35:36.000Z","updated_at":"2024-11-16T09:22:50.000Z","dependencies_parsed_at":"2022-07-27T05:16:38.413Z","dependency_job_id":null,"html_url":"https://github.com/indragiek/CocoaMarkdown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indragiek%2FCocoaMarkdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indragiek%2FCocoaMarkdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indragiek%2FCocoaMarkdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indragiek%2FCocoaMarkdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indragiek","download_url":"https://codeload.github.com/indragiek/CocoaMarkdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228503083,"owners_count":17930506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-01-05T20:16:01.781Z","updated_at":"2024-12-06T17:30:29.686Z","avatar_url":"https://github.com/indragiek.png","language":"Objective-C","funding_links":[],"categories":["Text","UI","IOS 或 OSX","Markdown"],"sub_categories":["Other free courses","Layout","Other Testing","Keychain"],"readme":"## CocoaMarkdown\n#### Markdown parsing and rendering for iOS and macOS\n\nCocoaMarkdown is a cross-platform framework for parsing and rendering Markdown, built on top of the [C reference implementation](https://github.com/jgm/CommonMark) of [CommonMark](http://commonmark.org).\n\n### Why?\n\nCocoaMarkdown aims to solve two primary problems better than existing libraries:\n\n1. **More flexibility**. CocoaMarkdown allows you to define custom parsing hooks or even traverse the Markdown AST using the low-level API.\n2. **Efficient `NSAttributedString` creation for easy rendering on iOS and macOS**. Most existing libraries just generate HTML from the Markdown, which is not a convenient representation to work with in native apps.\n\n![Example app macOS](images/example-app-mac.png)\n\n![Example app iOS](images/example-app-iOS.png)\n\n### Installation\n\nFirst you will want to add this project as a submodule to your project:\n\n```\ngit submodule add https://github.com/indragiek/CocoaMarkdown.git\n```\n\nThen, you need to pull down all of its dependencies.\n\n```\ncd CocoaMarkdown\ngit submodule update --init --recursive\n```\n\nNext, drag the `.xcodeproj` file from within `CocoaMarkdown` into your project. After that, click on the General tab of your target. Select the plus button under \"Embedded Binaries\" and select the CocoaMarkdown.framework.\n\n### API\n\n#### Traversing the Markdown AST\n\n[`CMNode`](CocoaMarkdown/CMNode.h) and [`CMIterator`](CocoaMarkdown/CMIterator.h) wrap CommonMark's C types with an object-oriented interface for traversal of the Markdown AST.\n\n```swift\nlet document = CMDocument(contentsOfFile: path, options: [])\ndocument.rootNode.iterator().enumerateUsingBlock { (node, _, _) in\n    print(\"String value: \\(node.stringValue)\")\n}\n```\n\n#### Building Custom Renderers\n\nThe [`CMParser`](CocoaMarkdown/CMParser.h) class isn't _really_ a parser (it just traverses the AST), but it defines an `NSXMLParser`-style delegate API that provides handy callbacks for building your own renderers:\n\n```objective-c\n@protocol CMParserDelegate \u003cNSObject\u003e\n@optional\n- (void)parserDidStartDocument:(CMParser *)parser;\n- (void)parserDidEndDocument:(CMParser *)parser;\n...\n- (void)parser:(CMParser *)parser foundText:(NSString *)text;\n- (void)parserFoundHRule:(CMParser *)parser;\n...\n@end\n```\n\n[`CMAttributedStringRenderer`](CocoaMarkdown/CMAttributedStringRenderer.h) is an example of a custom renderer that is built using this API.\n\n#### Rendering Attributed Strings\n\n[`CMAttributedStringRenderer`](CocoaMarkdown/CMAttributedStringRenderer.h) is the high level API that will be useful to most apps. It creates an `NSAttributedString` directly from Markdown, skipping the step of converting it to HTML altogether.\n\nGoing from a Markdown document to rendering it on screen is as easy as:\n\n```swift\nlet document = CMDocument(contentsOfFile: path, options: [])\nlet renderer = CMAttributedStringRenderer(document: document, attributes: CMTextAttributes())\ntextView.attributedText = renderer.render()\n```\n\nOr, using the convenience method on `CMDocument`:\n\n```swift\ntextView.attributedText = CMDocument(contentsOfFile: path, options: []).attributedStringWithAttributes(CMTextAttributes())\n```\n\nHTML elements can be supported by implementing [`CMHTMLElementTransformer`](CocoaMarkdown/CMHTMLElementTransformer.h). The framework includes several transformers for commonly used tags:\n\n* [`CMHTMLStrikethroughTransformer`](CocoaMarkdown/CMHTMLStrikethroughTransformer.h)\n* [`CMHTMLSuperscriptTransformer`](CocoaMarkdown/CMHTMLSuperscriptTransformer.h)\n* [`CMHTMLSubscriptTransformer`](CocoaMarkdown/CMHTMLSubscriptTransformer.h)\n\nTransformers can be registered with the renderer to use them:\n\n```swift\nlet document = CMDocument(contentsOfFile: path, options: [])\nlet renderer = CMAttributedStringRenderer(document: document, attributes: CMTextAttributes())\nrenderer.registerHTMLElementTransformer(CMHTMLStrikethroughTransformer())\nrenderer.registerHTMLElementTransformer(CMHTMLSuperscriptTransformer())\ntextView.attributedText = renderer.render()\n```\n\n#### Customizing Attributed strings rendering\n\nAll attributes used to style the text are customizable using the [`CMTextAttributes`](CocoaMarkdown/CMTextAttributes.h) class. \n\nEvery Markdown element type can be customized using the corresponding `CMStyleAttributes` property in `CMTextAttributes`, defining 3 different kinds of attributes:\n\n- String attributes, i.e. regular NSAttributedString attributes\n- Font attributes, for easy font setting \n- Paragraph attributes, relevant only for block elements\n\nAttributes for any Markdown element kind can be directly set:\n\n```swift\nlet textAttributes = CMTextAttributes()\ntextAttributes.linkAttributes.stringAttributes[NSAttributedString.Key.backgroundColor] = UIColor.yellow\n```\n\nA probably better alternative for style customization is to use grouped attributes setting methods available in `CMTextAttributes`:\n\n```swift\nlet textAttributes = CMTextAttributes()\n\n// Set the text color for all headers\ntextAttributes.addStringAttributes([ .foregroundColor: UIColor(red: 0.0, green: 0.446, blue: 0.657, alpha: 1.0)], \n                                   forElementWithKinds: .anyHeader)\n\n// Set a specific font + font-traits for all headers\nlet boldItalicTrait: UIFontDescriptor.SymbolicTraits = [.traitBold, .traitItalic]\ntextAttributes.addFontAttributes([ .family: \"Avenir Next\" ,\n                                   .traits: [ UIFontDescriptor.TraitKey.symbolic: boldItalicTrait.rawValue]], \n                                 forElementWithKinds: .anyHeader)\n// Set specific font traits for header1 and header2\ntextAttributes.setFontTraits([.weight: UIFont.Weight.heavy], \n                             forElementWithKinds: [.header1, .header2])\n\n// Center block-quote paragraphs        \ntextAttributes.addParagraphStyleAttributes([ .alignment: NSTextAlignment.center.rawValue], \n                                           forElementWithKinds: .blockQuote)\n\n// Set a background color for code elements        \ntextAttributes.addStringAttributes([ .backgroundColor: UIColor(white: 0.9, alpha: 0.5)], \n                                   forElementWithKinds: [.inlineCode, .codeBlock])\n```\n\nList styles can be customized using dedicated paragraph style attributes:\n\n```swift\n// Customize the list bullets\ntextAttributes.addParagraphStyleAttributes([ .listItemBulletString: \"🍏\" ], \n                                           forElementWithKinds: .unorderedList)\ntextAttributes.addParagraphStyleAttributes([ .listItemBulletString: \"🌼\" ], \n                                           forElementWithKinds: .unorderedSublist)\n\n// Customize numbered list item labels format and distance between label and paragraph\ntextAttributes.addParagraphStyleAttributes([ .listItemNumberFormat: \"(%02ld)\", \n                                             .listItemLabelIndent: 30 ],    \n                                           forElementWithKinds: .orderedList)\n\n```\n\nFont and paragraph attributes are incremental, meaning that they allow to modify only specific aspects of the default rendering styles.\n\nAdditionally on iOS, Markdown elements styled using the font attributes API get automatic Dynamic-Type compliance in the generated attributed string, just like default rendering styles.\n\n### Rendering HTML\n\n[`CMHTMLRenderer`](CocoaMarkdown/CMHTMLRenderer.h) provides the ability to render HTML from Markdown:\n\n```swift\nlet document = CMDocument(contentsOfFile: path, options: [])\nlet renderer = CMHTMLRenderer(document: document)\nlet HTML = renderer.render()\n```\n\nOr, using the convenience method on `CMDocument`:\n\n```swift\nlet HTML = CMDocument(contentsOfFile: path).HTMLString()\n```\n\n### Example Apps\n\nThe project includes example apps for iOS and macOS to demonstrate rendering attributed strings.\n\n### Contact\n\n* Indragie Karunaratne\n* [@indragie](http://twitter.com/indragie)\n* [http://indragie.com](http://indragie.com)\n\n### License\n\nCocoaMarkdown is licensed under the MIT License. See `LICENSE` for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findragiek%2FCocoaMarkdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findragiek%2FCocoaMarkdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findragiek%2FCocoaMarkdown/lists"}