Support collapsible blocks for Kramdown rendered pages

eneko · Oct 27, 2017 · f135a97 · f135a97
1 parent 0a01980
commit f135a97
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,18 @@
 ## Master
 
-### Changes
+### Enhancements
+- None
+
+### Fixes
 - None
 
 
+## 0.3.0
+
+### Enhancements
+- Add support for collapsible blocks on GitHub.com and rendered GitHub Pages.
+
+
 ## 0.2.1
 
 ### Fixes
@@ -31,3 +40,4 @@
 
 ## 0.1.0
 - Initial Release
+
diff --git a/Sources/MarkdownGenerator/MarkdownCollapsibleSection.swift b/Sources/MarkdownGenerator/MarkdownCollapsibleSection.swift
@@ -7,10 +7,29 @@
 
 import Foundation
 
+/// Collapsible blocks are a great way to hide large portions of content
+/// that, while valuable to the reader, would result on a lot of noise.
+///
+/// Collapsible blocks work well in most Markdown readers, including
+/// GitHub.com and rendered GitHub Pages. However, because they rely on
+/// HTML tags, they will make the _raw_ markdown output harder to read.
+///
+/// ```html
+/// <details><summary>Block Title</summary>
+///
+///     Block details.
+///
+/// </details>
+/// ```
 public struct MarkdownCollapsibleSection: MarkdownConvertible {
     let summary: String
     let details: MarkdownConvertible
 
+    /// MarkdownCollapsibleSection initializer
+    ///
+    /// - Parameters:
+    ///   - summary: Plain text or HTML string containing the block title.
+    ///   - details: Markdown convertible elements to include in the collapsible block.
     public init(summary: String, details: MarkdownConvertible) {
         self.summary = summary
         self.details = details
@@ -19,9 +38,10 @@ public struct MarkdownCollapsibleSection: MarkdownConvertible {
     /// Generated Markdown output
     public var markdown: String {
         return """
-        <details><summary>\(summary)</summary>
+        <details><summary markdown="span">\(summary)</summary>
 
         \(details.markdown)
+
         </details>
         """
     }

diff --git a/Tests/MarkdownGeneratorTests/MarkdownCollapsibleSectionTests.swift b/Tests/MarkdownGeneratorTests/MarkdownCollapsibleSectionTests.swift
@@ -12,17 +12,18 @@ class MarkdownCollapsibleSectionTests: XCTestCase {
 
     func testSimple() {
         let output = """
-        <details><summary>Hello</summary>
+        <details><summary markdown="span">Hello</summary>
 
         World
+
         </details>
         """
         XCTAssertEqual(MarkdownCollapsibleSection(summary: "Hello", details: "World").markdown, output)
     }
 
     func testComplex() {
         let output = """
-        <details><summary>This is cool stuff</summary>
+        <details><summary markdown="span">This is cool stuff</summary>
 
         # Title
 
@@ -38,6 +39,7 @@ class MarkdownCollapsibleSectionTests: XCTestCase {
         ```swift
         let foo = Bar()
         ```
+
         </details>
         """