@adobe/helix-md2docx 2.1.29 → 2.1.31

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.1.31](https://github.com/adobe/helix-md2docx/compare/v2.1.30...v2.1.31) (2023-09-30)
+
+
+### Bug Fixes
+
+* **deps:** update dependency hast-util-to-mdast to v10.1.0 ([ec6ab9a](https://github.com/adobe/helix-md2docx/commit/ec6ab9a28325aa1ed79dcad2e173d09ab5a71b51))
+
+## [2.1.30](https://github.com/adobe/helix-md2docx/compare/v2.1.29...v2.1.30) (2023-09-30)
+
+
+### Bug Fixes
+
+* Support in-document Heading Anchors ([b79b2ce](https://github.com/adobe/helix-md2docx/commit/b79b2cea8a091d4046715829f35f4fbb4ede86d2)), closes [#327](https://github.com/adobe/helix-md2docx/issues/327)
+
 ## [2.1.29](https://github.com/adobe/helix-md2docx/compare/v2.1.28...v2.1.29) (2023-09-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2docx",
-  "version": "2.1.29",
+  "version": "2.1.31",
   "description": "Helix Service that converts markdown to word documents",
   "main": "src/index.js",
   "type": "module",
@@ -32,10 +32,12 @@
     "@adobe/helix-markdown-support": "7.0.0",
     "@adobe/helix-shared-process-queue": "3.0.0",
     "@adobe/remark-gridtables": "2.0.1",
-    "docx": "8.2.2",
+    "docx": "8.2.3",
+    "github-slugger": "2.0.0",
     "hast-util-is-element": "3.0.0",
-    "hast-util-to-mdast": "10.0.1",
+    "hast-util-to-mdast": "10.1.0",
     "image-size": "1.0.2",
+    "mdast-util-to-string": "4.0.0",
     "mime": "3.0.0",
     "rehype-parse": "9.0.0",
     "remark-gfm": "4.0.0",
@@ -45,7 +47,7 @@
   },
   "devDependencies": {
     "@adobe/eslint-config-helix": "2.0.3",
-    "@adobe/helix-mediahandler": "2.2.16",
+    "@adobe/helix-mediahandler": "2.2.17",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/exec": "6.0.3",
     "@semantic-release/git": "10.0.1",
@@ -61,7 +63,7 @@
     "mocha": "10.2.0",
     "mocha-multi-reporters": "1.5.1",
     "nock": "13.3.3",
-    "semantic-release": "22.0.4",
+    "semantic-release": "22.0.5",
     "unist-util-inspect": "8.0.0",
     "yauzl": "2.10.0"
   },

package/src/mdast2docx/handlers/bookmark.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2023 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { Bookmark } from 'docx';
+import all from '../all.js';
+
+export default async function bookmark(ctx, node) {
+  const children = await all(ctx, node);
+  return new Bookmark({
+    id: node.anchor,
+    children,
+  });
+}

package/src/mdast2docx/handlers/heading.js

@@ -9,7 +9,8 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { HeadingLevel, Paragraph } from 'docx';
+import { Bookmark, HeadingLevel, Paragraph } from 'docx';
+
 import all from '../all.js';
 
 const DEPTHS = [
@@ -23,6 +24,13 @@ const DEPTHS = [
 
 export default async function heading(ctx, node, parent) {
   const children = await all(ctx, node);
+
+  if (node.anchor) {
+    children.unshift(new Bookmark({
+      id: node.anchor,
+      children: [],
+    }));
+  }
   return new Paragraph({
     heading: DEPTHS[node.depth - 1],
     children,

package/src/mdast2docx/handlers/index.js

@@ -9,10 +9,13 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-
+import all from '../all.js';
+import bookmark from './bookmark.js';
 import brk from './break.js';
 import characterStyle from './characterStyle.js';
 import code from './code.js';
+import gridTable from './gridTable.js';
+import gtRow from './gtRow.js';
 import heading from './heading.js';
 import html from './html.js';
 import image from './image.js';
@@ -24,24 +27,24 @@ import paragraph from './paragraph.js';
 import paragraphStyle from './paragraphStyle.js';
 import root from './root.js';
 import table from './table.js';
-import tableRow from './tableRow.js';
 import tableCell from './tableCell.js';
+import tableRow from './tableRow.js';
 import text from './text.js';
 import thematicBreak from './thematicBreak.js';
-import gridTable from './gridTable.js';
-import gtRow from './gtRow.js';
-import all from '../all.js';
 
 export default {
   blockquote: paragraphStyle('Quote'),
+  bookmark,
   break: brk,
   code,
   delete: characterStyle('strike'),
   emphasis: characterStyle('italics'),
-  strong: characterStyle('bold'),
-  underline: characterStyle('underline'),
-  subscript: characterStyle('subScript'),
-  superscript: characterStyle('superScript'),
+  gridTable,
+  gtBody: all,
+  gtCell: tableCell,
+  gtFooter: all,
+  gtHeader: all,
+  gtRow,
   heading,
   html,
   image,
@@ -51,15 +54,13 @@ export default {
   listItem,
   paragraph,
   root,
+  strong: characterStyle('bold'),
+  subscript: characterStyle('subScript'),
+  superscript: characterStyle('superScript'),
   table,
-  tableRow,
   tableCell,
+  tableRow,
   text,
   thematicBreak,
-  gridTable,
-  gtRow,
-  gtHeader: all,
-  gtFooter: all,
-  gtBody: all,
-  gtCell: tableCell,
+  underline: characterStyle('underline'),
 };

package/src/mdast2docx/handlers/link.js

@@ -9,7 +9,9 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { ExternalHyperlink, ImageRun, TextRun } from 'docx';
+import {
+  ExternalHyperlink, ImageRun, InternalHyperlink, TextRun,
+} from 'docx';
 import all from '../all.js';
 
 /**
@@ -49,6 +51,12 @@ export default async function link(ctx, node) {
         }));
       }
     }
+  } else if (node.url.startsWith('#')) {
+    // Link to the headings
+    result.push(new InternalHyperlink({
+      children,
+      anchor: node.anchor,
+    }));
   } else {
     result.push(new ExternalHyperlink({
       children,

package/src/mdast2docx/index.js

@@ -21,6 +21,7 @@ import sanitizeHtml from './mdast-sanitize-html.js';
 // import { openArrayBuffer } from '../zipfile.js';
 import { findXMLComponent } from './utils.js';
 import downloadImages from './mdast-download-images.js';
+import { buildAnchors } from './mdast-docx-anchors.js';
 
 export default async function mdast2docx(mdast, opts = {}) {
   const {
@@ -54,7 +55,7 @@ export default async function mdast2docx(mdast, opts = {}) {
   // process.stdout.write('==================================================\n');
 
   await downloadImages(ctx, mdast);
-
+  await buildAnchors(mdast);
   const children = await all(ctx, mdast);
 
   if (!stylesXML) {

package/src/mdast2docx/mdast-docx-anchors.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2023 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { visit } from 'unist-util-visit';
+import { toString } from 'mdast-util-to-string';
+import { slug } from 'github-slugger';
+
+class GHSlugger {
+  constructor() {
+    this.occurrences = {};
+  }
+
+  /**
+   * Generate a unique slug.
+   * @param  {string} value String of text to slugify
+   * @return {string}       A unique slug string
+   */
+  slug(value) {
+    let id = slug(value)
+      // remove leading numbers
+      .replace(/^\d+-+/, '');
+
+    // resolve collisions
+    const original = id;
+    while (id in this.occurrences) {
+      this.occurrences[original] += 1;
+      id = `${original}-${this.occurrences[original]}`;
+    }
+    this.occurrences[id] = 0;
+    return id;
+  }
+}
+
+export function buildAnchors(tree) {
+  const tracking = {};
+  const slugger = new GHSlugger();
+
+  const track = (url) => {
+    let ref = tracking[url];
+    if (!ref) {
+      ref = { links: [], heading: null, bookmark: null };
+      tracking[url] = ref;
+    }
+    return ref;
+  };
+
+  visit(tree, (node) => {
+    if (node.type === 'link' && node.url.startsWith('#')) {
+      const ref = track(node.url);
+      ref.links.push(node);
+      // special case: link to top of page
+      if (node.url === '#') {
+        // eslint-disable-next-line no-param-reassign
+        node.anchor = '_top';
+      }
+    } else if (node.type === 'link' && node.anchor) {
+      // eslint-disable-next-line no-param-reassign
+      node.type = 'bookmark';
+      track(`#${node.anchor}`).bookmark = node;
+    } else if (node.type === 'heading') {
+      const anchor = `#${slugger.slug(toString(node))}`;
+      track(anchor).heading = node;
+    }
+    return visit.CONTINUE;
+  });
+
+  const anchors = {};
+  Object.keys(tracking).forEach((k) => {
+    const ref = tracking[k];
+    if (ref.heading) {
+      // ms-word heading bookmark algorithm
+      const words = toString(ref.heading).split(/\s+/).slice(0, 3);
+      let anchor = `_${words.join('_')}`.substring(0, 36);
+
+      // resolve collisions
+      const original = anchor;
+      while (anchor in anchors) {
+        anchors[original] += 1;
+        anchor = `${original}${anchors[original]}`;
+      }
+      anchors[anchor] = 0;
+
+      ref.heading.anchor = anchor;
+      for (const link of ref.links) {
+        link.anchor = anchor;
+      }
+    } else if (ref.bookmark) {
+      const { anchor } = ref.bookmark;
+      for (const link of ref.links) {
+        link.anchor = anchor;
+      }
+    }
+  });
+}

package/src/mdast2docx/mdast-sanitize-html.js

@@ -29,6 +29,32 @@ function formatHandler(type) {
   };
 }
 
+/**
+ * @param {State} state
+ *   State.
+ * @param {Readonly<Element>} node
+ *   hast element to transform.
+ * @returns {Link}
+ *   mdast node.
+ */
+export function linkHandler(state, node) {
+  const properties = node.properties || {};
+  // Allow potentially “invalid” nodes, they might be unknown.
+  // We also support straddling later.
+  const children = /** @type {Array<PhrasingContent>} */ (state.all(node));
+
+  /** @type {Link} */
+  const result = {
+    type: 'link',
+    url: state.resolve(String(properties.href || '') || null),
+    title: properties.title ? String(properties.title) : null,
+    anchor: properties.name ?? properties.id,
+    children,
+  };
+  state.patch(node, result);
+  return result;
+}
+
 /**
  * removes paragraphs from the child nodes recursively.
  * @param  node
@@ -134,6 +160,7 @@ export default function sanitizeHtml(tree) {
         document: false,
         handlers: {
           ...defaultHandlers,
+          a: linkHandler,
           u: formatHandler('underline'),
           sub: formatHandler('subscript'),
           sup: formatHandler('superscript'),