@uniweb/content-writer 0.2.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.1.17"
+    "@uniweb/content-reader": "1.2.0"
   },
   "directories": {
     "test": "tests"

package/src/nodes.js

@@ -126,6 +126,42 @@ export function serializeInsetBlock(node) {
   return `${fence}@${component}${attrStr}\n${body}\n${fence}`
 }
 
+/**
+ * Serialize a concept block back to its ```md:<tag> fence.
+ *
+ * The inverse of content-reader's concept-block branch. The body is real block
+ * content, so it serializes through the ordinary node path — a concept block is
+ * the section pipeline one level down, and its body is markdown at both ends.
+ *
+ * The fence widens past any backtick run in the body, for the same reason a
+ * container's does: an answer that shows a code sample is ordinary
+ * documentation, and a three-backtick fence would close on the sample's own
+ * fence and spill the remainder into the page as prose.
+ *
+ * A missing serializer here is not a cosmetic gap. `serializeNode` omits an
+ * unmapped node, so the whole block — the author's prose with it — would
+ * vanish from the file on the next write-back and from the per-page markdown
+ * projection. That is why the round-trip test asserts the BODY rather than
+ * just the fence line.
+ *
+ * @param {Object} node - concept_block node with attrs.tag + block content
+ * @returns {string} Fenced concept block
+ */
+export function serializeConceptBlock(node) {
+  const { tag } = node.attrs || {}
+  if (!tag) return ''
+
+  const { serializeNode } = await_serializer()
+  const body = (node.content || [])
+    .map(child => serializeNode(child))
+    .filter(Boolean)
+    .join('\n\n')
+
+  const fence = '`'.repeat(fenceWidthFor(body))
+
+  return `${fence}md:${tag}\n${body}\n${fence}`
+}
+
 /**
  * Serialize a data block node.
  *
@@ -317,9 +353,21 @@ function indentBlock(text, firstPrefix, pad) {
 
 /**
  * Serialize a divider node.
- * @returns {string} Markdown horizontal rule
+ *
+ * Emits the attribute spelling only when `type` carries a non-default value, so
+ * an ordinary rule stays `---` and no existing document is rewritten. `style` and
+ * `size` are deliberately NOT emitted: they are dead attrs (nothing reads them,
+ * no spelling sets them) and writing them would put vocabulary into every
+ * author's file that the framework is trying to retire.
+ *
+ * @param {Object} [node] - Divider node
+ * @returns {string} Markdown thematic break, with `{type=…}` when meaningful
  */
-export function serializeDivider() {
+export function serializeDivider(node) {
+  const type = node?.attrs?.type
+  if (typeof type === 'string' && type && type !== 'hr') {
+    return `---{type=${type}}`
+  }
   return '---'
 }
 

package/src/serializer.js

@@ -10,6 +10,7 @@ import {
   serializeImage,
   serializeInsetRef,
   serializeInsetBlock,
+  serializeConceptBlock,
   serializeCodeBlock,
   serializeDataBlock,
   serializeBlockquote,
@@ -29,6 +30,7 @@ const NODE_SERIALIZERS = {
   image: serializeImage,
   inset_ref: serializeInsetRef,
   inset_block: serializeInsetBlock,
+  concept_block: serializeConceptBlock,
   codeBlock: serializeCodeBlock,
   dataBlock: serializeDataBlock,
   blockquote: serializeBlockquote,

package/tests/roundtrip.test.js

@@ -389,3 +389,71 @@ describe('Round-trip: Hard breaks', () => {
     expect(proseMirrorToMarkdown(parsed).trim()).toBe('wrapped\nparagraph')
   })
 })
+
+describe('Round-trip: Concept blocks', () => {
+  testRoundTrip(
+    '```md:faq\n# A question\nAn answer.\n\n# Another\nAlso answered.\n```',
+    'concept block with two pairs'
+  )
+
+  testRoundTrip(
+    '```md:warning\nBack up your database **first**.\n\n- Not reversible\n```',
+    'headingless concept block (a callout)'
+  )
+
+  testRoundTrip(
+    '```md:faq\n# Q\nAn answer with **bold** and a [link](/x).\n```',
+    'concept block whose body carries marks and links'
+  )
+
+  test('the BODY survives, not just the fence line', () => {
+    // A missing NODE_SERIALIZERS entry omits the whole node, so a test that
+    // only checks the fence and tag came back would pass on an empty block —
+    // and on a serializer that mangles the prose while the first line looks
+    // right. Assert the content.
+    const md = '```md:faq\n# What plans do you have?\nWe have three.\n```'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out).toContain('md:faq')
+    expect(out).toContain('# What plans do you have?')
+    expect(out).toContain('We have three.')
+  })
+
+  test('serialization is a FIXED POINT, which is the bar — not byte equality', () => {
+    // pass1 may differ from the author's original: the serializer normalizes
+    // spacing, so `# Q` immediately followed by its answer comes back with a
+    // blank line between them. Nothing is lost. Asserting byte-equality
+    // against the original would fail on content that is behaving correctly,
+    // and someone would "fix" the serializer to make it pass.
+    const original = '```md:faq\n# Q1\nA1\n# Q2\nA2\n```'
+    const pass1 = proseMirrorToMarkdown(markdownToProseMirror(original))
+    const pass2 = proseMirrorToMarkdown(markdownToProseMirror(pass1))
+
+    // Guard the guard: a fixed point on NOTHING is trivially true. Verified by
+    // canary — unregister the serializer and every other test in this block
+    // fails while `'' === ''` sails through. So pin the content first.
+    expect(pass1).toContain('# Q1')
+    expect(pass1).toContain('A2')
+    expect(pass2).toBe(pass1)
+  })
+
+  test('a code sample inside a concept block widens the outer fence', () => {
+    // Without fenceWidthFor the outer fence closes on the sample's own fence
+    // and the remainder spills into the page as prose. An FAQ answer that
+    // shows code is ordinary documentation, so this is the common case, not
+    // an edge one.
+    const md = '````md:faq\n# How do I start?\nRun this:\n\n```sh\nnpm i\n```\n````'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out.startsWith('````md:faq')).toBe(true)
+    expect(out).toContain('```sh')
+    expect(markdownToProseMirror(out)).toEqual(markdownToProseMirror(md))
+  })
+
+  test('an unmapped node would be dropped — so this one must stay mapped', () => {
+    // The failure mode this suite exists to catch: serializeNode omits a node
+    // it has no serializer for, taking the author's prose with it.
+    const doc = markdownToProseMirror('```md:faq\n# Q\nA\n```')
+    expect(proseMirrorToMarkdown(doc).trim()).not.toBe('')
+  })
+})