You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Publish Swift Markdown's documentation to GitHub pages (#32)
* Adopt the Swift-DocC Plugin for documentation generation
* Add a script for publishing docs to GitHub pages
* Add missing license headers
* Move README docs to articles in the DocC catalog
* Remove out-of-date documentation about `DiagnosticEngine`
Swift markdown no longer includes a DiagnosticEngine so these links were failing
to resolve.
Parsing text is just one way to build a tree of `Markup` elements. You can also build them yourself declaratively.
42
-
43
-
## Building Markup Trees
44
-
45
-
You can build trees using initializers for the various element types provided.
46
-
47
-
```swift
48
-
importMarkdown
49
-
50
-
let document =Document(
51
-
Paragraph(
52
-
Text("This is a "),
53
-
Emphasis(
54
-
Text("paragraph."))))
55
-
```
56
-
57
-
This would be equivalent to parsing `"This is a *paragraph.*"` but allows you to programmatically insert content from other data sources into individual elements.
58
-
59
-
## Modifying Markup Trees with Persistence
60
-
61
-
Swift Markdown uses a [persistent](https://en.wikipedia.org/wiki/Persistent_data_structure) tree for its backing storage, providing effectively immutable, copy-on-write value types that only copy the substructure necessary to create a unique root without affecting the previous version of the tree.
62
-
63
-
### Modifying Elements Directly
64
-
65
-
If you just need to make a quick change, you can modify an element anywhere in a tree, and Swift Markdown will create copies of substructure that cannot be shared.
66
-
67
-
```swift
68
-
importMarkdown
69
-
70
-
let source ="This is *emphasized.*"
71
-
let document =Document(parsing: source)
72
-
print(document.debugDescription())
73
-
// Document
74
-
// └─ Paragraph
75
-
// ├─ Text "This is "
76
-
// └─ Emphasis
77
-
// └─ Text "emphasized."
78
-
79
-
var text = document.child(through:
80
-
0, // Paragraph
81
-
1, // Emphasis
82
-
0) as! Text // Text
83
-
84
-
text.string="really emphasized!"
85
-
print(text.root.debugDescription())
86
-
// Document
87
-
// └─ Paragraph
88
-
// ├─ Text "This is "
89
-
// └─ Emphasis
90
-
// └─ Text "really emphasized!"
91
-
92
-
// The original document is unchanged:
93
-
94
-
print(document.debugDescription())
95
-
// Document
96
-
// └─ Paragraph
97
-
// ├─ Text "This is "
98
-
// └─ Emphasis
99
-
// └─ Text "emphasized."
100
-
```
101
-
102
-
If you find yourself needing to systematically change many parts of a tree, or even provide a complete transformation into something else, maybe the familiar [Visitor Pattern](https://en.wikipedia.org/wiki/Visitor_pattern) is what you want.
103
-
104
-
## Visitors, Walkers, and Rewriters
105
-
106
-
There is a core `MarkupVisitor` protocol that provides the basis for transforming, walking, or rewriting a markup tree.
107
-
108
-
```swift
109
-
publicprotocolMarkupVisitor {
110
-
associatedtypeResult
111
-
}
112
-
```
113
-
114
-
Using its `Result` type, you can transform a markup tree into anything: another markup tree, or perhaps a tree of XML or HTML elements. There are two included refinements of `MarkupVisitor` for common uses.
115
-
116
-
The first refinement, `MarkupWalker`, has an associated `Result` type of `Void`, so it's meant for summarizing or detecting aspects of a markup tree. If you wanted to append to a string as elements are visited, this might be a good tool for that.
117
-
118
-
```swift
119
-
importMarkdown
120
-
121
-
/// Counts `Link`s in a `Document`.
122
-
structLinkCounter: MarkupWalker {
123
-
var count =0
124
-
mutatingfuncvisitLink(_link: Link) {
125
-
if link.destination =="https://swift.org" {
126
-
count +=1
127
-
}
128
-
descendInto(link)
129
-
}
130
-
}
131
-
132
-
let source ="There are [two](https://swift.org) links to <https://swift.org> here."
133
-
let document =Document(parsing: source)
134
-
print(document.debugDescription())
135
-
var linkCounter =LinkCounter()
136
-
linkCounter.visit(document)
137
-
print(linkCounter.count)
138
-
// 2
139
-
```
140
-
141
-
The second refinement, `MarkupRewriter`, has an associated `Result` type of `Markup?`, so it's meant to change or even remove elements from a markup tree. You can return `nil` to delete an element, or return another element to substitute in its place.
142
-
143
-
```swift
144
-
importMarkdown
145
-
146
-
/// Delete all **strong** elements in a markup tree.
Swift Markdown includes a syntax extension for attributed block elements. See [Block Directive](Documentation/BlockDirectives.md) documentation for more information.
39
+
Please see Swift `Markdown`'s [documentation site](https://apple.github.io/swift-markdown/documentation/markdown/)
40
+
for more detailed information about the library.
167
41
168
42
## Getting Involved
169
43
@@ -188,4 +62,4 @@ Swift Markdown can be improved to better meet your needs.
188
62
189
63
Please see the [contributing guide](https://swift.org/contributing/#contributing-code) for more information.
190
64
191
-
<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
65
+
<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
Copy file name to clipboardExpand all lines: Sources/Markdown/Markdown.docc/Markdown.md
+6-1Lines changed: 6 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,12 @@ The parser is powered by GitHub-flavored Markdown's [cmark-gfm](https://github.c
8
8
9
9
The markup tree provided by this package is comprised of immutable/persistent, thread-safe, copy-on-write value types that only copy substructure that has changed. Other examples of the main strategy behind this library can be seen in Swift's [lib/Syntax](https://github.com/apple/swift/tree/master/lib/Syntax) and its Swift bindings, [SwiftSyntax](https://github.com/apple/swift-syntax).
When parsing block directive syntax, Swift Markdown supplies an optional diagnostic infrastructure for reporting parsing problems to a user. See ``Diagnostic``, ``DiagnosticEngine``, and ``DiagnosticConsumer``.
156
-
157
-
Here is a simple case if you just want to collect diagnostics:
158
-
159
-
```swift
160
-
classDiagnosticCollector: DiagnosticConsumer {
161
-
var diagnostics = [Diagnostic]()
162
-
funcreceive(_diagnostic: Diagnostic) {
163
-
diagnostics.append(diagnostic)
164
-
}
165
-
}
166
-
167
-
let collector =DiagnosticCollector()
168
-
let diagnostics =DiagnosticEngine()
169
-
diagnostics.subscribe(collector)
170
-
171
-
let document =Document(parsing: source,
172
-
options: .parseBlockDirectives,
173
-
diagnostics: diagnostics)
174
-
175
-
for diagnostic in collector.diagnostics {
176
-
print(diagnostic)
177
-
}
178
-
```
155
+
When parsing block directive syntax, you can optionally provide an array of errors
156
+
to collect parsing problems and report them to a user. See ``DirectiveArgumentText/ParseError``.
179
157
180
158
<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
0 commit comments