Demo conversion (Markdown)

>>>>> gd2md-html alert: ERRORs: 0; WARNINGs: 2; ALERTS: 6.

See top comment block for details on ERRORs and WARNINGs.
In the converted Markdown or HTML, search for inline alerts that start with >>>>> gd2md-html alert: for specific instances that need correction.

Links to alert messages:

alert1 alert2 alert3 alert4 alert5 alert6

>>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.

This is a raw conversion from a Google Doc (link to original Google Doc).

gd2md-html sample/demo doc

This page demonstrates the features of gd2md-html conversion from a Google Doc to a simple Markdown or HTML file.

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.

[TOC]

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

Headings

gd2md-html converts headings to the corresponding heading level in Markdown or HTML. If you use a lot of Heading 1 headings in your Doc, but you want to adhere to the HTML convention of only a single H1 heading per page, you can use the Demote headings option.

Heading IDs

If you generate a table of contents in your Doc, gd2md-html will create IDs for each heading. If your Markdown environment does not handle heading attributes, you can chose the HTML headings/IDs option.

Note that some Markdown environments strip heading IDs and generate their own.

Basic paragraphs

This is a paragraph.[^1] (gd2md-html also supports footnotes) A sentence with some embedded code. gd2md-html removes "smart quotes" from text and code to guard against cut-and-paste errors.

Mixed code spans

gd2md-html uses Markdown for most inline code, but it will also handle mixed code spans like this: $ ls -l filename, by using HTML markup.

Lists

gd2md-html supports numbered lists, ordered lists, and definition lists.

Numbered lists

Note: simple nested lists now work in both Markdown and HTML:

Here is a numbered list:

Outer list: Item one.
Outer list: Item two.
1. Nested list: Item one.
2. Nested list: Item two.
  1. Doubly-nested: Item one.
Outer list: Item three.
Outer list: Item four.

Ordered lists

Note: simple nested lists now work in both Markdown and HTML:

And here is a bullet list:

A list item without any punctuation
- A nested list item.
  - A doubly-nested list item.
A list item with an embedded command: ps aux | grep conky | grep -v grep | awk '{print $2}' | xargs kill
Some mixed-font code: ls -l filename. Followed by some normal text.

Lists with code blocks

You can have a code block within a list item, as long as you indent the code (in the Doc) the same amount as the list:

A text item, followed by a code block that's indented and should be part of this item:
```
// A comment.
some code;
  callFunction();
```
Another item.
- A nested list item with a command:
```
$ cat file | grep dog | wc
```

Lists with embedded paragraphs

Note: Works for Markdown, still a known issue for HTML.

A bullet list with an additional paragraph:

This is another paragraph.

This is a new paragraph, but also part of this list item. It should be indented
Another item.
- A nested item.
  
  This is a new paragraph within the nested item.
```
// Some code after a nested paragraph.
callSomeFunction();
```
Another list item.
And another.
- Nested
  
  A paragraph within a list item.
  - Nested
    
    A paragraph within a list item.
- Reducing the nesting level.
First-level list item.

A regular paragraph.

Definition lists

Because Google Docs does not have a definition list element, gd2md-html uses a simple but explicit syntax that is similar to the kramdown syntax for definition lists:

?term on a line by itself (starting with a question mark)
:Definition preceded by a colon.

Definition list examples

? term
: Definition here.

?term1
?term2
: First paragraph of definition.
: Second paragraph of definition.

renders as:

term : Definition here.

term1 term2 : First paragraph of definition. : Second paragraph of definition.

A term that has some crazy formatting and characters (not recommended)//. : Definition of crazy term.

But a definition term cannot be empty:

?

>>>>> gd2md-html alert: Definition ↓↓ outside of definition list. Missing preceding term(s)?
(Back to top)(Next alert)
>>>>>

: Empty term above causes an error here.

Code blocks

A code block (note that by default, gd2md-html does not add language descriptors to code blocks, but see Code Blocks with lang specification):

package main

import "fmt"

func main() {
	fmt.Println("Hello, 世界")
}

A single-cell table also becomes a code block:

#include<stdio.h>
main()
{
    printf("Hello World");
}

If you have any smart quotes in "code" or code blocks, gd2md-html removes them during the conversion:

func main() {
	fmt.Println("Why would you do this?")
}

Code blocks with lang specification

gd2md-html supports an optional lang specification on the first line of the code sample (in the Doc source). The syntax is: lang: langspec

For example, here is a code block that specifies lang:c on the first line:

#include<stdio.h>
main()
{
    printf("Hello World");
}

This also works in single-cell tables: here is a single-cell table that specifies lang: java on the first line:

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

Tables

gd2md-html generates HTML tables.

A table:

Some text.	`some code` `var i = 0;`
More text.	A list: mozzarella cheese

You can also merge columns and rows in tables:

This row merges the first three columns. one			four
one	two	These two rows are merged three	four
one	two	These two rows are merged three	four

Links

Some regular URL links:

Some links with titles:

Images

A plain image:

>>>>> gd2md-html alert: inline image link here (to images/html-sample0.png). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

alt_text

Note that the image link will be broken until you store the image file on your server and adjust the path and width if necessary.

Alternatively, you can use a Drawing to display an image. Here's an example where we've pasted the image into a Drawing and referenced it after converting the doc:

>>>>> gd2md-html alert: inline image link here (to images/html-sample1.jpg). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

alt_text

Tip: You can limit the width of an image in Markdown by adding (for example) {width="75%"} after the link markup (if your Markdown engine supports such syntax). For HTML, just add a width="75%" attribute to the img tag.

Drawings

Google Docs does not provide an API for accessing the data in a Google Drawing. If you have an inline drawing, gd2md-html will warn and provide an alert in the converted output:

>>>>> gd2md-html alert: inline drawings not supported directly from Docs. You may want to copy the inline drawing to a standalone drawing and export by reference. See Google Drawings by reference for details. The img URL below is a placeholder.
(Back to top)(Next alert)
>>>>>

drawing

You can display Google Drawings (and images in Drawings) by reference. See Google Drawings by reference for details.

Here's an example where we've referred to a drawing by reference (after converting):

>>>>> gd2md-html alert: inline drawings not supported directly from Docs. You may want to copy the inline drawing to a standalone drawing and export by reference. See Google Drawings by reference for details. The img URL below is a placeholder.
(Back to top)(Next alert)
>>>>>

drawing

Tip: For any drawing that you display by reference, be sure to change the permissions to make it viewable by anyone with the link.

Equations

If you insert an equation using Google Docs, gd2md-html will warn and insert an alert message in the output. However, if your target publishing platform supports LaTeX equations, you can use LaTeX syntax directly.

A Google Docs equation:

>>>>> gd2md-html alert: equation: use MathJax/LaTeX if your publishing platform supports it.
(Back to top)(Next alert)
>>>>>

A LaTeX equation:

$$e^{i\pi } = -1$$

renders as:

$$e^{i\pi } = -1$$

Right-to-left text

A few Arabic words هذه فقرة تجريبية inside an English paragraph:

They should appear as in this RTL paragraph:

هذه فقرة تجريبية

Subscript and superscript processing

A sentence with _subscript and ^superscript and some more regular text and ^{a link to Google}.

And more _bold and ^{mixed bold italic code} and some more text. Some italic text.

Another paragraph with some bold text.

^SUPA subscript or superscript at the beginning or end of a paragraph should not break things:_SUB

A numbered list following a terminal subscript.
Another list item.

Bugs

Current open bugs: https://github.com/evbacher/gd2md-html/issues
New bug or feature request: https://github.com/evbacher/gd2md-html/issues/new. Thanks for helping to make gd2md-html better!

Notes

[^1]: gd2md-html supports footnotes!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly