Skip to content

Latest commit

 

History

History
312 lines (162 loc) · 16.6 KB

homepage.md

File metadata and controls

312 lines (162 loc) · 16.6 KB
Raw

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

[the add-on formerly known as GD2md-html]

(link to original Google Doc)

Contents:

Docs to Markdown quick start:

  1. Install Docs to Markdown from the G Suite Marketplace. Or: Install Docs to Markdown from the Chrome web store (which is soon to be deprecated).
  2. From the Google Docs Add-ons menu in a Google Doc, select Docs to Markdown > 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

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

Docs to Markdown 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 Docs to Markdown better.

Join the GD2md-html group group for announcements, questions, and discussion about Docs to Markdown (formerly GD2md-html). Low traffic.

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

Installing Docs to Markdown

Install Docs to Markdown from the G Suite Marketplace. Or: Install Docs to Markdown from the Chrome web store (which is soon to be deprecated).

Using Docs to Markdown

You can use the Docs to Markdown 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 Docs to Markdown > 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, Docs to Markdown 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 the following standard: single H1 as title, H2 as top-level heading in the text body. You may need to add an H1 to function as the title after conversion.
  • 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).
  • Allow HTML tags: [Note: this option currently has no effect.] By default, angle brackets (<) will be replaced by the &lt; entity. If you really want to embed HTML tags in your Markdown, select this option to preserve them. Or, if you just want to use an occasional HTML tag, you can escape the opening angle bracket like this: \\<tag>text\\</tag>.

Using Docs to Markdown 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

Docs to Markdown 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: Docs to Markdown may fall back to HTML to handle mixed code spans in normal text properly.

  • Definition lists: Docs to Markdown supports simple definition lists.

    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: Docs to Markdown 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, Docs to Markdown will convert only the selection. Otherwise it will convert the entire document. This is useful for converting code samples or tables.
  • ERRORs, WARNINGs, ALERTs: Docs to Markdown 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 Docs to Markdown.

Troubleshooting

If you find trouble that's not noted here, please file a bug at Docs to Markdown bugs.

Conversion error

If a conversion fails completely, file a bug against the converter at Docs to Markdown 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.

Docs to Markdown 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

Docs to Markdown 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, Docs to Markdown 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.

ERROR: undefined internal link

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 Docs to Markdown add-on does not collect or distribute any information about you or about the documents being converted.

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

Docs to Markdown 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 Docs to Markdown 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 Docs to Markdown (GD2md-html)