Google Docs Converter
Command Line app to convert Google Docs documents into Markdown or Org plain text formats.
Google Docs Converter (gconv) is a command line utility that takes a Google Docs URL and converts the document into either Markdown or Org Mode formats. It's written in Typescript for Node.js and requires a credentials.json file from your Google Developer account.
OS X & Linux
npm install -g google-docs-converter
You'll also need to place a
credentials.json file from your Google Developer Account in the folder
You can generate the correct credentials using the Google Cloud Console. Create a project, enable the Google Docs API (readonly is fine), and create OAUTH credentials for a Web application with the authorized URI redirect
http://localhost:3000/oauth2callback. You may also want to put the project into "Testing" mode and authorize your own email address to cut down on warnings from Google about using an unverified project. Then download those credentials, rename the file to
credentials.json and move it to
After you have the credentials, when you try to use the CLI for the first time, a web browser window will open and ask you to authorize read-only access to your Google Docs.
This app was created because I often work in Google Docs with a partner, but when I'm writing alone, I prefer to write in plain text markup formats like Markdown and Org Mode. This utility makes it easy for me to quickly convert a Google Doc into one of those formats and start editing.
Usage: gconv [options] <Google Docs URL> Options: -V, --version output the version number -f, --format <format> Format for conversion: markdown, loose-markdown, org, fountain (default: "loose-markdown") -j, --json <jsonFile> Pass Google Docs JSON as file -h, --help display help for command
Google Docs Converter will output the conversion into the console, where you can then pipe it into another utility or redirect it into a file.
gconv -f org http://docs.google.com/blahblah > my-file.org
NOTE: Google Docs URLs can sometimes include ampersands, question marks, and other characters that may trigger unwanted behavior in your terminal. You may want to surround the URL with quote marks
'' to protect against this.
For debugging purposes, you can use the -j flag to pass a local JSON file representing the Google Docs file you wish to convert. The Google Docs JSON format is documented here.
Google Docs Converter supports a subset of Markdown reflecting the basic elements of a document: headers, lists, links, and styled text (bold, italic, etc.).
There are three Markdown flavors currently offered:
- Regular Markdown (
markdown) tries to follow the original John Gruber Markdown spec. It will attempt to use HTML tags to reflect things like strikethroughs and underlines in a Google Doc.
- Github Flavored Markdown (
gfm) is identical to Regular Markdown except it supports Github's strikethrough markup (
- Loose Markdown (
loose-markdown) is less faithful to the original Google Doc, ignoring strikethroughs and converting underlines into italics. It's the default because this is usually what I want.
- Fountain (
fountain) ignores bold, italic, and underline, bringing in only headings and links. It's useful if you'd rather write out markdown styles in Google Docs rather than use rich text.
Google Docs Converter currently supports the following Org Mode elements: headings, lists, links, bold text, italic text, underline text, and strikethrough text.
Not Currently Supported
- Centered text
- Horizontal Rules (e.g.
- Complex, overlapping styled text (bold text inside italic, etc)
- Version 2.0.1: Updating README instructions.
- Version 2.0.0: Updating dependencies and Google Auth code to current best practices.
- Version 1.2.2: Updating dependencies to include bugfixes.
- Version 1.2.1: Fixed bug where documents with images or footnotes wouldn't parse. Images and footnotes are not currently supported and are now just skipped.
- Version 1.2.0: Adding Fountain output option which doesn't translate bold, italic, and underline rich text.
- Version 1.1.5: Exporting Parser and Markdown so they can be imported into other Node projects. Fixing bugs introduced by that change.
- Version 1.0.2: Fixing bug with command line argument parser.
- Version 1.0.0: Initial release.
This app uses the Google Docs API v1.