Example usage of snippets for Swift Evolution

Author: bitjammer

[email protected]

@@ -58,7 +58,7 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
     // SwiftPM command plugins are only supported by Swift version 5.6 and later.
     #if swift(>=5.6)
     package.dependencies += [
-        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", .branch("main")),
     ]
     #endif
 } else {

Snippets/Formatting/DefaultFormatting.swift

@@ -0,0 +1,28 @@
+//! Format a parsed Markdown document with default settings.
+
+import Markdown
+
+let source = """
+|a|b|c|
+|-|-|-|
+|*Some text*||<https://swift.org>|
+"""
+
+let document = Document(parsing: source)
+let formattedSource = document.format()
+
+// MARK: Hide
+
+print("""
+## Original source:
+```
+\(source)
+```
+""")
+
+print("""
+## Formatted source:
+```
+\(formattedSource)
+```
+""")

Snippets/Formatting/MaximumWidth.swift

@@ -0,0 +1,25 @@
+//! Keep lines under a certain length.
+import Markdown
+
+let source = """
+This is a really, really, really, really, really, really, really, really, really, really, really long line.
+"""
+
+let document = Document(parsing: source)
+let lineLimit = MarkupFormatter.Options.PreferredLineLimit(maxLength: 80, breakWith: .softBreak)
+let formattingOptions = MarkupFormatter.Options(preferredLineLimit: lineLimit)
+let newSource = document.format(options: formattingOptions)
+
+// MARK: Hide
+
+print("## Original source:")
+print("```")
+print(source)
+print("```")
+print()
+
+print("## Formatted source:")
+print("```")
+print(newSource)
+print("```")
+print()

Snippets/Parsing/ParseDocumentFile.swift

@@ -0,0 +1,14 @@
+//! Parse the contents of a file by its ``URL`` without having to read
+//! its contents yourself.
+
+import Foundation
+import Markdown
+
+let file = URL(fileURLWithPath: "test.md")
+let document = try Document(parsing: file)
+
+// MARK: HIDE
+
+print("Parsed \(file.path)")
+print("## Parsed document structure")
+print(document.debugDescription())

Snippets/Parsing/ParseDocumentString.swift

@@ -0,0 +1,12 @@
+//! Parse a ``String`` as Markdown
+
+import Markdown
+
+let source = "Some *Markdown* source"
+let document = Document(parsing: source)
+
+// MARK: HIDE
+
+print("Parsed \(source.debugDescription)")
+print("## Parsed document structure")
+print(document.debugDescription())

Snippets/Parsing/test.md

@@ -0,0 +1,3 @@
+# Sample document
+
+This is a *sample document*.

Snippets/Rewriters/RemoveElementKind.swift

@@ -0,0 +1,41 @@
+//! Remove all instances of a kind of element using a `MarkupRewriter`.
+import Markdown
+
+// MARK: Hide
+
+let source = """
+The strong emphasis element is **going to be** deleted.
+"""
+
+// MARK: Show
+
+struct StrongDeleter: MarkupRewriter {
+  func visitStrong(_ strong: Strong) -> Markup? {
+    return nil
+  }
+}
+
+let document = Document(parsing: source)
+var deleter = StrongDeleter()
+let newDocument = deleter.visit(document) as! Document
+
+// MARK: Hide
+
+print("## Original source:")
+print("```")
+print(source)
+print("```")
+print()
+
+print("## Original Markdown tree:")
+print(document.debugDescription())
+print()
+
+print("## New Markdown tree:")
+print(newDocument.debugDescription())
+print()
+
+print("## New source:")
+print("```")
+print(newDocument.format())
+print("```")

Sources/Markdown/Markdown.docc/Markdown.md

@@ -10,6 +10,10 @@ The markup tree provided by this package is comprised of immutable/persistent, t
 
 ## Topics
 
+### Snippets
+
+- <doc:snippets>
+
 ### Getting Started
 
 - <doc:Parsing-Building-and-Modifying-Markup-Trees>

Sources/Markdown/Markdown.docc/snippets.md

@@ -0,0 +1,15 @@
+# Snippets
+
+## Parsing
+
+@Snippet(path: "swift-markdown/snippets/ParseDocumentString")
+@Snippet(path: "swift-markdown/snippets/ParseDocumentFile")
+
+## Formatting
+
+@Snippet(path: "swift-markdown/snippets/DefaultFormatting"
+@Snippet(path: "swift-markdown/snippets/MaximumWidth")
+
+## Rewriters
+
+@Snippet(path: "swift-markdown/snippets/RemoveElementKind")