Ink/README.md at master · JohnSundell/Ink · GitHub
Welcome to Ink, a quick and versatile Markdown parser written in Swift. It can be utilized to transform Markdown-formatted strings into HTML, and in addition helps metadata parsing, in addition to tough customization choices for fine-grained post-processing. It used to be constructed with a focal point on Swift-based internet construction and different HTML-centered workflows.
Ink is used to render all articles on swiftbysundell.com.
Converting Markdown into HTML
To get began with Ink, all you must do is to import it, and use its
MarkdownParser sort to transform any Markdown string into successfully rendered HTML:
import Ink let markdown: String = ... let parser = MarkdownParser() let html = parser.html(from: markdown)
That’s it! The ensuing HTML can then be displayed as-is, or embedded into another context — and if that’s all you want Ink for, then not more code is needed.
Automatic metadata parsing
Ink additionally comes with metadata make stronger integrated, that means that you’ll be able to outline key/worth pairs at the highest of any Markdown file, which can then be robotically parsed right into a Swift dictionary.
To benefit from that characteristic, name the
parse approach on
MarkdownParser, which will give you a
Markdown worth that each incorporates any metadata discovered inside the parsed Markdown string, in addition to its HTML illustration:
let markdown: String = ... let parser = MarkdownParser() let end result = parser.parse(markdown) let dateString = end result.metadata["date"] let html = end result.html
To outline metadata values inside of a Markdown file, use the next syntax:
--- keyA: valueA keyB: valueB --- Markdown textual content...
The above structure could also be supported via many alternative Markdown editors and different gear, even if it’s no longer a part of the authentic Markdown spec.
Besides its integrated parsing regulations, which goals to hide the most typical options discovered within the more than a few flavors of Markdown, you’ll be able to additionally customise how Ink plays its parsing via using modifiers.
A modifier is outlined the use of the
Modifier sort, and is related to a given
Target, which determines the type of Markdown fragments that it is going to be used for. For instance, right here’s how an H3 tag may well be added ahead of every code block:
var parser = MarkdownParser() let modifier = Modifier(goal: .codeBlocks) html, markdown in go back "<h3>This is a code block:</h3>" + html parser.uploadModifier(modifier) let markdown: String = ... let html = parser.html(from: markdown)
Modifiers are handed each the HTML that Ink generated for the given fragment, and its uncooked Markdown illustration as smartly — either one of which can be utilized to resolve how every fragment will have to be custom designed.
Ink used to be designed to be as speedy and environment friendly as conceivable, to permit masses of full-length Markdown articles to be parsed in a question of seconds, whilst nonetheless providing a completely customizable API as smartly. Two key traits make this conceivable:
- Ink goals to get as with reference to
O(N)complexity as conceivable, via minimizing the quantity of occasions it must learn the Markdown strings which are handed to it, and via optimizing its HTML rendering to be utterly linear. While true
O(N)complexity is not possible to reach in the case of Markdown parsing, on account of its very versatile syntax, the objective is to come back as with reference to that focus on as conceivable.
- A top level of reminiscence potency is completed because of Swift’s tough
StringAPI, which Ink makes complete use of — via the use of string indexes, levels and substrings, quite than acting useless string copying between its more than a few operations.
Ink is sent the use of the Swift Package Manager. To set up it right into a undertaking, merely upload it as a dependency inside of your
let package deal = Package( ... dependencies: [ .package deal(url: "https://github.com/johnsundell/ink.git", from: "zero.1.zero") ], ... )
Then import Ink anywhere you’d like to make use of it:
Command line device
Ink additionally ships with a easy however helpful command line device that allows you to use it to transform Markdown to HTML immediately from the command line.
To set up it, clone the undertaking and run
$ git clone https://github.com/johnsundell/Ink.git $ cd Ink $ make
The command line device will probably be put in as
ink, and will also be known as with any Markdown string to transform it into HTML:
$ ink "$(cat README.md)"
You can in fact additionally construct your individual command line gear that makes use of Ink in additional complicated techniques via uploading it as a package deal.
Markdown syntax supported
Ink helps the next Markdown options:
- Headings (H1 – H6), the use of main pound indicators, as an example
- Italic textual content, via surrounding a work of textual content with both an asterisk (
*), or an underscore (
_). For instance
*Italic textual content*.
- Bold textual content, via surrounding a work of textual content with both two asterisks (
**), or two underscores (
__). For instance
**Bold textual content**.
- Text strikethrough, via surrounding a work of textual content with two tildes (
~~), as an example
~~Strikethrough textual content~~.
- Inline code, marked with a backtick on both website of the code.
- Code blocks, marked with 3 backticks each above and underneath the block.
- Links, the use of the next syntax:
- Images, the use of the next syntax:
- Both pictures and hyperlinks too can use reference URLs, which will also be outlined any place in a Markdown file the use of this syntax:
- Both ordered lists (the use of numbers) and unordered lists (the use of both a splash (
-), or an asterisk (
*) as bullets) are supported.
- Nested lists are supported as smartly, via indenting any a part of a listing that are supposed to be nested inside of its father or mother.
- Horizontal traces will also be positioned the use of both 3 asterisks (
***) or 3 dashes (
---) on a brand new line.
- HTML will also be inlined each at the basis stage, and inside of textual content paragraphs.
- Blockquotes will also be created via putting a greater-than arrow at the beginning of a line, like this:
> This is a blockquote.
Please observe that, being an excessively younger implementation, Ink does no longer totally make stronger all Markdown specifications, comparable to CommonMark. Ink unquestionably goals to hide as a lot flooring as conceivable, and to incorporate make stronger for probably the most regularly used Markdown options, but when entire CommonMark compatibility is what you’re in search of — then you may want to try gear like CMark.
Ink makes use of a extremely modular rule-based inner structure, to permit new regulations and formatting choices to be added with out impacting the device as a complete.
Each Markdown fragment is in my view parsed and rendered via a kind conforming to the inner
HTMLConvertible protocols — comparable to
To parse part of a Markdown file, every fragment sort makes use of a
Reader example to learn the Markdown string, and to make assertions about its construction. Errors are used as keep watch over glide to sign whether or not a parsing operation used to be a success or no longer, which in flip allows the father or mother context to come to a decision whether or not to advance the present
Reader example, or whether or not to rewind it.
A excellent position to start out exploring Ink’s implementation is to seem at the principle
parse approach, and to then dive deeper into the more than a few
Fragment implementations, and the
Ink used to be in the beginning written via John Sundell as a part of the Publish suite of static website era gear, which is used to construct and generate Swift via Sundell. The different gear that make up the Publish suite may also be open sourced quickly.
Contributions and make stronger
Ink is advanced utterly within the open, and your contributions are greater than welcome.
Before you get started the use of Ink in any of your tasks, it’s extremely really useful that you simply spend a couple of mins familiarizing your self with its documentation and inner implementation, in order that you’ll be in a position to take on any problems or edge circumstances that you may come upon.
Since it is a very younger undertaking, it’s prone to have many barriers and lacking options, which is one thing that may in reality best be came upon and addressed as extra folks get started the use of it. While Ink is utilized in manufacturing to render all of Swift via Sundell, it’s really useful that you simply first test it out in your particular use case, to ensure it helps the options that you want.
This undertaking does no longer include GitHub Issues-based make stronger, and customers are as an alternative inspired to turn out to be lively contributors in its endured construction — via solving any insects that they come upon, or via making improvements to the documentation anywhere it’s discovered to be missing.
If you need to make a transformation, open a Pull Request — even supposing it simply incorporates a draft of the adjustments you’re making plans, or a check that reproduces a topic — and we will be able to speak about it farther from there.
Hope you’ll revel in the use of Ink!