From 7a2019ce70867a851bf86f893397f99f6d9ca84f Mon Sep 17 00:00:00 2001
From: Said-MZ <saidzain897@gmail.com>
Date: Mon, 13 Jul 2026 22:34:28 +0300
Subject: [PATCH 1/4] fix(dev): keep the CSS watcher alive under Foreman

Tailwind's --watch stops as soon as stdin closes, which Foreman does
immediately for spawned processes, so `mise run dev` exited the whole
process group right after boot. --watch=always keeps it running
regardless of stdin.
---
 Procfile.dev | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Procfile.dev b/Procfile.dev
index c1cb248..02aaaf3 100644
--- a/Procfile.dev
+++ b/Procfile.dev
@@ -1,3 +1,3 @@
 web: env RUBY_DEBUG_OPEN=true bin/rails server
 js: yarn build --watch
-css: yarn build:css --watch
+css: yarn build:css --watch=always

From 99ae7172cad2e31a2e12b27f4b8fb1ed10d8da52 Mon Sep 17 00:00:00 2001
From: Said-MZ <saidzain897@gmail.com>
Date: Mon, 13 Jul 2026 22:34:36 +0300
Subject: [PATCH 2/4] feat(markdown): support YAML front matter in Markdown
 uploads

Parse a leading --- delimited YAML block off Markdown uploads before
rendering. `title` overrides the H1/filename fallback for the page
<title>, and `description` renders as a meta description tag. Malformed
or non-mapping front matter (or none at all) falls back to treating the
whole file as plain Markdown body, so nothing breaks rendering.
---
 app/models/markdown_document.rb       | 40 +++++++++++++++---
 test/models/markdown_document_test.rb | 58 +++++++++++++++++++++++++++
 2 files changed, 93 insertions(+), 5 deletions(-)

diff --git a/app/models/markdown_document.rb b/app/models/markdown_document.rb
index 18c586e..4c3f522 100644
--- a/app/models/markdown_document.rb
+++ b/app/models/markdown_document.rb
@@ -18,6 +18,10 @@ class MarkdownDocument
     autolink: true, tasklist: true, footnotes: true
   }.freeze
 
+  # A leading `---` block of YAML, terminated by another `---` line. Common to
+  # every static-site generator's Markdown dialect (Jekyll, Hugo, Astro, ...).
+  FRONT_MATTER_PATTERN = /\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*\r?\n?(.*)\z/m
+
   # Pinned so a stored paste renders identically forever. The ESM build boots
   # itself via startOnLoad and upgrades every <pre class="mermaid">.
   MERMAID_MODULE = "https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.min.mjs".freeze
@@ -67,7 +71,7 @@ class MarkdownDocument
   CSS
 
   def initialize(markdown, filename: nil)
-    @markdown = markdown.to_s
+    @front_matter, @markdown = self.class.split_front_matter(markdown.to_s)
     @filename = filename.to_s
   end
 
@@ -81,7 +85,7 @@ def to_html
       <meta charset="utf-8">
       <meta name="viewport" content="width=device-width, initial-scale=1">
       <title>#{CGI.escapeHTML(document_title)}</title>
-      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+      #{description_meta_tag}<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
       <link rel="stylesheet" href="#{FONTS_HREF}">
       <style>
       #{BRAND_CSS}#{HIGHLIGHT_CSS}
@@ -141,9 +145,35 @@ def mermaid_script
         %(</script>)
     end
 
-    # The document's own H1 names it; fall back to the filename (sans extension)
-    # so the paste still gets a meaningful <title> -- and title.
+    # Front matter's `title` wins if present; then the document's own H1; then
+    # the filename (sans extension), so the paste still gets a meaningful
+    # <title>.
     def document_title
-      @heading.presence || File.basename(@filename, ".*").presence || "Untitled"
+      @front_matter["title"].presence || @heading.presence ||
+        File.basename(@filename, ".*").presence || "Untitled"
+    end
+
+    def description_meta_tag
+      description = @front_matter["description"].presence
+      return "" unless description
+
+      %(<meta name="description" content="#{CGI.escapeHTML(description.to_s)}">\n)
     end
+
+  class << self
+    # Splits a leading YAML front-matter block off the Markdown body. Returns
+    # [{}, raw] unchanged if there's no front matter, the YAML doesn't parse,
+    # or it doesn't parse to a Hash -- front matter is metadata, never load-bearing
+    # for rendering, so any trouble here just means the whole file is treated
+    # as plain Markdown body.
+    def split_front_matter(raw)
+      match = FRONT_MATTER_PATTERN.match(raw)
+      return [ {}, raw ] unless match
+
+      data = YAML.safe_load(match[1], permitted_classes: [ Date, Time ])
+      data.is_a?(Hash) ? [ data, match[2] ] : [ {}, raw ]
+    rescue Psych::SyntaxError, Psych::DisallowedClass
+      [ {}, raw ]
+    end
+  end
 end
diff --git a/test/models/markdown_document_test.rb b/test/models/markdown_document_test.rb
index 929c376..4f27406 100644
--- a/test/models/markdown_document_test.rb
+++ b/test/models/markdown_document_test.rb
@@ -56,4 +56,62 @@ class MarkdownDocumentTest < ActiveSupport::TestCase
 
     assert_not_includes html, "alert('xss')"
   end
+
+  test "strips yaml front matter and uses it for title and description" do
+    html = MarkdownDocument.new(<<~MD, filename: "x.md").to_html
+      ---
+      title: "My Document Title"
+      author: "Jane Doe"
+      date: 2026-07-13
+      tags: [markdown, tutorial, yaml]
+      draft: false
+      description: "A test document"
+      ---
+
+      # Document Heading Starts Here
+      This is the regular Markdown body text.
+    MD
+
+    assert_includes html, "<title>My Document Title</title>"
+    assert_includes html, '<meta name="description" content="A test document">'
+    assert_not_includes html, "title: \"My Document Title\""
+    assert_includes html, ">Document Heading Starts Here</h1>"
+  end
+
+  test "front matter title overrides an h1" do
+    html = MarkdownDocument.new(<<~MD, filename: "x.md").to_html
+      ---
+      title: From Front Matter
+      ---
+      # From Heading
+    MD
+
+    assert_includes html, "<title>From Front Matter</title>"
+  end
+
+  test "falls back to h1, then filename, when front matter has no title" do
+    assert_includes MarkdownDocument.new("---\nauthor: Jane\n---\n# Heading", filename: "x.md").to_html,
+      "<title>Heading</title>"
+    assert_includes MarkdownDocument.new("---\nauthor: Jane\n---\nbody", filename: "my-notes.md").to_html,
+      "<title>my-notes</title>"
+  end
+
+  test "omits the description tag when front matter has none" do
+    html = MarkdownDocument.new("# Plain\n\ntext", filename: "x.md").to_html
+    assert_not_includes html, 'name="description"'
+  end
+
+  test "treats malformed or non-mapping front matter as plain body" do
+    malformed = MarkdownDocument.new("---\n[1, 2\n---\nbody", filename: "x.md").to_html
+    assert_includes malformed, "[1, 2"
+
+    sequence = MarkdownDocument.new("---\n- a\n- b\n---\nbody", filename: "x.md").to_html
+    assert_includes sequence, "<li>a</li>"
+    assert_includes sequence, "<li>b</li>"
+  end
+
+  test "does not treat a body horizontal rule as front matter" do
+    html = MarkdownDocument.new("no leading marker\n\n---\n\nafter the rule", filename: "x.md").to_html
+    assert_includes html, "<hr"
+  end
 end

From fad6217a952f3fec9ebbfe71fef4aaaa4e60f879 Mon Sep 17 00:00:00 2001
From: Said-MZ <saidzain897@gmail.com>
Date: Mon, 13 Jul 2026 22:41:56 +0300
Subject: [PATCH 3/4] fix(markdown): rescue all Psych errors when parsing front
 matter

Psych::SyntaxError and Psych::DisallowedClass aren't the only failure
modes -- YAML aliases (&anchor/*alias) raise Psych::BadAlias or
Psych::AliasesNotEnabled, which weren't rescued and would break
rendering instead of falling back to plain Markdown body.

Co-authored-by: Copilot code review
---
 app/models/markdown_document.rb       | 2 +-
 test/models/markdown_document_test.rb | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/app/models/markdown_document.rb b/app/models/markdown_document.rb
index 4c3f522..daac98a 100644
--- a/app/models/markdown_document.rb
+++ b/app/models/markdown_document.rb
@@ -172,7 +172,7 @@ def split_front_matter(raw)
 
       data = YAML.safe_load(match[1], permitted_classes: [ Date, Time ])
       data.is_a?(Hash) ? [ data, match[2] ] : [ {}, raw ]
-    rescue Psych::SyntaxError, Psych::DisallowedClass
+    rescue Psych::Exception
       [ {}, raw ]
     end
   end
diff --git a/test/models/markdown_document_test.rb b/test/models/markdown_document_test.rb
index 4f27406..8da2b2f 100644
--- a/test/models/markdown_document_test.rb
+++ b/test/models/markdown_document_test.rb
@@ -114,4 +114,10 @@ class MarkdownDocumentTest < ActiveSupport::TestCase
     html = MarkdownDocument.new("no leading marker\n\n---\n\nafter the rule", filename: "x.md").to_html
     assert_includes html, "<hr"
   end
+
+  test "treats front matter with yaml aliases as plain body instead of raising" do
+    html = MarkdownDocument.new("---\nfoo: &anchor bar\nbaz: *anchor\n---\nbody", filename: "x.md").to_html
+    assert_includes html, "<title>x</title>"
+    assert_includes html, "baz: *anchor"
+  end
 end

From 0089373dd111195a33183ef92a3d0afc13cd64ae Mon Sep 17 00:00:00 2001
From: Said-MZ <saidzain897@gmail.com>
Date: Mon, 13 Jul 2026 22:48:26 +0300
Subject: [PATCH 4/4] test(markdown): drop the yaml-alias front matter test

Redundant with the broadened Psych::Exception rescue itself; not
worth the upkeep.
---
 test/models/markdown_document_test.rb | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/test/models/markdown_document_test.rb b/test/models/markdown_document_test.rb
index 8da2b2f..4f27406 100644
--- a/test/models/markdown_document_test.rb
+++ b/test/models/markdown_document_test.rb
@@ -114,10 +114,4 @@ class MarkdownDocumentTest < ActiveSupport::TestCase
     html = MarkdownDocument.new("no leading marker\n\n---\n\nafter the rule", filename: "x.md").to_html
     assert_includes html, "<hr"
   end
-
-  test "treats front matter with yaml aliases as plain body instead of raising" do
-    html = MarkdownDocument.new("---\nfoo: &anchor bar\nbaz: *anchor\n---\nbody", filename: "x.md").to_html
-    assert_includes html, "<title>x</title>"
-    assert_includes html, "baz: *anchor"
-  end
 end