@pretextbook/ptxast-util-to-mdast 0.0.4 → 0.0.6

package/README.md

@@ -28,7 +28,19 @@ Converts a `PtxRoot` tree to an mdast `Root` tree with directive nodes for PreTe
 
 ### `ptxastToMarkdown(root: PtxRoot): string`
 
-Converts a `PtxRoot` tree to a Markdown string. Theorem-like environments render as `:::theorem` directive fences; divisions render as ATX headings (`##`).
+Converts a `PtxRoot` tree to a Markdown string. Theorem-like environments render as `:::theorem` directive fences; divisions render as ATX headings, relative to the document's actual outermost division (a depth-1 heading is whatever that division is — `chapter`, `section`, `part`, ...).
+
+When the outermost division isn't `chapter` (the default a depth-1 heading is assumed to mean by [`@pretextbook/remark-pretext`](../remark-pretext)), a `division:` frontmatter block is prepended so the markdown can be converted back to PreTeXt unambiguously:
+
+```
+---
+division: section
+---
+
+# Top-level section
+
+## A subsection
+```
 
 ## License
 

package/dist/index.cjs

@@ -1,2 +1,7 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("@pretextbook/ptxast"),k=require("mdast-util-to-markdown"),x=require("mdast-util-directive"),v=require("mdast-util-math"),b=new Set(["chapter","section","subsection","subsubsection","paragraphs","appendix"]),T={chapter:1,section:2,subsection:3,subsubsection:4,paragraphs:5,appendix:1},w=new Set(["pretext","book","article","frontmatter","backmatter","part"]),P=new Map([["theorem",{name:"theorem",category:"theorem-like"}],["lemma",{name:"lemma",category:"theorem-like"}],["corollary",{name:"corollary",category:"theorem-like"}],["proposition",{name:"proposition",category:"theorem-like"}],["claim",{name:"claim",category:"theorem-like"}],["fact",{name:"fact",category:"theorem-like"}],["conjecture",{name:"conjecture",category:"theorem-like"}],["axiom",{name:"axiom",category:"theorem-like"}],["principle",{name:"principle",category:"theorem-like"}],["hypothesis",{name:"hypothesis",category:"theorem-like"}],["algorithm",{name:"algorithm",category:"theorem-like"}],["definition",{name:"definition",category:"definition-like"}],["notation",{name:"notation",category:"definition-like"}],["remark",{name:"remark",category:"remark-like"}],["note",{name:"note",category:"remark-like"}],["observation",{name:"observation",category:"remark-like"}],["warning",{name:"warning",category:"remark-like"}],["insight",{name:"insight",category:"remark-like"}],["assemblage",{name:"assemblage",category:"remark-like"}],["example",{name:"example",category:"example-like"}],["question",{name:"question",category:"example-like"}],["problem",{name:"problem",category:"example-like"}],["exercise",{name:"exercise",category:"example-like"}],["activity",{name:"activity",category:"example-like"}],["exploration",{name:"exploration",category:"example-like"}],["investigation",{name:"investigation",category:"example-like"}],["project",{name:"project",category:"example-like"}],["proof",{name:"proof",category:"proof-like"}],["case",{name:"case",category:"proof-like"}],["solution",{name:"solution",category:"solution-like"}],["hint",{name:"hint",category:"solution-like"}],["answer",{name:"answer",category:"solution-like"}]]),M=new Set(["theorem-like","definition-like"]);function g(e){return{type:"root",children:d(e.children,2)}}function d(e,t){const n=[];for(const r of e){if(r.type!=="element")continue;const o=r;if(w.has(o.name))n.push(...d(o.children,t));else if(b.has(o.name)){const l=T[o.name]??t;n.push(...E(o,l))}else{const l=u(o);l!==null&&n.push(l)}}return n}function E(e,t){const n=[],r=e.attributes??{},o=e.children,l=o.find(a=>a.type==="element"&&a.name==="title"),s=o.filter(a=>!(a.type==="element"&&a.name==="title")),i={type:"heading",depth:t,children:l?l.children.map(h).filter(m):[],...r["xml:id"]?{data:{id:r["xml:id"],hProperties:{id:r["xml:id"]}}}:{}};n.push(i);const c=Math.min(t+1,6);return n.push(...d(s,c)),n}function u(e){switch(e.name){case"p":return S(e);case"blockquote":return C(e);case"ol":return y(e,!0);case"ul":return y(e,!1);case"program":return D(e);case"me":case"men":case"md":case"mdn":return I(e);default:{const t=P.get(e.name);return t?j(e,t):null}}}function S(e){return{type:"paragraph",children:e.children.map(h).filter(m)}}function C(e){return{type:"blockquote",children:e.children.filter(t=>t.type==="element").map(t=>u(t)).filter(m)}}function y(e,t){return{type:"list",ordered:t,spread:!1,children:e.children.filter(n=>n.type==="element").map(n=>q(n))}}function q(e){return{type:"listItem",spread:!1,children:e.children.filter(t=>t.type==="element").map(t=>u(t)).filter(m)}}function D(e){return{type:"code",lang:(e.attributes??{}).language??null,value:p.getPtxTextContent(e)}}function I(e){const t=e.children;return t.length>0&&t[0].type==="text"?{type:"math",value:p.getPtxTextContent(e)}:{type:"math",value:t.filter(r=>r.type==="element"&&r.name==="mrow").map(r=>p.getPtxTextContent(r)).join(` \\\\
-`)}}function j(e,t){const n=e.attributes??{},r=e.children,o={};n["xml:id"]&&(o.id=n["xml:id"]);for(const[i,c]of Object.entries(n))i==="xml:id"||c==null||(o[i]=c);const l=r.find(i=>i.type==="element"&&i.name==="title"),s=[];if(l){const i={type:"paragraph",data:{directiveLabel:!0},children:l.children.map(h).filter(m)};s.push(i)}if(M.has(t.category))for(const i of r){if(i.type!=="element")continue;const c=i;if(c.name!=="title")if(c.name==="statement")for(const a of c.children){if(a.type!=="element")continue;const f=u(a);f&&s.push(f)}else{const a=u(c);a&&s.push(a)}}else for(const i of r){if(i.type!=="element")continue;const c=i;if(c.name==="title")continue;const a=u(c);a&&s.push(a)}return{type:"containerDirective",name:t.name,attributes:Object.keys(o).length>0?o:void 0,children:s}}function h(e){if(e.type==="text")return{type:"text",value:e.value??""};if(e.type!=="element")return null;const t=e;switch(t.name){case"em":return{type:"emphasis",children:t.children.map(h).filter(m)};case"alert":return{type:"strong",children:t.children.map(h).filter(m)};case"c":return{type:"inlineCode",value:p.getPtxTextContent(t)};case"m":return{type:"inlineMath",value:p.getPtxTextContent(t)};default:return null}}function m(e){return e!==null}function N(e){const t=g(e);return k.toMarkdown(t,{extensions:[x.directiveToMarkdown(),v.mathToMarkdown()]})}exports.ptxastToMarkdown=N;exports.ptxastToMdast=g;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("@pretextbook/ptxast"),T=require("mdast-util-to-markdown"),I=require("mdast-util-directive"),S=require("mdast-util-math"),g=new Set([...c.DIVISION_HIERARCHY,...c.EXTRA_DIVISION_TYPES.filter(e=>!c.isTitlelessDivisionType(e))]),k=new Set(c.TITLELESS_DIVISION_TYPES),x=new Set(["pretext","book","article","frontmatter","backmatter"]),E=new Map([["theorem",{name:"theorem",category:"theorem-like"}],["lemma",{name:"lemma",category:"theorem-like"}],["corollary",{name:"corollary",category:"theorem-like"}],["proposition",{name:"proposition",category:"theorem-like"}],["claim",{name:"claim",category:"theorem-like"}],["fact",{name:"fact",category:"theorem-like"}],["conjecture",{name:"conjecture",category:"theorem-like"}],["axiom",{name:"axiom",category:"theorem-like"}],["principle",{name:"principle",category:"theorem-like"}],["hypothesis",{name:"hypothesis",category:"theorem-like"}],["algorithm",{name:"algorithm",category:"theorem-like"}],["definition",{name:"definition",category:"definition-like"}],["notation",{name:"notation",category:"definition-like"}],["remark",{name:"remark",category:"remark-like"}],["note",{name:"note",category:"remark-like"}],["observation",{name:"observation",category:"remark-like"}],["warning",{name:"warning",category:"remark-like"}],["insight",{name:"insight",category:"remark-like"}],["assemblage",{name:"assemblage",category:"remark-like"}],["example",{name:"example",category:"example-like"}],["question",{name:"question",category:"example-like"}],["problem",{name:"problem",category:"example-like"}],["exercise",{name:"exercise",category:"example-like"}],["activity",{name:"activity",category:"example-like"}],["exploration",{name:"exploration",category:"example-like"}],["investigation",{name:"investigation",category:"example-like"}],["project",{name:"project",category:"example-like"}],["proof",{name:"proof",category:"proof-like"}],["case",{name:"case",category:"proof-like"}],["solution",{name:"solution",category:"solution-like"}],["hint",{name:"hint",category:"solution-like"}],["answer",{name:"answer",category:"solution-like"}]]),P=new Set(["theorem-like","definition-like"]);function v(e){return{type:"root",children:h(e.children,1)}}function b(e){for(const t of e){if(t.type!=="element")continue;const i=t;if(g.has(i.name)||k.has(i.name)){const n=i.attributes??{},r={};return n["xml:id"]&&(r.xmlid=n["xml:id"]),n.label&&(r.label=n.label),n.component&&(r.component=n.component),{name:i.name,attributes:r}}if(x.has(i.name)){const n=b(i.children);if(n)return n}}}function h(e,t){const i=[];for(const n of e){if(n.type!=="element")continue;const r=n;if(x.has(r.name)||k.has(r.name))i.push(...h(r.children,t));else if(g.has(r.name))i.push(...w(r,Math.min(t,6)));else{const s=p(r);s!==null&&i.push(s)}}return i}function w(e,t){const i=[],n=e.attributes??{},r=e.children,s=r.find(a=>a.type==="element"&&a.name==="title"),m=r.filter(a=>!(a.type==="element"&&a.name==="title")),o={type:"heading",depth:t,children:s?s.children.map(f).filter(u):[],...n["xml:id"]?{data:{id:n["xml:id"],hProperties:{id:n["xml:id"]}}}:{}};i.push(o);const l=Math.min(t+1,6);return i.push(...h(m,l)),i}function p(e){switch(e.name){case"p":return M(e);case"blockquote":return D(e);case"ol":return y(e,!0);case"ul":return y(e,!1);case"program":return N(e);case"me":case"men":case"md":case"mdn":return C(e);default:{const t=E.get(e.name);return t?j(e,t):null}}}function M(e){return{type:"paragraph",children:e.children.map(f).filter(u)}}function D(e){return{type:"blockquote",children:e.children.filter(t=>t.type==="element").map(t=>p(t)).filter(u)}}function y(e,t){return{type:"list",ordered:t,spread:!1,children:e.children.filter(i=>i.type==="element").map(i=>_(i))}}function _(e){return{type:"listItem",spread:!1,children:e.children.filter(t=>t.type==="element").map(t=>p(t)).filter(u)}}function N(e){return{type:"code",lang:(e.attributes??{}).language??null,value:c.getPtxTextContent(e)}}function C(e){const t=e.children;return t.length>0&&t[0].type==="text"?{type:"math",value:c.getPtxTextContent(e)}:{type:"math",value:t.filter(n=>n.type==="element"&&n.name==="mrow").map(n=>c.getPtxTextContent(n)).join(` \\\\
+`)}}function j(e,t){const i=e.attributes??{},n=e.children,r={};i["xml:id"]&&(r.id=i["xml:id"]);for(const[o,l]of Object.entries(i))o==="xml:id"||l==null||(r[o]=l);const s=n.find(o=>o.type==="element"&&o.name==="title"),m=[];if(s){const o={type:"paragraph",data:{directiveLabel:!0},children:s.children.map(f).filter(u)};m.push(o)}if(P.has(t.category))for(const o of n){if(o.type!=="element")continue;const l=o;if(l.name!=="title")if(l.name==="statement")for(const a of l.children){if(a.type!=="element")continue;const d=p(a);d&&m.push(d)}else{const a=p(l);a&&m.push(a)}}else for(const o of n){if(o.type!=="element")continue;const l=o;if(l.name==="title")continue;const a=p(l);a&&m.push(a)}return{type:"containerDirective",name:t.name,attributes:Object.keys(r).length>0?r:void 0,children:m}}function f(e){if(e.type==="text")return{type:"text",value:e.value??""};if(e.type!=="element")return null;const t=e;switch(t.name){case"em":return{type:"emphasis",children:t.children.map(f).filter(u)};case"alert":return{type:"strong",children:t.children.map(f).filter(u)};case"c":return{type:"inlineCode",value:c.getPtxTextContent(t)};case"m":return{type:"inlineMath",value:c.getPtxTextContent(t)};default:return null}}function u(e){return e!==null}function q(e){const t=v(e),i=T.toMarkdown(t,{extensions:[I.directiveToMarkdown(),S.mathToMarkdown()]}),n=b(e.children);if(!n)return i;const r=[];return n.name!=="chapter"&&r.push(`division: ${n.name}`),n.attributes.xmlid&&r.push(`xmlid: ${n.attributes.xmlid}`),n.attributes.label&&r.push(`label: ${n.attributes.label}`),n.attributes.component&&r.push(`component: ${n.attributes.component}`),r.length===0?i:`---
+${r.join(`
+`)}
+---
+
+${i}`}exports.ptxastToMarkdown=q;exports.ptxastToMdast=v;

package/dist/index.js

@@ -1,30 +1,17 @@
-import { getPtxTextContent as u } from "@pretextbook/ptxast";
-import { toMarkdown as g } from "mdast-util-to-markdown";
-import { directiveToMarkdown as k } from "mdast-util-directive";
-import { mathToMarkdown as v } from "mdast-util-math";
-const x = /* @__PURE__ */ new Set([
-  "chapter",
-  "section",
-  "subsection",
-  "subsubsection",
-  "paragraphs",
-  // appendix is division-like at the same level as chapter
-  "appendix"
-]), b = {
-  chapter: 1,
-  section: 2,
-  subsection: 3,
-  subsubsection: 4,
-  paragraphs: 5,
-  appendix: 1
-}, T = /* @__PURE__ */ new Set([
+import { DIVISION_HIERARCHY as b, EXTRA_DIVISION_TYPES as T, isTitlelessDivisionType as I, TITLELESS_DIVISION_TYPES as S, getPtxTextContent as p } from "@pretextbook/ptxast";
+import { toMarkdown as E } from "mdast-util-to-markdown";
+import { directiveToMarkdown as w } from "mdast-util-directive";
+import { mathToMarkdown as _ } from "mdast-util-math";
+const g = /* @__PURE__ */ new Set([
+  ...b,
+  ...T.filter((e) => !I(e))
+]), k = new Set(S), v = /* @__PURE__ */ new Set([
   "pretext",
   "book",
   "article",
   "frontmatter",
-  "backmatter",
-  "part"
-]), w = /* @__PURE__ */ new Map([
+  "backmatter"
+]), P = /* @__PURE__ */ new Map([
   // theorem-like
   ["theorem", { name: "theorem", category: "theorem-like" }],
   ["lemma", { name: "lemma", category: "theorem-like" }],
@@ -63,78 +50,91 @@ const x = /* @__PURE__ */ new Set([
   ["solution", { name: "solution", category: "solution-like" }],
   ["hint", { name: "hint", category: "solution-like" }],
   ["answer", { name: "answer", category: "solution-like" }]
-]), E = /* @__PURE__ */ new Set(["theorem-like", "definition-like"]);
-function P(e) {
+]), D = /* @__PURE__ */ new Set(["theorem-like", "definition-like"]);
+function N(e) {
   return {
     type: "root",
-    children: f(e.children, 2)
+    children: h(e.children, 1)
   };
 }
-function f(e, t) {
-  const n = [];
-  for (const r of e) {
-    if (r.type !== "element") continue;
-    const o = r;
-    if (T.has(o.name))
-      n.push(...f(o.children, t));
-    else if (x.has(o.name)) {
-      const l = b[o.name] ?? t;
-      n.push(...M(o, l));
-    } else {
-      const l = p(o);
-      l !== null && n.push(l);
+function x(e) {
+  for (const t of e) {
+    if (t.type !== "element") continue;
+    const i = t;
+    if (g.has(i.name) || k.has(i.name)) {
+      const n = i.attributes ?? {}, r = {};
+      return n["xml:id"] && (r.xmlid = n["xml:id"]), n.label && (r.label = n.label), n.component && (r.component = n.component), { name: i.name, attributes: r };
+    }
+    if (v.has(i.name)) {
+      const n = x(i.children);
+      if (n) return n;
+    }
+  }
+}
+function h(e, t) {
+  const i = [];
+  for (const n of e) {
+    if (n.type !== "element") continue;
+    const r = n;
+    if (v.has(r.name) || k.has(r.name))
+      i.push(...h(r.children, t));
+    else if (g.has(r.name))
+      i.push(...M(r, Math.min(t, 6)));
+    else {
+      const c = u(r);
+      c !== null && i.push(c);
     }
   }
-  return n;
+  return i;
 }
 function M(e, t) {
-  const n = [], r = e.attributes ?? {}, o = e.children, l = o.find(
+  const i = [], n = e.attributes ?? {}, r = e.children, c = r.find(
     (a) => a.type === "element" && a.name === "title"
-  ), s = o.filter(
+  ), m = r.filter(
     (a) => !(a.type === "element" && a.name === "title")
-  ), i = {
+  ), o = {
     type: "heading",
     depth: t,
-    children: l ? l.children.map(h).filter(m) : [],
-    ...r["xml:id"] ? { data: { id: r["xml:id"], hProperties: { id: r["xml:id"] } } } : {}
+    children: c ? c.children.map(f).filter(s) : [],
+    ...n["xml:id"] ? { data: { id: n["xml:id"], hProperties: { id: n["xml:id"] } } } : {}
   };
-  n.push(i);
-  const c = Math.min(t + 1, 6);
-  return n.push(...f(s, c)), n;
+  i.push(o);
+  const l = Math.min(t + 1, 6);
+  return i.push(...h(m, l)), i;
 }
-function p(e) {
+function u(e) {
   switch (e.name) {
     case "p":
-      return I(e);
+      return L(e);
     case "blockquote":
-      return S(e);
+      return A(e);
     case "ol":
       return y(e, !0);
     case "ul":
       return y(e, !1);
     case "program":
-      return N(e);
+      return j(e);
     case "me":
     case "men":
     case "md":
     case "mdn":
-      return j(e);
+      return R(e);
     default: {
-      const t = w.get(e.name);
-      return t ? _(e, t) : null;
+      const t = P.get(e.name);
+      return t ? Y(e, t) : null;
     }
   }
 }
-function I(e) {
+function L(e) {
   return {
     type: "paragraph",
-    children: e.children.map(h).filter(m)
+    children: e.children.map(f).filter(s)
   };
 }
-function S(e) {
+function A(e) {
   return {
     type: "blockquote",
-    children: e.children.filter((t) => t.type === "element").map((t) => p(t)).filter(m)
+    children: e.children.filter((t) => t.type === "element").map((t) => u(t)).filter(s)
   };
 }
 function y(e, t) {
@@ -142,76 +142,76 @@ function y(e, t) {
     type: "list",
     ordered: t,
     spread: !1,
-    children: e.children.filter((n) => n.type === "element").map((n) => D(n))
+    children: e.children.filter((i) => i.type === "element").map((i) => O(i))
   };
 }
-function D(e) {
+function O(e) {
   return {
     type: "listItem",
     spread: !1,
-    children: e.children.filter((t) => t.type === "element").map((t) => p(t)).filter(m)
+    children: e.children.filter((t) => t.type === "element").map((t) => u(t)).filter(s)
   };
 }
-function N(e) {
+function j(e) {
   return {
     type: "code",
     lang: (e.attributes ?? {}).language ?? null,
-    value: u(e)
+    value: p(e)
   };
 }
-function j(e) {
+function R(e) {
   const t = e.children;
-  return t.length > 0 && t[0].type === "text" ? { type: "math", value: u(e) } : { type: "math", value: t.filter((r) => r.type === "element" && r.name === "mrow").map((r) => u(r)).join(` \\\\
+  return t.length > 0 && t[0].type === "text" ? { type: "math", value: p(e) } : { type: "math", value: t.filter((n) => n.type === "element" && n.name === "mrow").map((n) => p(n)).join(` \\\\
 `) };
 }
-function _(e, t) {
-  const n = e.attributes ?? {}, r = e.children, o = {};
-  n["xml:id"] && (o.id = n["xml:id"]);
-  for (const [i, c] of Object.entries(n))
-    i === "xml:id" || c == null || (o[i] = c);
-  const l = r.find(
-    (i) => i.type === "element" && i.name === "title"
-  ), s = [];
-  if (l) {
-    const i = {
+function Y(e, t) {
+  const i = e.attributes ?? {}, n = e.children, r = {};
+  i["xml:id"] && (r.id = i["xml:id"]);
+  for (const [o, l] of Object.entries(i))
+    o === "xml:id" || l == null || (r[o] = l);
+  const c = n.find(
+    (o) => o.type === "element" && o.name === "title"
+  ), m = [];
+  if (c) {
+    const o = {
       type: "paragraph",
       data: { directiveLabel: !0 },
-      children: l.children.map(h).filter(m)
+      children: c.children.map(f).filter(s)
     };
-    s.push(i);
+    m.push(o);
   }
-  if (E.has(t.category))
-    for (const i of r) {
-      if (i.type !== "element") continue;
-      const c = i;
-      if (c.name !== "title")
-        if (c.name === "statement")
-          for (const a of c.children) {
+  if (D.has(t.category))
+    for (const o of n) {
+      if (o.type !== "element") continue;
+      const l = o;
+      if (l.name !== "title")
+        if (l.name === "statement")
+          for (const a of l.children) {
             if (a.type !== "element") continue;
-            const d = p(a);
-            d && s.push(d);
+            const d = u(a);
+            d && m.push(d);
           }
         else {
-          const a = p(c);
-          a && s.push(a);
+          const a = u(l);
+          a && m.push(a);
         }
     }
   else
-    for (const i of r) {
-      if (i.type !== "element") continue;
-      const c = i;
-      if (c.name === "title") continue;
-      const a = p(c);
-      a && s.push(a);
+    for (const o of n) {
+      if (o.type !== "element") continue;
+      const l = o;
+      if (l.name === "title") continue;
+      const a = u(l);
+      a && m.push(a);
     }
   return {
     type: "containerDirective",
     name: t.name,
-    attributes: Object.keys(o).length > 0 ? o : void 0,
-    children: s
+    attributes: Object.keys(r).length > 0 ? r : void 0,
+    children: m
   };
 }
-function h(e) {
+function f(e) {
   if (e.type === "text")
     return { type: "text", value: e.value ?? "" };
   if (e.type !== "element") return null;
@@ -220,31 +220,38 @@ function h(e) {
     case "em":
       return {
         type: "emphasis",
-        children: t.children.map(h).filter(m)
+        children: t.children.map(f).filter(s)
       };
     case "alert":
       return {
         type: "strong",
-        children: t.children.map(h).filter(m)
+        children: t.children.map(f).filter(s)
       };
     case "c":
-      return { type: "inlineCode", value: u(t) };
+      return { type: "inlineCode", value: p(t) };
     case "m":
-      return { type: "inlineMath", value: u(t) };
+      return { type: "inlineMath", value: p(t) };
     default:
       return null;
   }
 }
-function m(e) {
+function s(e) {
   return e !== null;
 }
-function O(e) {
-  const t = P(e);
-  return g(t, {
-    extensions: [k(), v()]
-  });
+function H(e) {
+  const t = N(e), i = E(t, {
+    extensions: [w(), _()]
+  }), n = x(e.children);
+  if (!n) return i;
+  const r = [];
+  return n.name !== "chapter" && r.push(`division: ${n.name}`), n.attributes.xmlid && r.push(`xmlid: ${n.attributes.xmlid}`), n.attributes.label && r.push(`label: ${n.attributes.label}`), n.attributes.component && r.push(`component: ${n.attributes.component}`), r.length === 0 ? i : `---
+${r.join(`
+`)}
+---
+
+${i}`;
 }
 export {
-  O as ptxastToMarkdown,
-  P as ptxastToMdast
+  H as ptxastToMarkdown,
+  N as ptxastToMdast
 };

package/dist/lib/ptxast-to-mdast.d.ts

@@ -1,4 +1,36 @@
 import { Root as MdastRoot } from 'mdast';
-import { Root } from '@pretextbook/ptxast';
+import { Root, ElementContent } from '@pretextbook/ptxast';
+export declare const DIVISION_TYPE_NAMES: Set<string>;
+export declare const TITLELESS_DIVISION_TYPES: Set<string>;
+/**
+ * Structural container types whose content should be recursed into
+ * without emitting a heading, and without changing the current depth.
+ * This handles full ptxast trees that include a `pretext > book > chapter`
+ * hierarchy.
+ */
+export declare const TRANSPARENT_TYPES: Set<string>;
 /** Convert an xast Root (PreTeXt document) to an mdast Root. */
 export declare function ptxastToMdast(root: Root): MdastRoot;
+/** The outermost division's name plus the subset of its attributes that
+ * round-trip through markdown frontmatter (`xmlid`, `label`, `component`). */
+export interface TopLevelDivisionInfo {
+    name: string;
+    attributes: {
+        xmlid?: string;
+        label?: string;
+        component?: string;
+    };
+}
+/**
+ * Find the outermost division in a ptxast tree (skipping transparent
+ * structural wrappers), i.e. the division a depth-1 heading would represent
+ * if this tree were flattened to markdown — along with its `xml:id`/
+ * `label`/`component` attributes, for round-tripping into frontmatter.
+ */
+export declare function findTopLevelDivisionInfo(nodes: ElementContent[]): TopLevelDivisionInfo | undefined;
+/**
+ * Find the name of the outermost division in a ptxast tree (skipping
+ * transparent structural wrappers), i.e. the division a depth-1 heading
+ * would represent if this tree were flattened to markdown.
+ */
+export declare function findTopLevelDivision(nodes: ElementContent[]): string | undefined;

package/dist/lib/ptxast-util-to-mdast.d.ts

@@ -3,5 +3,11 @@ export { ptxastToMdast } from './ptxast-to-mdast.js';
 /**
  * Convert an xast Root (PreTeXt document) to a markdown string using the directive
  * syntax for PreTeXt block environments.
+ *
+ * A leading frontmatter block is prepended when the outermost division
+ * carries information that markdown can't otherwise represent: a
+ * `division:` field when it isn't `chapter` (the default a depth-1 heading
+ * is assumed to mean), and `xmlid:`/`label:`/`component:` fields mirroring
+ * that division's `xml:id`/`label`/`component` attributes.
  */
 export declare function ptxastToMarkdown(root: Root): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/ptxast-util-to-mdast",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Convert ptxast to mdast (markdown AST) and markdown strings",
   "author": "Oscar Levin",
   "license": "GPL-3.0-or-later",
@@ -39,7 +39,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@pretextbook/ptxast": "^0.0.4",
+    "@pretextbook/ptxast": "^0.0.6",
     "@types/mdast": "^4.0.0",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-math": "^3.0.0",