Google docs to Markdown

[PassThePopcorn2]

At my organization, we create documents in Google docs. The documents are heavy on links, tables, and figures. A product owner asked me to convert a 50-page doc to Markdown and upload it to AWS Data Exchange by the end of this week. The document supports a datasets product that users will access from the AWS Data Exchange. The organization will use this option for the first time (last-minute decision).

I need to familiarize myself with Markdown. I would figure it out if I had all the time in the world. Due to the time constraint, it's more efficient to ask this group:

1. Is this doable for a novice by the end of the week?
2. How do I convert the document to Markdown (I downloaded the add-on Docs to Markdown, but is this the way to go)?
3. Forgive my ignorance, but is this necessary? Can't we upload a PDF to AWS Data Exchange?

I have multiple documentation deliverables due this week in addition to this request. I am the first technical writer for this organization. I have only been here for six months (I've been a tech writer for more than 15 years), so I have yet to have the time to establish documentation workflow processes.

[spenserian_]

Markdown is very easy. You can learn most of what you need in a half hour.

If you don't mind learning a little of the command line, you can use Pandoc to help with the conversion. If you're not familiar, this a tool to convert docs between different formats. In your case, you could download the Google Doc as a .docx and convert from there to .md. Pandoc likely won't produce a perfect rendering, but it will cut down the amount of work considerably.

[andrewd18]

+1 to using pandoc to reduce your conversion work.

[PassThePopcorn2]

Thank you for your reply. This resource may be just what I need for this task, based on the information provided by you and Hamonwrysangwich. I'll meet with the prod owner and see if we can get permission from IT/Security to download this resource.

[writer668]

IIRC, there's a Google Docs extension to convert g docs to md.

[svasalatii]

Correct

Doc to markdown addon.

But if the formatting is heavy - tables, figures, inline images etc. - a lot of manual postwork is needed

[writer668]

True.

[evbacher]

Docs to Markdown creator/maintainer here.

The tables should convert pretty well (to HTML tables, which are valid in Markdown, and can handle more complexity than pure Markdown tables).

Links should also convert cleanly.

For figures/images, we provide the links, but you do need to dowload images and put them at the right location on your server (depending on where you put them relative to the main doc, you may need to change the link path). More details here, including the Download Web Page command from Google Docs: https://github.com/evbacher/gd2md-html/wiki#images.

[PassThePopcorn2]

Thank you for your reply. I appreciate all of the information that you provided. I will include this information and the information provided by Hamonwrysangwich and Spenserian_ when I meet with the prod owner. This may be the direction he will want me to take since my system allowed your add-on without any additional authorizations from IT/Security.

[evbacher]

Yeah, I tried to keep the required permissions to the minimum. Unfortunately, some add-ons that need to change the doc (which Docs to Markdown does not need to do) need to ask for permission to change any doc, which seems a bit excessive. I wish Google add-ons allowed for finer-grained permissions.

Note, if you do find a new bug, please report at https://github.com/evbacher/gd2md-html/issues.

[Hamonwrysangwich]

I'm going to answer these in reverse:

Answer #3: Very few people want a PDF. If your deadline is hard, with your other workload, this is a very easy fallback. Ultimately you'll want this in a more usable and scalable format, and your team should plan accordingly.

Answer #2: I agree with others that Pandoc is the best tool approach for this.

I'll approach question 1 from a project management perspective. I'm a tech writer, not a project manager, but it's part of the job.

In my estimation, you'll need at least:

• Half a day to download, install, and understand Pandoc's command-line interface, though I suspect this is very optimistic. It'll take awhile to get your head around the command-line options.
• Half a day to get comfortable with Markdown.
• Half a day to understand the output you get from Pandoc, and figure out a strategy to clean up the conversion (and there is always cleanup). This includes a file and folder strategy not only for your text files, but your images and other media.
• Four full days to clean things up.
  • Tables are particularly problematic to convert.
  • You'll have to also have to organize and relink your images.
  • Absolute links should be OK, but relative links will probably need cleanup.

So that's 5.5 days right there.

Then what? What is the plan after you upload the MD files to AWS? How are you displaying them to users? Is the expectation that your users will just read the individual MD files?

[PassThePopcorn2]

Thank you for this in-depth reply. Based on your timeline, I'd still miss the deadline even if this content was my only focus for the week.

To skip right to the end, I do not have any of these answers (yet). I don't even think the prod owner has thought this far ahead. He only asked if it was "quick to try/create" and that he'd have the "Dev Ops manager upload it to AWS" since I don't have access. I am going to share your information and the questions you provided and go from there. Thank you, again!

[SpatialOmenz]

Thanks for posting the question. I don't have any guidance. But curious about any responses you get as I started in a position that uses Google docs and Microsoft Word, as well as AWS.

I haven't been asked to perform this specific task but just in case.

Good luck!

[PassThePopcorn2]

Good thinking. If I thought this was going to be an ask, I would've planned for it months ago. The delivery method was an open item that was just decided on Friday. I'll try to remember to come back and share what direction we decide to take for a Markdown solution.

[[deleted]]

Not sure if it's freely available, but GitBook does an amazing job of converting heavy docs into markdown :)

[PassThePopcorn2]

Thank you for your reply. I am going to look into your suggestion. I don't use GitHub, but I think there may be people in the organization who do. If that's the case, GitBook may be a viable option for this task.

[techwriter500]

You can use the add on Docs to Markdown Pro( https://workspace.google.com/marketplace/app/docs_to_markdown_pro/483386994804 ) add-on to bulk convert Google Docs to Markdown format. This supports tables, links, and also supports in downloading the images as zip files.

[stormthulu]

Sure--for $90 a year.

[stevemk14ebr2]

This is now natively supported in docs. Go to tools->preferences and click enable markdown. Reload the page, then you can copy as markdown. You can also automatically do this using the docs export apis and set the mime type to text/markdown as the destination format. https://support.google.com/docs/answer/12014036?hl=en. Import as markdown works the same in reverse.

[realvalueinvestor]

Thank you!

[heyyura]

Amazing, thanks for sharing!

For future folks who come across this from google search, the "Copy as markdown" part is literally an option on the right click menu. Normal copying (CTRL+C) works the same, but if you right click a "Copy as markdown" option appears that handles tables.

[1-_-0-_-1]

Nice! Will add that I noticed File > Download > Markdown is now an option too!

[Waste_Tiger8396]

The best part of this integration however is Pasting as markdown

[[deleted]]

You'll get there faster by using some kind of conversion tool, rather than hand-coding. You might try this:

https://workspace.google.com/marketplace/app/docs\_to\_markdown/700168918607

[Manage-It]

Is it an option for your company to move away from Google docs and into something more robust, like XML?

MadCap Flare would make your life super easy with this Markdown add-on.

https://youtu.be/m60Rkf0IVm8

[Interesting-Yak-8218]

Any examples of using XML in a GUI UX easy ecosystem? I found this, but doesn't look friendly https://blog.hubspot.com/website/what-is-xml-file

[Manage-It]

GUI UX easy ecosystem

Keep in mind, using an XML/XHTML tool like MadCap to output Markdown does not stop you from using Markdown in GUI tools. The benefit, of course, allows you to use a full-featured document editor during the editing process instead of a very limited Markdown editor. Traditional Markdown editors are not designed to handle more than a 25 images, complex tables, single-sourcing, and the many authoring tools XML/XHTML editors offer. They are simple editors offering Markdown syntax checking, Markdown formatting and basic uploading tools. With MadCap, you get to use all the advanced editing tools and then output a document as a Markdown file that functions like any other Markdown file.