ggrossetie / asciidoc-googledocs-addon

Export Google Docs as AsciiDoc

AsciiDoc Processor Add-on for Google Docs™

Convert your Google Docs™ into AsciiDoc.

Usage

1. Install extension from Google Workspace Marketplace

2. Open a document or create a new one

3. Under the Add-ons menu, click AsciiDoc Processor > Convert all to convert the entire document into AsciiDoc.

4. Copy and paste the AsciiDoc output anywhere you want!

Note	To convert a part of your document, select some text and click AsciiDoc Processor > Convert selection

Supported text formats

This Add-on supports the following text formats :

• Headings

• Bold, italic, underline, subscript, superscript

• Tables

• Code bloc

• Lists (unordered and ordered)

Development

As a Google Apps add-on, this project is written in JavaScript and HTML. The file app/Code.gs contains the JavaScript functions; app/Dialog.html is the template for calling the conversion functions and displaying the processed output.

Testing unpublished code

To safely test the code in your own Google Apps environment, create a new Google Apps project out of these files — or your modified versions! — then create and run test deployments using these simple steps.

1. Inside a Google Doc, select Tools > Script editor…​.

   • A new tab will open for a blank project, with a Code.gs file already started.

2. In the new tab, give your project a name, such as asciidoc-googledocs-addon-test, and click "Ok".

3. Replace the entire body of Code.gs with the contents of app/Code.gs, and save.

4. In the page menu, select File > New > HTML file.

5. In the Create dialog, enter the filename Dialog.html, then "Ok".

6. Replace the entire body of Dialog.html with the contents of app/Dialog.html, and save.

7. In the page menu, select Publish > Test as addon.

8. Under "Installation Config", select "Installed and Enabled".

9. Click "Select Doc" and choose a Google Doc from your Drive.

10. Under "Execute Saved Test", select the radio button to the left of your new test, then click "Test".

    • This will open your document in a new tab; your new test addon will be listed under Add-ons!

Help

If you discover errors or ommisions in the source code or documentation, please don’t hesitate to submit an issue or open a pull request with a fix.

asciidoc-googledocs-addon's Issues

limit permissions

Can you add this to the top of addon.gs so that you only need permission to access the current document?

/**
 * @OnlyCurrentDoc  Limits the script to only accessing the current document.
 */

Formatting preferences and options

Tell me if I'm stepping on any toes, or if you have a better place for this discussion, but I was thinking maybe we could just use a thread to list some things we may or may not consider less-than-optimal about the current formatting, and maybe a wishlist of changes? We can spin issue tickets off for the ones we want to implement, if we want...

\s before *?
The first thing I noticed is you put spaces before list markup (ordered and unordered).

So:

 * item
 * item

Instead of:

* item
* item

Is there a reason for this convention? I find it really awkward.

Blank lines before lists?
The conversions are also missing blank lines between the preceding line and the list (ordered or unordered).

So:
This kind of thing:

• Item 1
• Item 2

Parses to:

*This kind of thing:*
 * Item 1
 * Item 2

I think a blank line is required. This just dumps the asterisks and text inline.

Extraneous ==
Sometimes I'm getting == on a line on its own. I haven't investigated, but I'm guessing it's maybe from deleted headings or something? We could probably stand to clean up stray ^\=\=\n or something. I don't think this was intentional, right?

I'll leave it there for now. Let me know if this is helpful, and create tickets (or I will) to implement these? I'll gladly take some on :-)

Feature Request: Support Images

Per $subject. :)

Feature Request: Support Tables

Awesome start!

Perusing source, caught some header and minor formatting support, but nothing in line yet for tables. IMO is probably a great next step (my use case doc that I want to port makes heavy use of tables).

Inline code not converted

I have lots of inline code in my gdoc along styled with consolas font among words with Arial font. Those codes are not converted to adoc syntax.

Explain how source blocks are recognized in a Google Docs

Feedback from David Turanski:

I had to look at the source code to realize that you need use one of the prescribed font families like Courier New. The docs could be better.

Local links to use <<anchor,text>> format

Right now when a hyperlink to a local anchor gets processed, it looks something like this:

#heading=h.cughuow97z4o[local link]

This seems to just be a direct copy, but I bet that ID is getting carried with the element being linked to, and we can grab that and use it to form proper local xref. We don't actually use a lot of local links, but these can be a little hard to convert since that hash string doesn't actually appear elsewhere in the converted, so it's not clear just what that local link lined up with.

<<anchor-to-heading-id-or-explicit-anchor,local link>>

Force blank line above lists

The conversions are also missing blank lines between the preceding line and the list (ordered or unordered).

Right now...
This kind of thing in GDocs:

• Item 1
• Item 2

Parses to:

• This kind of thing in AsciiDoc: * * Item 1 * Item 2

When we want it to parse to:

*This kind of thing in AsciiDoc:*

 * Item 1
 * Item 2

A blank line is required between any text and the first item in a list.

Remove spaces prepended to list items

Both ordered and unordered lists insert a superfluous \s before at position one of the line. This is unnecessary, so let's remove it. (As per discussion in #17.)

Change output:

 * item
 * item

to

* item
* item

and

 . item
 . item

to

. item
. item

Not verified by Google error.

Google no longer allows this App. Now get the following error whenever I try to install the App:
"Sign in with Google temporarily disabled for this app
This app has not been verified yet by Google in order to use Google Sign In."

Document how to run the code for development

I would be great to add some hints to the readme about how the code can be run. This would lower the barrier for potential contributes who never before worked with a googledocs plugin.

Merge with gdoc2adoc project

The following project has the same goal and supports a wide range of features.

I think it makes sense to merge the two projects.

https://github.com/maxandersen/gdoc2adoc

/cc @maxandersen

Authorization is required

Logged in to docs with my company google account, I've done the suggested installation of the add-on. I granted all requested permission while installing the add-on, but when I go to convert I get the following error.

I am the owner of the document and I tried "share" to "anyone with the link" as a viewer, commenter, and editor. All configurations given me the same error message.

Level 1 and Level 2 headers

I think the level 1 and 2 headers conversion is fundamentally broken and I think it has to do with AsciiDoc Cheatsheet misleading us. I have opened a discussion around fixing the cheatsheet here .

But regardless of when the cheatsheet gets fixed the issue can be fixed in the processor.

Publish on web store

Submitted the Add-on form today!

Feature Request: Support lists

As requested by @nawroth

Remove extraneous "false" headings

When a blank heading is left in a GDoc, the addon renders the formatting markup anyway. This is observed in level 2 titles (==), but it likely occurs with others?

We should seek and destory any orphaned formatting marks, wherever they may lurk!

Feature Request: Export one sentence per line (ventilated prose)

Many writers choose to take advantage of AsciiDoc's support for ventilated prose (one sentence per line). In fact, writing ventilated prose is one of the recommended best practices published on asciidoctor.org.

It would be very helpful if the AsciiDoc Processor Add-on had and on/off toggle to export content using ventilated prose. Other open-source AsciiDoc utilities already support this functionality, so perhaps this feature doesn't need to be built from scratch. For example, Kramdown AsciiDoc supports this behavior with its --wrap=ventilate option.

README: link for issues incorrectly points to asciidoctor

Converting forever

Hi,

The extension is converting forever (any doc, any mode : convert all or convert selection).
Chrome Versions :

• 51.0.2704.79 (64-bit)
• 51.0.2704.106 (64-bit)

OS : Linux

An idea ?

Importing asciidoc to googledoc

Hello!

Thank you for open-sourcing this wonderful add-on!

I was wondering if there are any plans to add support for the other way around: importing asciidoc and converting it into a google doc?

Disable list continuation (attributes, conditional processing, and more?)

Hello,

I am trying to set up a workflow where product managers iterate on a release notes draft on Google Docs. When it's release time, I want to copy paste the AsciiDoc generated from the extension as-is to a new file and publish using Antora.

To this effect, I place attributes and conditional directives in the Gdoc but, unless I messed up with Docs formatting, the + sign is added to the end of lines with attributes and if macros.

This is a sample of a such a Gdoc (# == Title and ## == Heading 1 in the sample below):

# v2.18.0
:release-date: 2019.10.15
:gh-changelog: https://github.com/Company/app/compare/v2.17.0\...v2.18.0
:asana-changelog: https://app.asana.com/0/1144692386463428/list

ifdef::page-internal[]
include::partial$release-info.adoc[]
endif::[]

## New developments

…

## Other section

…

For information, the release-info partial looks like this:

_**Release date:** {release-date}_

Changes since the last release:

* {asana-changelog}[Asana dashboard]
* {gh-changelog}[GitHub changelog]

This is what I get from the conversion:

= v2.18.0

:release-date: 2019.10.15 +
:gh-changelog: https://github.com/Company/app/compare/v2.17.0\...v2.18.0 +
:asana-changelog: https://app.asana.com/0/1144692386463428/list

ifdef::page-internal[] +
include::partial$release-info.adoc[] +
endif::[]

== New developments

…

== Other section

…

When I publish to Antora, the ifdef macro is not resolved. If I remove the macro and try to output the attributes, I meet the same issue.

I believe you will understand my use case and may provide alternate solutions, if this looks too convoluted, but I have to say I have many more elaborate use cases in mind.

Thanks for your work and thanks in advance - casual contribution for business users is essential to technical docs.

AsciiDoc no longer shows up in Add-on menu

AsciiDoc Processor no longer appears in the Add-on menu nor in list of extensions available to install for Google Docs.

To reproduce:
. Open a new Google doc.
. Click Add-ons.

No AsciiDoc Processor option.
Selecting Manage Add-ons opens the GSuite Marketplace.
Searching the market place for AsciiDoc keyword returns no results.

The procedure with the install link to the Chrome Web Store returns a 404.

When I go to my Google account's security page and check Third-party access, the AsciiDoc Processor options match the ones listed in #34.

Is anyone else having this issue?

ScriptError: TypeError: child.editAsText is not a function

When I try to convert a gdoc get error "ScriptError: TypeError: child.editAsText is not a function".

It seems I can convert small parts of it, but not the whole doc, or couple of pages.
Any ideas?

Thank you!

Ensure Empty Lines before Headings/after Title

When I convert a Document that uses the google docs formatting for title/headings, the created AsciiDoc is not what I would expect.

Generated AsciiDoc:

= Title
== Heading Level 1
Some Text

=== Heading Level 2
Some Text

There needs to be an empty line before Heading Level 1. The generated code leads to the "Level 1"-block is completely missing.

I would go so far to say, it would be better to have an empty line also after the title and headings.

So my expectation for the output is:

= Title

== Heading Level 1

Some Text

=== Heading Level 2

Some Text

DocumentApp.PositionedImage#getBlob can throw an exception

I don't know exactly why and this is undocumented but I can reproduce this issue on a Google Document.
For reference, here's the documentation for DocumentApp.PositionedImage#getBlob: https://developers.google.com/apps-script/reference/document/positioned-image

As a result, we should add a try/catch around:

https://github.com/Mogztter/asciidoc-googledocs-addon/blob/e629db563e5bba80885a829ca840590549378320/app/Code.gs#L322-L324

Only the first paragraph in a table celle is converted, while the other paragraphs are lost in translation

When you have more than one paragraph in a table celle, only the first paragraph is converted into asciidoc, while the other paragraphs are omitted (lost in translation).

Ignore unsupported child in a Google document

Section breaks are DocumentApp.ElementType.UNSUPPORTED and should be ignored to avoid error.

We should add the following code:

if (child.getType() == DocumentApp.ElementType.UNSUPPORTED) {
  continue;
}

just before:

https://github.com/Mogztter/asciidoc-googledocs-addon/blob/b70259eea794eb0254741c08ed90cab42ea02eef/app/Code.gs#L67