Skip to content

Latest commit

 

History

History
118 lines (54 loc) · 7.1 KB

dev.md

File metadata and controls

118 lines (54 loc) · 7.1 KB
Raw

Developer guide: contributing to Docs to Markdown

Docs to Markdown is a Google Docs add-on that converts a Google Doc to simple, readable Markdown or HTML.

Note: This is my first big open-source project, so I’m still figuring it out. If you have any suggestions, please file a bug or feature request.

The spirit of Docs to Markdown

Docs to Markdown is meant to provide a simple conversion from Google Docs text content to Markdown. While Markdown is the primary target, because we sometimes need to convert things to HTML (like tables), we also provide a secondary HTML target.

Docs to Markdown is a filter

Docs to Markdown converts the text in your Google Doc to either Markdown or HTML. It is a filter only: that is, it creates Markdown or HTML output based on the content in your Google Doc. It does not change anything in the source document.

No fancy formatting

In general, Docs to Markdown does not not do fancy formatting, colors, or styles. Examples of fancy formatting considered but not implemented include font colors and background colors, table-cell background colors, and heading styles.

And in general, Docs to Markdown converts the text as-is. There are a few exceptions:

  • HTML tags <tag> are escaped by default (so that they appear literally in the rendered output). If you want to actually write HTML and render it in your output, you can select the Render HTML tags option.
  • Single-cell tables get converted to code blocks.
  • Definition lists: Docs to Markdown provides a simple markup for definition lists, since Google Docs does not provide a way to express this useful construct.
  • Smart quotes are converted to straight quotes when they appear within code (inline or in code blocks).

Minimum permissions

Docs to Markdown requires only two permissions: permission to access the current document (to read and convert it) and permission to create a sidebar. For details, see Required permissions.

The goal is to minimize the intrusiveness of Docs to Markdown. While it would be possible to do things like collect images and create a zip file in the users Drive, that would require much wider permissions to write to Drive.

Getting the source to Docs to Markdown

Modifying Docs to Markdown code

There is a development/verification doc that you can use to develop changes to Docs to Markdown. Make a copy of the development/verification doc and change the source there :

  1. Tools > Script Manager > New
  2. Create a new project and copy the add-on files there (keep the same names).
  3. Make your changes (and add any necessary test cases to the doc). Note that Docs to Markdown is currently running under the legacy Rhino runtime engine (not the Chrome V8 engine).
  4. Run your modified add-on against the doc (select the “HTML headings/ids” option for the Markdown conversion, no options for the HTML conversion).
  5. Fork the gd2md-html project and compare your output to the markdown-verification.md and html-verification.md files. Any diffs should be consistent with your changes (and they should not change any other rendered output).

Testing your changes

Convert your development doc to both Markdown and HTML (use the HTML headings option for Markdown, but no other options). On your forked copy of the gd2md-html repo, compare your output to the Markdown and HTML verification files. The diffs should be minimal, except for any test cases you have added to the master doc and any rendering changes that result from your change.

Getting your changes into the main branch of the Docs to Markdown add-on

  1. When you’re sure your changes are working well, send me a pull request, detailing the changes you’ve made. In the pull request comment, share a link to your copy of the development/verification doc with me (with edit permission) so that I can use it to verify any changes.
  2. I will add your code changes to a development branch and verify that your changes work and are consistent with the spirit of Docs to Markdown.
  3. Once I publish a new version, I will acknowledge you as a contributor (unless you prefer to remain anonymous).

Potential enhancements

In addition to open bugs, there are several potential enhancements possible for Docs to Markdown:

New markup targets

Docs to Markdown provides a fairly generic framework for parsing Google Docs content. The current add-on provides conversion to Markdown and HTML. It should be relatively easy to add conversion capabilities to other targets, including plain-text markup like reStructuredText or AsciiDoc. In addition, it should be possible to provide reasonable conversion to typesetting markup languages like troff or LaTex. Note that there may be complications unique to each target that I am not aware of.

Markdown tables

There is an existing feature request for Markdown table output. This should be possible, but Markdown tables cannot handle complex tables that are possible in Google Docs or HTML.

New workflows

Docs to Markdown is a simple filter. There are other tools available like Pandoc that provide good conversion from one document format to another. You may be able to combine Docs to Markdown with Pandoc or other tools to get to the target format. And Pandoc may provide better conversion for some workflows than Docs to Markdown can provide. There is no need for Docs to Markdown to try to compete with a tool like Pandoc. This enhancement may require more process documentation than code.

Existing bugs, feature requests

Open issues for Docs to Markdown are at /evbacher/gd2md-html/issues.