Adopt Snippets in Swift Markdown

Package@swift-5.5.swift

@@ -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/CondenseAutolinks.swift

@@ -0,0 +1,29 @@
+// Format links that use URLs as their link text into autolinks.
+
+import Markdown
+
+let source = """
+This [https://swift.org](https://swift.org) link will become <https://swift.org>
+"""
+
+let document = Document(parsing: source)
+let formattingOptions = MarkupFormatter.Options(condenseAutolinks: true)
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/CustomLinePrefix.swift

@@ -0,0 +1,30 @@
+// Format a Markdown document to have a custom line prefix, such as a comment prefix for use in source code.
+
+import Markdown
+
+let source = """
+This document's lines
+will be prefixed with `//`.
+"""
+
+let document = Document(parsing: source)
+let formattingOptions = MarkupFormatter.Options(customLinePrefix: "// ")
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/DefaultFormatting.swift

@@ -0,0 +1,34 @@
+// Format Markdown with the default settings.
+
+import Markdown
+
+let source = """
+|a|b|c|
+|-|:-|-:|
+|*Some text*|x|<https://swift.org>|
+"""
+
+// There is not an option for formatting tables per se but is useful to show the behavior for tables.
+// Table columns are automatically expanded to fit the column's largest
+// cell, making the table easier to read in the Markdown source.
+
+let document = Document(parsing: source)
+let formattedSource = document.format()
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/EmphasisMarkers.swift

@@ -0,0 +1,30 @@
+// Format a consistent style for emphasis markers.
+
+import Markdown
+
+let source = """
+This document uses a mix of *star* and _underbar_ emphasized elements.
+"""
+
+let document = Document(parsing: source)
+// Use only * for emphasis markers.
+let emphasisMarker = MarkupFormatter.Options.EmphasisMarker.star
+let formattedSource = document.format(options: .init(emphasisMarker: emphasisMarker))
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/MaximumWidth.swift

@@ -0,0 +1,31 @@
+// Format lines to stay 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)
+// Break lines longer than 80 characters in width with a soft break.
+let lineLimit = MarkupFormatter.Options.PreferredLineLimit(maxLength: 80, breakWith: .softBreak)
+let formattingOptions = MarkupFormatter.Options(preferredLineLimit: lineLimit)
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/OrderedListNumerals.swift

@@ -0,0 +1,32 @@
+// Format the counting behavior of ordered lists.
+
+import Markdown
+
+let source = """
+1. An
+2. ordered
+3. list
+"""
+
+let document = Document(parsing: source)
+// Use all 0. markers to allow easily reordering ordered list items.
+let formattingOptions = MarkupFormatter.Options(orderedListNumerals: .allSame(1))
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/PreferredHeadingStyle.swift

@@ -0,0 +1,37 @@
+// Format a Markdown document to use ATX style headings throughout.
+
+import Markdown
+
+let source = """
+# Title
+
+## Second-level Heading
+
+Another Second-level Heading
+----------------------------
+
+The above heading will be converted to ATX style, using hashes.
+"""
+
+let document = Document(parsing: source)
+let headingStyle = MarkupFormatter.Options.PreferredHeadingStyle.atx
+let formattingOptions = MarkupFormatter.Options(preferredHeadingStyle: headingStyle)
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/ThematicBreakCharacter.swift

@@ -0,0 +1,37 @@
+// Format a consistent style for thematic breaks.
+
+import Markdown
+
+let source = """
+First paragraph.
+
+-----
+
+Second paragraph.
+
+*****
+"""
+
+let document = Document(parsing: source)
+let thematicBreakCharacter = MarkupFormatter.Options.ThematicBreakCharacter.dash
+// Make all thematic breaks 10 dash `-` characters.
+let formattingOptions = MarkupFormatter.Options(thematicBreakCharacter: thematicBreakCharacter, thematicBreakLength: 10)
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/UnorderedListMarker.swift

@@ -0,0 +1,31 @@
+// Format the unordered list marker.
+
+import Markdown
+
+let source = """
+- An
+- unordered
+- list
+"""
+
+let document = Document(parsing: source)
+// Use an star or asterisk `*` as the unordered list marker.
+let formattedSource = document.format(options: .init(unorderedListMarker: .star))
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Formatting/UseCodeFence.swift

@@ -0,0 +1,40 @@
+// Format all code blocks to use a consistent style for code blocks,
+// optionally setting the default info string to declare that they
+// have a particular syntax.
+
+import Markdown
+
+let source = """
+This document contains a mix of indented and fenced code blocks.
+
+    A code block.
+
+```
+func foo() {}
+```
+"""
+
+let document = Document(parsing: source)
+// Always fenced code blocks.
+let fencedCodeBlock = MarkupFormatter.Options.UseCodeFence.always
+// Use `swift` as the info string on all fenced code blocks.
+let defaultCodeBlockLanguage = "swift"
+let formattedSource = document.format(options: .init(useCodeFence: fencedCodeBlock, defaultCodeBlockLanguage: defaultCodeBlockLanguage))
+
+print("""
+## Original source:
+\(source)
+
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Parsing/ParseDocumentFile.swift

@@ -0,0 +1,21 @@
+// Parse the contents of a file by its ``URL`` without having to read its contents yourself.
+
+import Foundation
+import Markdown
+
+// snippet.hide
+let inputFileURL = URL(fileURLWithPath: #file).deletingLastPathComponent().appendingPathComponent("test.md")
+// snippet.show
+let document = try Document(parsing: inputFileURL)
+
+print(document.debugDescription())
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Parsing/ParseDocumentString.swift

@@ -0,0 +1,18 @@
+// Parse a ``String`` as Markdown.
+
+import Markdown
+
+let source = "Some *Markdown* source"
+let document = Document(parsing: source)
+
+print(document.debugDescription())
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/

Snippets/Parsing/test.md

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