Adopt more snippets

Add snippets for the following areas:

- Parsing
- Querying
- Walkers, Rewriters, and Visitors
- Formatting

Add a link to the top-level page.

Add an article which inlines all of the snippets in one place for quick reference.

rdar://103054461

Author: bitjammer

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

@@ -1,28 +1,34 @@
-// Format a parsed Markdown document with default settings.
+// Format Markdown with the default settings.
 
 import Markdown
 
 let source = """
 |a|b|c|
-|-|-|-|
-|*Some text*||<https://swift.org>|
+|-|:-|-:|
+|*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()
 
-// MARK: Hide
-
 print("""
 ## Original source:
-```
 \(source)
-```
-""")
 
-print("""
 ## 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

@@ -1,25 +1,31 @@
-// Keep lines under a certain length.
+// 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 newSource = document.format(options: formattingOptions)
+let formattedSource = document.format(options: formattingOptions)
+
+print("""
+## Original source:
+\(source)
 
-// MARK: Hide
+## Formatted source:
+\(formattedSource)
+""")
+// snippet.hide
+/*
+ This source file is part of the Swift.org open source project
 
-print("## Original source:")
-print("```")
-print(source)
-print("```")
-print()
+ Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
 
-print("## Formatted source:")
-print("```")
-print(newSource)
-print("```")
-print()
+ 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

@@ -3,11 +3,19 @@
 import Foundation
 import Markdown
 
-let file = URL(fileURLWithPath: "test.md")
-let document = try Document(parsing: file)
+// snippet.hide
+let inputFileURL = URL(fileURLWithPath: #file).deletingLastPathComponent().appendingPathComponent("test.md")
+// snippet.show
+let document = try Document(parsing: inputFileURL)
 
-// MARK: HIDE
-
-print("Parsed \(file.path)")
-print("## Parsed document structure")
 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
+*/