No magic
Stanislav Dombrovsky
Stanislav Dombrovsky Follow
Mobile Developer in the past. Former product manager in AppCode. Engineer.
· 7 min read

Export to HTML addon

This addon is open-sourced - see it here.

What is it?

Google Docs addon that converts Google Doc to simple HTML that can be used in various blogs.

Installation

To install this addon, navigate here

Versions <= 48 were deployed to the Chrome Web Store, as it was required by Google for Google Docs addons. Newer versions are deployed to the G-Suite Marketplace, as it’s required by Google now. Old installations should be automatically updated to newer versions starting from 07.05.2020.

Migration

Versions <= 52 updated to the latest version:

  1. You do hot have any custom templates in g2html_settings.json file:
    • Close all opened Google Documents
    • Open Google Drive and search for g2html_settings.json file
    • Delete it
  2. You have some custom templates in g2html_settings.json file:
    • Close all opened Google Documents
    • Open Google Drive and search for g2html_settings.json file
    • Download it from the Google Drive
    • Delete it on Google Drive
    • Open any Google Document and perform a single conversion.
    • Add your custom templates to the newly created g2html_settings.json file.

Without these steps [html][/html] tags added in version 52 won’t work.

Configuration and folders

This addon automatically creates the following files and folders:

  • G2HTML folder to store generated HTMLs (so you can download them as a single file if you don’t want to copy HTML contents via “Copy to clipboard” button)
  • g2html_settings.json file where all addon settings are stored and custom replacements can be configured (see the Customization section below).

Markup reference

  1. Text with Consolas font = <code>text</code>
  2. [d]Title[/d] = <p><a class="jb-download-button" href="some url"><i class="download-icon"></i>Title</a></p>. Change some url to your IDE’s download url in g2html_settings.json.
  3. [e]http://youtube_link[/e] = <iframe width="560" height="315" src="http://youtube_link" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  4. [more] = <!--more-->
  5. Select image → ⌘⌥Y → Set Alt or Description for image = alt attribute for image.
  6. Select image → ⌘K → Set link = src attribute of the image having this link.
  7. [html]<html part>[/html] = <html part> part inserted into rendered HTML without any changes. Great for a custom markup.

Tip: you can define your own tags, see the Customization section below.

Working with images

The following workflow should be used to deal with images inside the Google Doc to use this addon efficiently:

  1. Upload various images to have final links
  2. Insert them to Google Doc
  3. Set alt and image link using the approach from Markup reference section
  4. For GIFs: have the same name and links for the GIF preview and the GIF itself, e.g. upload them at the same time. Set only link to the GIF image itself and turn on Generate | Gifs in settings. After that, GIF player markup will be generated automatically.

General workflow

  1. Write the Google Document
  2. Execute Add-ons → Export to HTML → Convert
  3. Change settings if needed and press “Convert”
  4. Empty warnings / errors list is displayed if everything is OK
  5. List with warnings/errors is displayed if there are some problems. Click the warning or error description to navigate to the place in the document and fix it. Navigation uses bookmarks to jump to the specific place in the document (there is no other way to implement it), and as soon as warning / error is fixed, corresponding bookmark is removed.
  6. As soon as all problems are fixed, copy rendered HTML to clipboard and paste it to the blog post.

Toolbar controls (from left to right)

  1. Re-run conversion with previously selected settings
  2. Copy generated HTML to clipboard
  3. Clear all bookmarks, warnings and errors
  4. Open settings
  5. Help link

Settings

Generation

  1. Paragraphs - wrap each paragraph in <p></p>.
  2. id attributes for headings - automatically generate id attribute for h tags based on the tag content. You can add your own custom regexps for transforming heading content into id in idtemplates sections in g2html_settings.json file.
  3. Images - generate image markup for images in Google Document.
  4. Gifs - generate specific markup for GIFs (preview, JB-specific site markup), see Working with images section.

Transform

  1. Always make image width /= 2 - useful when you don’t have images with @2x postfix.
  2. Limit max image width to - limits max image width to the specified value.

Inspections

  1. Image alts - check if each and every alt image attribute is not empty
  2. 404 errors (slow) - tries to load the content for each url in the document (including images) and reports if there is a problem with loading the content.
  3. Marketing tokens in links (UTMs, etc) - checks for various marketing tokens in URL and warns you (since you don’t need them in original text)
  4. Empty links - shows errors for empty links.
  5. TODOs - shows warning for every text or link containing TBD. Tip: if you don’t want to insert the link to some resource right now, enter “TBD” instead of the URL.
  6. Shortcuts - detect shortcuts that do not have “Consolas” font (<code> tags) set.
  7. Multiple spaces - detect several spaces instead of a single one in text.
  8. Title Case - checks document title for so-called “Title Case” rules and suggests a correct title

Behavior

  1. Always open settings before conversion - by default addon does not show the Settings screen when making a document conversion. This option forces it to always show this screen.

Customization

To customize any settings that are not visible in the addon UI, download the g2html_settings.json, edit it and replace your current settings file with it. After that addon should use your own settings.

Settings reference

Generate

  1. paragraphs. Value: true or false. Stores Paragraphs option.
  2. heading_ids. Value: true or false. Stores id attributes for paragraphs.
  3. gifs. Value: true or false. Stores Gifs option.
  4. generate_images. Value: true or false. Stores Images option.

Transform

  1. transform_image_width. Value: true or false. Stores Always make image_width /= 2 option.
  2. max_image_width. Value: integer, 800 by default. Stores Limit max image width to option.

Inspections

  1. image_alts. Value: true or false. Stores Image alts option.
  2. url_tokens. Value: true or false. Stores Marketing tokens in links (UTMs, etc) option.
  3. fetch_links. Value: true or false. Stores 404 errors (slow) option.
  4. empty_links. Value: true or false. Stores Empty links option.
  5. tbd. Value: true or false. Stores TODOs option.
  6. shortcuts. Value: true or false. Stores Shortcuts option.
  7. spaces. Value: true or false. Stores Multiple spaces option.
  8. title_case. Value: true or false. Stores Title Case option.
  9. open_settings_on_start. Value: true or false. Stores the behavior option.
  10. idtemplates. Array of templates for replacing certain characters for header id attribute. Each template has the following format: 
    {
    "regexp": "c\\+\\+", //escaped RegExp
    "replacement": "cpp" //text to insert instead of characters matched by regexp
}
  11. templates. Array of templates for text transformations. First accepted template format: 
    {
    "attributes": {
        "LINK_URL": true
    },
    "replacement": "<a href=\"LINK_URL\">$TEXT$</a>"
}

    Each text element in the Google Docs a) contains a text b) has some markup attributes (background color, foreground color, font family etc). attributes map contains key-value pairs. The key is one of the text attribute names. Value is the value of this attribute. <attribute>:null pair means that there should be no such attribute for the text. replacement is the replacement markup to be inserted into the HTML. The $TEXT$ variable contains the text of the text element. You can use various text attributes in the markup. To do that, just insert the text attribute name.

    In the example above, we match all the text elements having non-empty link (LINK_URL attribute). In the resulting HTML, each of such elements is wrapped in <a> tag with a link from the LINK_URL attribute.

    Second accepted template format:

    {
    "regexp": "\\[d\\](.*)\\[\\/d\\]",
    "replacement": "<p><a class=\"jb-download-button\" href=\"some url\"><i class=\"download-icon\"></i>$1</a></p>"
}

    regexp is a regular expression that matches the text of the text element. Nothing else, no attributes are accepted here. You can define matcher groups and use them inside the replacement attribute. Example below shows how we can use the following custom text in our Google Document:

    [d]Download My IDE![/d]

    This text is transformed into the following HTML markup:

        <p><a class="jb-download-button" href="some url"><i class="download-icon"></i>Download My IDE!</a></p>

    Suggestion: as some typical text elements (like links) are handled by the general parser logic, it’s not recommended to alter them via templates for now. There is no easy way to simplify the example above - the only way to have the correct template for you is to configure it once for your product.

Checklist for custom templates:

  1. Check regexp escaping.
  2. Check if your json is valid at all.
  3. If something does not work, please ping me.

Limitations

Sometimes bookmarks generated for errors are not removed from the document because of Google Docs bug.

Third-party libraries

  1. ImgApp
  2. GoogleDoc2Html - borrowed initial version from here.

Note about privacy policy

This page has Disqus comments and you may be confused that the link “Disqus’ Privacy Policy” is a privacy policy for “Export to HTML” addon. No, it’s a privacy policy of a comment block on the webpage. It’s not the privacy policy of the “Export to HTML” addon. Here is the privacy policy for “Export to HTML” addon.

addons