feat: Add markdown-to-YAML conversion utilities for sidebar navigation

Author: ioncakephper

docs/src/utils/markdownToYaml.js

@@ -0,0 +1,287 @@
+import yaml from 'js-yaml';
+
+/**
+ * Parses a Markdown navigation list (as generated by yamlToMarkdown) back into a JS object suitable for YAML serialization.
+ * Handles:
+ *   - Headings (## ...)
+ *   - Paragraphs after heading as sidebar comments
+ *   - List items (- label, - _property_: value, - _tags_:, - _headings_:)
+ *   - Indentation for hierarchy
+ *   - Scalar properties (string, number, boolean)
+ *   - Tags arrays
+ *   - Headings arrays
+ * 
+ * @param {string} markdown - The Markdown string to parse.
+ * @returns {object} The reconstructed JS object (e.g., { sidebars: [...] })
+ */
+export function markdownToYamlObject(markdown) {
+  const lines = markdown.split('\n');
+  const sidebars = [];
+  let currentSidebar = null;
+  let parentsStack = [];
+  let currentItems = null;
+
+  // Helper to get indentation level (2 spaces per level)
+  function getIndentLevel(line) {
+    const match = line.match(/^(\s*)/);
+    return match ? Math.floor((match[1].length) / 2) : 0;
+  }
+
+  // Helper to parse a scalar property line: - _property_: value
+  function parseScalarProperty(line) {
+    const match = line.match(/^- _([a-zA-Z0-9_]+)_: (.+)$/);
+    if (match) {
+      let value = match[2].trim();
+      // Try to parse booleans and numbers
+      if (value === 'true') return [match[1], true];
+      if (value === 'false') return [match[1], false];
+      if (!isNaN(Number(value))) return [match[1], Number(value)];
+      return [match[1], value];
+    }
+    return null;
+  }
+
+  // Helper to parse a label line: - Label or - [Label](href)
+  function parseLabel(line) {
+    // Markdown link
+    const linkMatch = line.match(/^- \[([^\]]+)\]\(([^)]+)\)$/);
+    if (linkMatch) {
+      return { label: linkMatch[1], href: linkMatch[2] };
+    }
+    // Plain label
+    const labelMatch = line.match(/^- (.+)$/);
+    if (labelMatch) {
+      return { label: labelMatch[1] };
+    }
+    return null;
+  }
+
+  let i = 0;
+  while (i < lines.length) {
+    let line = lines[i];
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+    // Sidebar heading
+    if (line.startsWith('## ')) {
+      if (currentSidebar) {
+        sidebars.push(currentSidebar);
+      }
+      currentSidebar = { label: line.replace(/^## /, '').trim() };
+      currentItems = [];
+      currentSidebar.items = currentItems;
+      parentsStack = [{items: currentItems, obj: currentSidebar, level: 0}];
+      i++;
+
+      // Collect paragraphs as comments until first list item or next heading
+      let comments = [];
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        if (
+          nextLine.trim() === '' ||
+          nextLine.startsWith('- ') ||
+          nextLine.startsWith('## ')
+        ) {
+          break;
+        }
+        comments.push(nextLine.trim());
+        i++;
+      }
+      if (comments.length > 0) {
+        currentSidebar.__comments = comments;
+      }
+      continue;
+    }
+
+    // List item or property
+    const indentLevel = getIndentLevel(line);
+    const trimmed = line.trim();
+
+    // _tags_ block
+    if (trimmed.startsWith('- _tags_:')) {
+      // Collect all subsequent indented lines as tags
+      let tags = [];
+      i++;
+      while (i < lines.length) {
+        const tagLine = lines[i];
+        if (tagLine.trim().startsWith('- ')) {
+          tags.push(tagLine.trim().replace(/^- /, ''));
+          i++;
+        } else if (tagLine.trim() === '') {
+          i++;
+        } else {
+          break;
+        }
+      }
+      // Attach tags to the last item in the current parent
+      let parent = parentsStack[parentsStack.length - 1];
+      if (parent && parent.items && parent.items.length > 0) {
+        parent.items[parent.items.length - 1].tags = tags;
+      }
+      continue;
+    }
+
+    // _headings_ block
+    if (trimmed.startsWith('- _headings_:')) {
+      // All subsequent lines at higher indent are headings
+      let headings = [];
+      i++;
+      while (i < lines.length) {
+        const headingLine = lines[i];
+        if (headingLine.trim().startsWith('- ')) {
+          // Recursively parse heading items
+          const headingIndent = getIndentLevel(headingLine);
+          const headingObj = parseLabel(headingLine.trim());
+          if (headingObj) {
+            headings.push(headingObj);
+            // Check for scalar properties or tags under this heading
+            let j = i + 1;
+            while (j < lines.length) {
+              const propLine = lines[j];
+              if (getIndentLevel(propLine) === headingIndent + 1 && propLine.trim().startsWith('- _')) {
+                // Scalar property
+                const prop = parseScalarProperty(propLine.trim());
+                if (prop) {
+                  headingObj[prop[0]] = prop[1];
+                }
+                j++;
+              } else if (getIndentLevel(propLine) === headingIndent + 1 && propLine.trim().startsWith('- _tags_:')) {
+                // Tags under heading
+                let tags = [];
+                j++;
+                while (j < lines.length) {
+                  const tagLine = lines[j];
+                  if (tagLine.trim().startsWith('- ')) {
+                    tags.push(tagLine.trim().replace(/^- /, ''));
+                    j++;
+                  } else if (tagLine.trim() === '') {
+                    j++;
+                  } else {
+                    break;
+                  }
+                }
+                headingObj.tags = tags;
+              } else {
+                break;
+              }
+            }
+          }
+          i++;
+        } else if (headingLine.trim() === '') {
+          i++;
+        } else {
+          break;
+        }
+      }
+      // Attach headings to the last item in the current parent
+      let parent = parentsStack[parentsStack.length - 1];
+      if (parent && parent.items && parent.items.length > 0) {
+        parent.items[parent.items.length - 1].headings = headings;
+      }
+      continue;
+    }
+
+    // Scalar property
+    if (trimmed.startsWith('- _') && trimmed.includes(':')) {
+      const prop = parseScalarProperty(trimmed);
+      if (prop) {
+        // Attach to the last item in the current parent
+        let parent = parentsStack[parentsStack.length - 1];
+        if (parent && parent.items && parent.items.length > 0) {
+          parent.items[parent.items.length - 1][prop[0]] = prop[1];
+        } else if (currentSidebar) {
+          // Attach to sidebar if not in items
+          currentSidebar[prop[0]] = prop[1];
+        }
+      }
+      i++;
+      continue;
+    }
+
+    // List item (label or link)
+    if (trimmed.startsWith('- ')) {
+      const obj = parseLabel(trimmed);
+      // Find the correct parent based on indentation
+      while (parentsStack.length > 0 && parentsStack[parentsStack.length - 1].level >= indentLevel) {
+        parentsStack.pop();
+      }
+      let parent = parentsStack[parentsStack.length - 1];
+      if (parent && parent.items) {
+        parent.items.push(obj);
+      }
+      // Prepare for possible children
+      obj.items = [];
+      parentsStack.push({items: obj.items, obj, level: indentLevel});
+      i++;
+      continue;
+    }
+
+    // Fallback
+    i++;
+  }
+
+  // Push the last sidebar
+  if (currentSidebar) {
+    // Remove empty items arrays
+    function clean(obj) {
+      if (Array.isArray(obj.items) && obj.items.length === 0) delete obj.items;
+      if (Array.isArray(obj.headings) && obj.headings.length === 0) delete obj.headings;
+      if (Array.isArray(obj.tags) && obj.tags.length === 0) delete obj.tags;
+      for (const k in obj) {
+        if (typeof obj[k] === 'object') clean(obj[k]);
+      }
+    }
+    clean(currentSidebar);
+    sidebars.push(currentSidebar);
+  }
+
+  return { sidebars };
+}
+
+/**
+ * Converts Markdown navigation list (as generated by yamlToMarkdown) back to YAML string.
+ * Sidebar-level comments (paragraphs after heading) are rendered as YAML comments.
+ * Prepends YAML comments for markdown file location and timestamp.
+ * @param {string} markdown - The Markdown string to parse.
+ * @param {object} [options] - Optional metadata: { markdownFilePath: string }
+ * @returns {string} YAML string.
+ */
+export function convertMarkdownToYaml(markdown, options = {}) {
+  const obj = markdownToYamlObject(markdown);
+
+  // Custom YAML dump to inject comments
+  function dumpWithComments(obj) {
+    // Only handle sidebars with possible __comments
+    if (!obj.sidebars) return yaml.dump(obj, { noRefs: true, lineWidth: 120 });
+
+    let output = '';
+
+    // Metadata comments
+    if (options.markdownFilePath) {
+      output += `# Source Markdown: ${options.markdownFilePath}\n`;
+    }
+    output += `# Generated: ${new Date().toISOString()}\n`;
+
+    output += 'sidebars:\n';
+    for (const sidebar of obj.sidebars) {
+      // Sidebar-level comments
+      if (sidebar.__comments && Array.isArray(sidebar.__comments)) {
+        for (const comment of sidebar.__comments) {
+          output += `  # ${comment}\n`;
+        }
+      }
+      // Dump the sidebar object, omitting __comments
+      const { __comments, ...sidebarNoComments } = sidebar;
+      // Indent YAML output by 2 spaces
+      let sidebarYaml = yaml.dump([sidebarNoComments], { noRefs: true, lineWidth: 120 });
+      // Remove the leading "- " and indent by 2 spaces
+      sidebarYaml = sidebarYaml.replace(/^- /, '  - ');
+      sidebarYaml = sidebarYaml.replace(/\n-/g, '\n  -');
+      output += sidebarYaml;
+    }
+    return output;
+  }
+
+  return dumpWithComments(obj);
+}