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.