feat: Added support for code fence titles

Author: kevinrenskers

README.md

@@ -36,6 +36,38 @@ Parsley is available via Swift Package Manager and runs on macOS and Linux.
 Parsley can be used as a reader in the static site generator [Saga](https://github.com/loopwerk/Saga), using [SagaParsleyMarkdownReader](https://github.com/loopwerk/SagaParsleyMarkdownReader).
 
 
+## Code block titles
+Parsley supports adding a title (typically a filename) to fenced code blocks using the `title="..."` syntax:
+
+~~~markdown
+```python title="views.py"
+def hello():
+    print("Hello, World!")
+```
+~~~
+
+This generates HTML with a `data-title` attribute on the `<pre>` element:
+
+```html
+<pre data-title="views.py"><code class="language-python">def hello():
+    print("Hello, World!")
+</code></pre>
+```
+
+You can then use CSS to display the title, for example:
+
+```css
+pre[data-title]::before {
+  content: attr(data-title);
+  display: block;
+  background: #1a1a1a;
+  padding: 0.5em 1em;
+  font-size: 0.85em;
+  border-bottom: 1px solid #333;
+}
+```
+
+
 ## Modifying the generated HTML
 Parsley doesn't come with a plugin system, it relies purely on `cmark-gfm` under the hood to render Markdown to HTML. If you want to modify the generated HTML, for example if you want to add `target="blank"` to all external links, [SwiftSoup](https://github.com/scinfu/SwiftSoup) is a great way to achieve this.
 

Sources/Parsley/Parsley.swift

@@ -22,16 +22,19 @@ public struct Parsley {
       cmark_parser_attach_syntax_extension(parser, syntaxExtension.createPointer())
     }
 
+    // Pre-process markdown to extract title from code fence info
+    let processedContent = preprocessCodeBlockTitles(content)
+
     // Parse into an ast
-    content.withCString {
+    processedContent.withCString {
       let stringLength = Int(strlen($0))
       cmark_parser_feed(parser, $0, stringLength)
     }
-    
+
     guard let ast = cmark_parser_finish(parser) else {
       throw MarkdownError.conversionFailed
     }
-    
+
     // Render the ast into an html string
     guard let htmlCString = cmark_render_html(&ast.pointee, options.rawValue, parser.pointee.syntax_extensions) else {
       throw MarkdownError.conversionFailed
@@ -51,7 +54,8 @@ public struct Parsley {
       throw MarkdownError.conversionFailed
     }
 
-    return html
+    // Post-process HTML to convert code-title comments to data-title attributes
+    return processCodeTitleComments(html)
   }
 
   /// This parses a String into a Document, which contains parsed Metadata and the document title.
@@ -74,6 +78,32 @@ public struct Parsley {
 }
 
 private extension Parsley {
+  /// Pre-processes markdown to extract title from code fence info.
+  /// Transforms: ```python title="views.py"  →  ```python
+  ///                                             <!--code-title:views.py-->
+  static func preprocessCodeBlockTitles(_ markdown: String) -> String {
+    let pattern = #"```(\S+)\s+title="([^"]+)"\n"#
+    guard let regex = try? NSRegularExpression(pattern: pattern) else { return markdown }
+    return regex.stringByReplacingMatches(
+      in: markdown,
+      range: NSRange(markdown.startIndex..., in: markdown),
+      withTemplate: "```$1\n<!--code-title:$2-->\n"
+    )
+  }
+
+  /// Converts code-title comment markers in HTML to data-title attributes on pre tags.
+  /// Transforms: <pre><code class="language-xxx">&lt;!--code-title:filename--&gt;\n
+  /// Into: <pre data-title="filename"><code class="language-xxx">
+  static func processCodeTitleComments(_ html: String) -> String {
+    let pattern = #"<pre><code([^>]*)>&lt;!--code-title:([^-]+)--&gt;\n"#
+    guard let regex = try? NSRegularExpression(pattern: pattern) else { return html }
+    return regex.stringByReplacingMatches(
+      in: html,
+      range: NSRange(html.startIndex..., in: html),
+      withTemplate: #"<pre data-title="$2"><code$1>"#
+    )
+  }
+
   /// Turns a string like `author: Kevin\ntags: Swift` into a dictionary:
   /// ["author": "Kevin", "tags": "Swift"]
   static func metadata(from content: String?) -> [String: String] {

Tests/ParsleyTests/ParsleyTests.swift

@@ -149,6 +149,55 @@ let markdown = try Parsley.parse(input)
     XCTAssertEqual(markdown.metadata, [:])
   }
 
+  func testFencedCodeBlockWithTitle() throws {
+    let input = """
+```python title="views.py"
+def test():
+    pass
+```
+"""
+    let expectedOutput = """
+<pre data-title="views.py"><code class="language-python">def test():
+    pass
+</code></pre>
+"""
+
+    let markdown = try Parsley.parse(input)
+    XCTAssertEqual(markdown.body, expectedOutput)
+  }
+
+  func testFencedCodeBlockWithTitleAndPath() throws {
+    let input = """
+```ts title="lib/store.js"
+function test() {}
+```
+"""
+    let expectedOutput = """
+<pre data-title="lib/store.js"><code class="language-ts">function test() {}
+</code></pre>
+"""
+
+    let markdown = try Parsley.parse(input)
+    XCTAssertEqual(markdown.body, expectedOutput)
+  }
+
+  func testFencedCodeBlockWithoutTitle() throws {
+    let input = """
+```python
+def test():
+    pass
+```
+"""
+    let expectedOutput = """
+<pre><code class="language-python">def test():
+    pass
+</code></pre>
+"""
+
+    let markdown = try Parsley.parse(input)
+    XCTAssertEqual(markdown.body, expectedOutput)
+  }
+
   func testSmartQuotesOff() throws {
     let input = """
 "test"
@@ -203,6 +252,9 @@ let markdown = try Parsley.parse(input)
     ("testTitleAndMetadataNewline", testTitleAndMetadataNewline),
     ("testOtherFeatures", testOtherFeatures),
     ("testFencedCodeBlock", testFencedCodeBlock),
+    ("testFencedCodeBlockWithTitle", testFencedCodeBlockWithTitle),
+    ("testFencedCodeBlockWithTitleAndPath", testFencedCodeBlockWithTitleAndPath),
+    ("testFencedCodeBlockWithoutTitle", testFencedCodeBlockWithoutTitle),
     ("testSmartQuotesOff", testSmartQuotesOff),
     ("testSmartQuotesOn", testSmartQuotesOn),
     ("testSafe", testSafe),