@adobe/helix-docx2md 1.1.4 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.2.0](https://github.com/adobe/helix-docx2md/compare/v1.1.4...v1.2.0) (2022-10-25)
+
+
+### Features
+
+* add support for document internal links and bookmarks ([#140](https://github.com/adobe/helix-docx2md/issues/140)) ([90bc3af](https://github.com/adobe/helix-docx2md/commit/90bc3afb3c05819ed285bb6deedf0fff89ba52b3)), closes [#134](https://github.com/adobe/helix-docx2md/issues/134)
+
 ## [1.1.4](https://github.com/adobe/helix-docx2md/compare/v1.1.3...v1.1.4) (2022-10-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-docx2md",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Helix library that converts word documents to markdown",
   "type": "module",
   "main": "./src/index.js",
@@ -37,6 +37,7 @@
     "@adobe/helix-shared-process-queue": "1.1.5",
     "@adobe/mammoth": "1.5.1-bleeding.1",
     "dirname-filename-esm": "1.1.1",
+    "github-slugger": "1.4.0",
     "mdast-util-to-markdown": "1.3.0",
     "mdast-util-to-string": "3.1.0",
     "remark-gfm": "3.0.1",
@@ -49,20 +50,20 @@
   },
   "devDependencies": {
     "@adobe/eslint-config-helix": "1.3.2",
-    "@adobe/helix-mediahandler": "1.2.6",
+    "@adobe/helix-mediahandler": "1.2.12",
     "@semantic-release/changelog": "6.0.1",
     "@semantic-release/exec": "6.0.3",
     "@semantic-release/git": "10.0.1",
     "c8": "7.12.0",
     "dotenv": "16.0.3",
-    "eslint": "8.24.0",
+    "eslint": "8.26.0",
     "eslint-import-resolver-exports": "1.0.0-beta.3",
     "eslint-plugin-header": "3.1.1",
     "eslint-plugin-import": "2.26.0",
     "husky": "8.0.1",
     "junit-report-builder": "3.0.1",
     "lint-staged": "13.0.3",
-    "mocha": "10.0.0",
+    "mocha": "10.1.0",
     "mocha-multi-reporters": "1.5.1",
     "semantic-release": "19.0.5",
     "unist-util-inspect": "7.0.1"

package/src/dast2mdast/dast2mdast.js

@@ -11,8 +11,10 @@
  */
 
 /* eslint-disable no-param-reassign */
+import { toString } from 'mdast-util-to-string';
 import one from './one.js';
 import handlers from './handlers/index.js';
+import IDSlugger from './id-slugger.js';
 
 /**
  * @typedef {Node} List
@@ -28,6 +30,11 @@ import handlers from './handlers/index.js';
  * Note: that the stack is reversed, i.e. the first is the deepest one.
  * @typedef {ListStack[]} ListContainers
  *
+ * @typedef Bookmark
+ * @property {string} name
+ * @property {Node} target
+ * @property {Node[]} links
+ *
  * Converts the docx AST to markdown ast.
  * @param {object} tree the docx ast
  * @param {object} opts options
@@ -62,9 +69,57 @@ export default async function dast2mdast(tree, opts = {}) {
   h.handlers = handlers;
   h.numbering = {};
   h.gridtables = opts.gridtables;
+  h.bookmarks = {};
 
   /** @type {ListContainers} */
   h.listContainers = [[]];
 
-  return one(h, tree, null);
+  /**
+   * @param {string} name
+   * @returns {Bookmark}
+   */
+  h.getBookmark = (name) => {
+    let bm = h.bookmarks[name];
+    if (!bm) {
+      bm = {
+        name,
+        target: null,
+        links: [],
+      };
+      h.bookmarks[name] = bm;
+    }
+    return bm;
+  };
+
+  const mdast = one(h, tree, null);
+
+  // process bookmarks. note that we _should_ re-slug them after the headings are sanitized in
+  // mdast2md. another option would be to keep the `bookmark` nodes in the mdast and only
+  // process them in mdast2md. but then, the dast2mdast would produce non standard mdast.
+  let slugger;
+  for (const bm of Object.values(h.bookmarks)) {
+    if (!bm.target) {
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+    if (!slugger) {
+      slugger = new IDSlugger();
+    }
+    // if heading, create an ID from its text
+    if (bm.target.type === 'heading') {
+      const text = toString(bm.target).trim();
+      bm.id = slugger.slug(text || 'heading');
+      bm.target.id = bm.id;
+    } else {
+      // create an anchor node for non-heading bookmarks
+      bm.id = slugger.slug('bookmark');
+      bm.target.type = 'html';
+      bm.target.value = `<a id="${bm.id}"></a>`;
+    }
+    // adjust all links uris to the id
+    for (const link of bm.links) {
+      link.url = `#${bm.id}`;
+    }
+  }
+  return mdast;
 }

package/src/dast2mdast/handlers/bookmark.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2019 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.
+ */
+
+/**
+ * Bookmarks are inserted by word when one creates a document internal link. At this point they
+ * are just remembered. If they are a child of a heading node it will later be adjusted to
+ * reflect the expected ID of that heading (by slugging the heading text). if they are just normal
+ * paragraph bookmarks, they will later be turned into an anchor link.
+ */
+export default function bookmark(h, node) {
+  const bm = h.getBookmark(node.name);
+  bm.target = h('bookmark', node.name);
+  bm.target.bookmark = bm;
+  return bm.target;
+}

package/src/dast2mdast/handlers/hyperlink.js

@@ -12,8 +12,18 @@
 import all from '../all.js';
 
 export default function hyperlink(h, node) {
-  return h('link', {
+  const link = h('link', {
     url: node.href || '',
     title: node.title,
   }, all(h, node));
+
+  // document internal links will have an `anchor` property and are managed as bookmarks
+  // after the document is processed, the uris will be adjusted to point to the correct bookmark id.
+  if (node.anchor) {
+    // only bookmark links have anchors
+    const bm = h.getBookmark(node.anchor);
+    bm.links.push(link);
+  }
+
+  return link;
 }

package/src/dast2mdast/handlers/index.js

@@ -20,6 +20,7 @@ import tableRow from './table-row.js';
 import tableCell from './table-cell.js';
 import text from './text.js';
 import run from './run.js';
+import bookmarkStart from './bookmark.js';
 
 export default {
   document,
@@ -32,4 +33,5 @@ export default {
   tableRow,
   tableCell,
   image,
+  bookmarkStart,
 };

package/src/dast2mdast/handlers/paragraph.js

@@ -172,8 +172,15 @@ export default function paragraph(h, node, parent, siblings) {
     if (toString(nodes).trim() === '---') {
       return h('thematicBreak');
     }
-    // sanitize children
-    return h('heading', { depth }, nodes);
+    const heading = h('heading', { depth }, nodes);
+    // check if any of the children is a bookmark
+    const idx = nodes.findIndex((n) => n.type === 'bookmark');
+    if (idx >= 0) {
+      // replace the bookmark node  with this heading and remove the child
+      nodes[idx].bookmark.target = heading;
+      nodes.splice(idx, 1);
+    }
+    return heading;
   }
 
   // check for codeblock

package/src/dast2mdast/id-slugger.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2022 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 GithubSlugger from 'github-slugger';
+
+export default class IDSlugger {
+  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 = GithubSlugger.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;
+  }
+}