Ed Bacher edited this page Oct 1, 2018 · 79 revisions

GD2md-html: convert a Google Doc to Markdown or HTML

(link to original Google Doc)

GD2md-html quick start:

  1. Install GD2md-html from the Chrome web store.
  2. From the Google Docs Add-ons menu in a Google Doc, select GD2md-html > Convert.
  3. Use the Markdown or HTML buttons in the sidebar window to convert your document to either Markdown or HTML.
  4. Copy the entire text from the text area in the sidebar to the clipboard and paste it into either a Markdown or HTML file.
  5. View the rendered page using a web browser or your publishing tools.

Details

GD2md-html is a free Google Docs add-on that converts a Google Doc to a simple, readable Markdown or HTML text file. GD2md-html lets you use Google Docs' editing, formatting, and collaboration tools before you publish to a Markdown or HTML platform. GD2md-html also lets you select and convert part of a Google Doc.

GD2md-html requires minimal permissions: it will ask for permission to access the current Doc (to convert it) and permission to create a sidebar (the user interface). It requires no other permissions.

Note: Not all Markdown renderers support all Markdown features. For example github Markdown does not support a table of contents ([TOC]), footnotes, or definition lists. Also, some Markdown environments strip heading IDs and replace them with their own generated IDs. You'll have to do some manual adjustments, depending on your target environment.

If you find any bugs, please file them at https://github.com/evbacher/gd2md-html/issues. Thanks for helping to make GD2md-html better.

Join the GD2md-html group group for announcements, questions, and discussion about GD2md-html. Low traffic.

Thanks to Renato Mangini for inspiration: he created the conversion script at https://github.com/mangini/gdocs2md before Drive add-ons even existed!

Contents:

Installing GD2md-html

Install GD2md-html from the Google Docs add-on store.

Using GD2md-html

You can use the GD2md-html add-on with any Doc for which you have edit permission. If you only have view permission, make a copy.

  1. From the Google Docs Add-ons menu, select GD2md-html > Convert. The sidebar window opens:

    GD2md-html sidebar

  2. Use the Markdown or HTML buttons in the sidebar window to convert your document to either Markdown or HTML. If you select part of the document, GD2md-html will convert only the selection. Otherwise it will convert the entire document. Click the Docs link for more information.

Options

  • Demote headings (H1 → H2, etc.): If you have used multiple Heading 1 headings in your Doc, choose this option to demote all heading levels to conform with g3doc standards (single H1 as title, H2 as top-level heading in the text body).
  • HTML headings/IDs: Not all Markdown renderers handle Markdown-style IDs. If that is the case for your target platform, choose this option to generate HTML headings and IDs.
  • Wrap HTML: By default, HTML output is not wrapped. Selecting this option will wrap HTML text (but note that some publishing platforms treat line breaks as <br> or <p> tags).

Using GD2md-html output

To use the output, copy the entire text to the clipboard and paste it into either a Markdown or HTML file.

If there are any errors or warnings during the conversion, they will appear in the conversion notes comment at the top of the text output.

Images

GD2md-html creates placeholder markup for images. You will need to move images to your server and change the path in the image tags to match the image location.

Drawings

The converter cannot handle inline Google Drawings, since Google Drawings does not (yet) have an API to get drawing data. However, you can copy embedded drawings to standalone Google Drawings and refer to them by reference in your Markdown or HTML documents (see Google Drawings by reference for details).

Features

Text element conversion features

Support for both Markdown and HTML conversion, unless noted.

  • Basic elements: Paragraphs, lists, inline code, links.

  • Text formatting: italic, bold, strikethrough, inline code, and combinations of text formatting.

  • Headings: Heading levels convert directly, unless you choose the option to demote heading levels.

  • Line breaks: If you use shift-enter to insert an explicit line break, the converter will preserve that line break, inserting a \ at the end of the line for Markdown, or <br> for HTML.

  • Intra-document links: If you linked to headings in your Doc, those links will convert properly as long as you generated a TOC.

  • Mixed inline code: GD2md-html may fall back to HTML to handle mixed code spans in normal text properly.

  • Definition lists: GD2md-html supports simple definition lists. See the sample doc for details and examples:

    Definition list syntax (in a Google Doc):
    
    ?Term starts with a question mark.
    :Definition here (starts with a leading colon).
    
  • Code blocks: Constant-width-font paragraphs and single-cell tables convert to fenced code blocks (Markdown) or <pre> blocks (HTML).

  • Code block language specification: You can optionally specify the language for a code block by specifying lang: langspec as the first line. For example this code block (in your Google Doc):

    lang:java
    public class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World");
        }
    }
    

    renders as:

    public class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World");
        }
    }

    This applies to both constant-width-font paragraphs and single-cell tables.

  • Tables: Tables currently convert to HTML tables for both Markdown and HTML. Full support for merged rows and columns.

  • Images: GD2md-html creates image links. You will need to save images to your web server and adjust the image paths.

  • Footnotes: Footnotes convert to standard Markdown footnotes, and corresponding markup in HTML.

  • Right-to-left languages: Embedded RTL text or RTL paragraphs display properly in the converted output.

UI/reporting features

  • Partial selections: If you select part of the document, GD2md-html will convert only the selection. Otherwise it will convert the entire document. This is useful for converting code samples or tables.
  • ERRORs, WARNINGs, ALERTs: GD2md-html output includes information about conditions that will probably require your attention (both in a comment at the top of the output and in red in the rendered output). Please proofread and correct before publishing.

Sample conversion

Both this document and the sample/demo page were converted from Google Docs using GD2md-html.

Troubleshooting

If you find trouble that's not noted here, please file a bug at GD2md-html bugs.

Conversion error

If a conversion fails completely, file a bug against the converter at GD2md-html bugs. Be sure to include the error message and a link to the document you were trying to convert.

TIP: You can do a crude sort of binary search to localize the problem by selecting the first half of the doc and converting. Change and/or reduce the selection until you find the offending portion of the document. You may be able to work around the problem, but please still file a bug! (And note the area of the problem if you localized it. Thanks!)

Alerts

Problem

Red marks all over the page.

GD2md-html alerts you to known issues, warnings, or errors that require your attention by inserting alert messages in the rendered output. For example, if you use a Google Docs equation, you'll get a message like this:

>>>>> equation: use MathJax/LaTeX if your publishing platform supports it.

Solution

Address the problem and remove the message from the Markdown/HTML file before publishing.

Heading IDs not generated

Problem

GD2md-html does not generate heading IDs and intra-document links properly if you're using a Doc that has the new-style TOC (with page numbers). Currently, GD2md-html requires the old-style ("blue links") TOC to correctly generate heading IDs and intra-document links.

Solution

Delete your TOC and insert a new TOC (choose the "blue links" style).

Alternate solution (in case the "blue links" style TOC is not available):

Find an old Doc that has the old-style TOC.

Cut and paste the entire TOC (not just the links -- you need to get the whole box) into your Doc, then regenerate the TOC. The promise is to have the TOC be selectable, but for now, the print-style TOC is the default for new Docs, it seems.

Problem

The conversion notes contains an error like this:

ERROR:
undefined internal link to this URL"#heading=h.64x194v1qq35".link text: link to an internal heading
?Did you generate a TOC?

Solution

First, check to see that you generated a table of contents (TOC) in your document. The conversion engine uses the TOC to create internal links. (Also, the TOC should come before any link references.)

If you generated a TOC and you are still getting internal link errors, the heading link in the original TOC may be stale. Try regenerating the TOC in your Google Doc, then convert the document again.

To check for staleness: search through the converted output for the link URL (something like #heading=h.vwl3eupkcsuz). When you find it, go back to the doc and see if that link works in the doc itself (by appending #heading=h.vwl3eupkcsuz or similar to the end of the doc URL).

Permissions

The GD2md-html add-on does not collect or distribute any information about you or about the documents being converted.

GD2md-html will ask for permission to access the current Doc (to convert it). GD2md-html reads the Doc content and structure; it does not change any content.

GD2md-html will also ask for permission to display a sidebar. It uses the sidebar to display action buttons and option checkboxes as well as the converted text (Markdown or HTML).

It requires no other permissions.

See the official privacy policy for GD2md-html here: https://sites.google.com/site/edbacher/home/gd2md-html-privacy-policy.

Bugs

Go to https://github.com/evbacher/gd2md-html/issues to view open bugs or to file a new bug.

Acknowledgements

This add-on was inspired by the work of Renato Mangini at https://github.com/mangini/gdocs2md, who created gdocs2md before Drive add-ons existed!

See also

See these links for more information about Markdown syntax and standards, and about Markdown previewers and editors.

Markdown previewers, editors

Markdown syntax, standards information

Articles about GD2md-html

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.