Add support for indented HTML blocks. (#33)

Author: samuel-williams-shopify

cmarkly

@@ -210,6 +210,42 @@ Without the flag, the prefix remains ordinary text. Inline code information is
 a single language token; richer code-block information belongs on a fenced code
 block instead.
 
+### HTML Block Blank Lines
+
+CommonMark ends type 6 and 7 HTML blocks at the first blank line. This can be
+surprising when a large HTML fragment is formatted with blank lines between
+consistently indented child elements: the following child is parsed as Markdown,
+often as an indented code block.
+
+`Markly::HTML_BLOCK_BLANK_LINES` allows those HTML blocks to continue across blank
+lines when their content establishes and preserves indentation:
+
+``` ruby
+markdown = <<~MARKDOWN
+	<div class="diagram">
+		<div class="request">GET /slides</div>
+
+		<div class="response">200 OK</div>
+	</div>
+MARKDOWN
+
+Markly.render_html(
+	markdown,
+	parse_flags: Markly::HTML_BLOCK_BLANK_LINES,
+	render_flags: Markly::UNSAFE,
+)
+```
+
+The indentation may be established after an initial blank line. Once
+established, the first nonblank line with less indentation ends the HTML block.
+This keeps the extension deterministic without attempting to match or interpret
+HTML tags.
+
+This option deliberately changes CommonMark parsing and is disabled by default.
+Use it for trusted, author-written documents where multiline HTML is a supported
+part of the Markdown dialect. `Markly::UNSAFE` is still required when rendering
+the resulting raw HTML.
+
 ### Code Block Metadata
 
 `Node#code_info` is the general information-string accessor for fenced code

context/extensions.md

@@ -45,6 +45,7 @@ Markly accepts integer flags which control how the Markdown is parsed and render
 | `Markly::FRONT_MATTER`               | Parse front matter at the start of the document.
 | `Markly::FOOTNOTES`                  | Parse footnotes.
 | `Markly::INLINE_CODE_INFO`           | Parse language prefixes such as `ruby:` on inline code spans.
+| `Markly::HTML_BLOCK_BLANK_LINES`     | Allow consistently indented HTML content to continue across blank lines.
 | `Markly::LIBERAL_HTML_TAG`           | Support liberal parsing of inline HTML tags.
 | `Markly::SMART`                      | Use smart punctuation (curly quotes, etc.).
 | `Markly::STRIKETHROUGH_DOUBLE_TILDE` | Parse strikethroughs by double tildes (compatibility with [redcarpet](https://github.com/vmg/redcarpet))

context/getting-started.md

@@ -91,8 +91,8 @@ static CMARK_INLINE bool S_ends_on_current_line(cmark_parser *parser, cmark_node
          // similar to fenced code blocks.
          // Types 6-7 end at a blank line, so their last content line is
          // the previous line and they should NOT match here.
-         (S_type(b) == CMARK_NODE_HTML_BLOCK && b->as.html_block_type >= 1 &&
-          b->as.html_block_type <= 5) ||
+         (S_type(b) == CMARK_NODE_HTML_BLOCK && b->as.html_block.type >= 1 &&
+          b->as.html_block.type <= 5) ||
          // Single-line blocks: finalized on same line they started
          b->start_line == parser->line_number;
 }
@@ -1037,7 +1037,7 @@ static bool parse_code_block_prefix(cmark_parser *parser, cmark_chunk *input,
 static bool parse_html_block_prefix(cmark_parser *parser,
                                     cmark_node *container) {
   bool res = false;
-  int html_block_type = container->as.html_block_type;
+  int html_block_type = container->as.html_block.type;
 
   assert(html_block_type >= 1 && html_block_type <= 7);
   switch (html_block_type) {
@@ -1051,7 +1051,32 @@ static bool parse_html_block_prefix(cmark_parser *parser,
     break;
   case 6:
   case 7:
-    res = !parser->blank;
+    if (!(parser->options & CMARK_OPT_HTML_BLOCK_BLANK_LINES)) {
+      res = !parser->blank;
+    } else if (parser->blank) {
+      // Tentatively retain blank lines. The next nonblank line determines
+      // whether the HTML block continues:
+      res = true;
+    } else if (S_last_line_blank(container)) {
+      // Establish the content indentation lazily so a blank line may follow
+      // the opening tag. A non-indented line still terminates the block:
+      if (container->as.html_block.indent == 0 && parser->indent > 0) {
+        container->as.html_block.indent = parser->indent;
+      }
+
+      res = container->as.html_block.indent > 0 &&
+            parser->indent >= container->as.html_block.indent;
+    } else {
+      // Record the shallowest positive content indentation before a blank
+      // line. Deeper nested HTML may then continue without changing it:
+      if (parser->indent > 0 &&
+          (container->as.html_block.indent == 0 ||
+           parser->indent < container->as.html_block.indent)) {
+        container->as.html_block.indent = parser->indent;
+      }
+
+      res = true;
+    }
     break;
   }
 
@@ -1224,7 +1249,7 @@ static void open_new_blocks(cmark_parser *parser, cmark_node **container,
                                    input, parser->first_nonspace))))) {
       *container = add_child(parser, *container, CMARK_NODE_HTML_BLOCK,
                              parser->first_nonspace + 1);
-      (*container)->as.html_block_type = matched;
+      (*container)->as.html_block.type = matched;
       // note, we don't adjust parser->offset because the tag is part of the
       // text
     } else if (!indented && cont_type == CMARK_NODE_PARAGRAPH &&
@@ -1421,7 +1446,7 @@ static void add_text_to_container(cmark_parser *parser, cmark_node *container,
       add_line(container, input, parser);
 
       int matches_end_condition;
-      switch (container->as.html_block_type) {
+      switch (container->as.html_block.type) {
       case 1:
         // </script>, </style>, </pre>
         matches_end_condition =

ext/markly/blocks.c

@@ -798,6 +798,12 @@ char *cmark_render_latex_with_mem(cmark_node *root, int options, int width, cmar
  */
 #define CMARK_OPT_INLINE_CODE_INFO (1 << 19)
 
+/** Allow indented content in type 6 and 7 HTML blocks to continue across
+ * blank lines. The indentation established by the HTML content must be
+ * preserved after each blank line.
+ */
+#define CMARK_OPT_HTML_BLOCK_BLANK_LINES (1 << 20)
+
 /**
  * ## Version information
  */

ext/markly/cmark-gfm.h

@@ -33,6 +33,11 @@ typedef struct {
   int8_t fenced;
 } cmark_code;
 
+typedef struct {
+  int type;
+  int indent;
+} cmark_html_block;
+
 typedef struct {
   int level;
   bool setext;
@@ -104,7 +109,7 @@ struct cmark_node {
     cmark_heading heading;
     cmark_link link;
     cmark_custom custom;
-    int html_block_type;
+    cmark_html_block html_block;
     int cell_index; // For keeping track of TABLE_CELL table alignments
     void *opaque;
   } as;

ext/markly/node.h

@@ -25,10 +25,13 @@ module Markly
 	FRONT_MATTER = 1 << 18
 	# Parse language prefixes on inline code spans, e.g. ruby:`Object.new`.
 	INLINE_CODE_INFO = 1 << 19
+	# Allow consistently indented HTML content to continue across blank lines.
+	HTML_BLOCK_BLANK_LINES = 1 << 20
 
 	PARSE_FLAGS = {
 		front_matter: FRONT_MATTER,
 		inline_code_info: INLINE_CODE_INFO,
+		html_block_blank_lines: HTML_BLOCK_BLANK_LINES,
 		validate_utf8: VALIDATE_UTF8,
 		smart_quotes: SMART,
 		liberal_html_tags: LIBERAL_HTML_TAG,

lib/markly/flags.rb

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add `Markly::HTML_BLOCK_BLANK_LINES` for keeping consistently indented HTML content together across blank lines.
+
 ## v0.18.0
 
   - Preserve complete node and extension metadata when duplicating node trees.

releases.md

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "markly"
+
+describe Markly::HTML_BLOCK_BLANK_LINES do
+	let(:flags) {Markly::HTML_BLOCK_BLANK_LINES}
+	
+	it "preserves CommonMark behavior by default" do
+		markdown = "<div>\n\t<p>one</p>\n\n\t<p>two</p>\n</div>\n"
+		document = Markly.parse(markdown)
+		
+		expect(document.first_child.type).to be == :html
+		expect(document.first_child.next).not.to be_nil
+	end
+	
+	it "keeps consistently indented HTML together across blank lines" do
+		markdown = "<div>\n\t<p>one</p>\n\n    <p>two</p>\n</div>\n"
+		document = Markly.parse(markdown, flags: flags)
+		
+		expect(document.first_child.type).to be == :html
+		expect(document.first_child.string_content).to be == markdown
+		expect(document.first_child.next).to be_nil
+	end
+	
+	it "can establish indentation after an initial blank line" do
+		markdown = "<div>\n\n\t<p>content</p>\n</div>\n"
+		document = Markly.parse(markdown, flags: flags)
+		
+		expect(document.first_child.string_content).to be == markdown
+		expect(document.first_child.next).to be_nil
+	end
+	
+	it "ends the HTML block when content dedents after a blank line" do
+		markdown = "<div>\n\tcontent\n\noutside\n"
+		document = Markly.parse(markdown, flags: flags)
+		
+		expect(document.first_child.string_content).to be == "<div>\n\tcontent\n\n"
+		expect(document.first_child.next.type).to be == :paragraph
+	end
+	
+	it "does not extend unindented HTML content" do
+		markdown = "<div>\ncontent\n\nmore\n"
+		document = Markly.parse(markdown, flags: flags)
+		
+		expect(document.first_child.next).not.to be_nil
+	end
+	
+	it "renders retained raw HTML when unsafe rendering is enabled" do
+		markdown = "<slide-diagram>\n  first\n\n    nested\n</slide-diagram>\n"
+		html = Markly.render_html(
+			markdown,
+			parse_flags: flags,
+			render_flags: Markly::UNSAFE,
+		)
+		
+		expect(html).to be == markdown
+	end
+end