Description

Converts the JSON representation of a Google Docs document into an HTML abstract syntax tree (HAST) which can be serialized to HTML or converted to Markdown.

Note: This library does not intend to match the rendering by Google Docs.

Install

Install using NPM or similar.

npm i @googleworkspace/google-docs-hast

Usage

import { toHast } from "@googleworkspace/google-docs-hast";

// Retrieve document from API, https://developers.google.com/docs/api
const doc = ...;

// Convert the document to an HTML AST.
const tree = toHast(doc);

To get the serialized representation of the HTML AST, use the rehype-stringify package.

import { unified } from "unified";
import rehypeStringify from "rehype-stringify";

// Convert the document to an HTML string.
const html = unified()
  .use(rehypeStringify, { collapseEmptyAttributes: true })
  .stringify(tree);

Images

All <img> elements should be post-processed as the src attribute is only valid for a short time and is of the pattern https://lh6.googleusercontent.com/....

import { visit } from "unist-util-visit";

visit(tree, (node) => {
  if (node.type === "element" && node.tagName === "img") {
    const { src } = node.properties;
    // download, store, and replace the src attribute
    node.properties.src = newSrc;
  }
});

Named styles

Named styles are converted to an HTML element matching the following table.

| Named Style | HTML | | ----------- | ----------------------------- | | Title | <h1 class="title"></h1> | | Subtitle | <p class="subtitle"></p> | | Heading 1 | <h1 class="heading-1"></h1> | | Heading 2 | <h2 class="heading-2"></h2> | | Heading 3 | <h3 class="heading-3"></h3> | | Heading 4 | <h4 class="heading-4"></h4> | | Heading 5 | <h5 class="heading-5"></h5> | | Heading 6 | <h6 class="heading-6"></h6> | | Normal Text | <p class="normal-text"></p> |

Text styles

Text styles are converted to an HTML element: <i>, <strong>, <s>, <sub>, <sup>, and <u>.

If there is no direct mapping, a <span> with CSS is used to support features such as text color and font. This can be disabled with { styles: false }.

Anchor links

Header IDs are in the form id="h.wn8l66qm9m7y" when exported from the Google Docs API. By default, header tag IDs are updated to match their text content. See github-slugger for more information on how this is done.

For example, the following html:

<h1 class="heading-1" id="h.wn8l66qm9m7y">A heading</h1>

becomes:

<h1 class="heading-1" id="a-heading">A heading</h1>

This can be disabled with { prettyHeaderIds: false}.

const tree = toHast(doc, { prettyHeaderIds: false });

Unsupported Features

Some features of Google Docs are not currently supported by this library. This list is not exhaustive.

| Type | Supported | Bug | | ----------------------------------------------------------------------------- | --------- | --- | | Styles applied to embedded objects including borders, rotations, transparency | ❌ | | | documentStyle including pageSize, margins, etc | ❌ | | | namedStyles ( only added as class name on the appropriate tag ) | ❌ | | | Page numbers | ❌ | | | Page breaks | ❌ | | | Equations | ❌ | | | Columns | ❌ | | | Suggestions | ❌ | | | Bookmarks | ❌ | |

Note: This library does not intend to match the rendering by Google Docs.

This is not an official Google product.