all.gdocs.how_to_guide.md

• Other approaches

• Markdown -> Gdocs

      - Use bullet lists to organize the whole Markdown for consistency with
        other docs. See
        [all.coding_style.how_to_guide.md](https://github.com/cryptokaizen/cmamp/blob/master/docs/coding/all.coding_style.how_to_guide.md)
        or any other published Markdown format as reference
      - Add missing ``` around code blocks. These could be missing in the
        original Google doc. Also adjust code block indentations if needed
      - The generated markdown may convert http links as `html` `<span>`
        objects. This hinders the readability of the `md` file. In this case,
        manually convert to a standard `http://` link:
        - `[<span class="underline">https://www.sorrentum.org/</span>](https://www.sorrentum.org/)`
          -> `https://www.sorrentum.org/`
      - Replace the `html` `<img>` tag with a markdown link:
        - `<img src="docs/work_tools/figs/visual_studio_code/image1.png"/>` ->
          `![alt_text](docs/work_tools/figs/visual_studio_code/image1.png")`

- Remove empty lines manually
  ```markdown
  :'<,'>! perl -ne 'print if /\S/'

• Run the lint_md.sh
  • Usage:

    > dev_scripts/lint_md.sh docs/documentation_meta/all.writing_docs.how_to_guide.md

  • What the linter will do:
    • Build TOC automatically
    • Adjust the indentation to improve the Markdown's format (but the precondition is that you have properly adjusted the indentation levels).
    • Remove extra empty lines under headings
    • Adjust text layout
  • Do not mix manual edits and linter runs
  • If the linter messes up the text
    • File bugs in amp with examples what the linter does incorrectly
• Last steps
  • Compare the generated markdown file with the original Gdoc from top to bottom to ensure accurate rendering.
  • Review the markdown file on GitHub to make sure it looks good, as it may slightly differ from the preview in your local markdown editor
• When a gdoc becomes obsolete or it's deleted
  • Add a note at the top of a gdoc explaining what happened
  • Example: "Moved to /new_markdown_file.md"
  • Strike out the entire document
  • Move the gdoc to the _OLD directory

Other approaches

• Best for a large document

• Approach 1 - Chrome Docs to Markdown extension:

  • Use the Docs to Markdown extension
    • Install the extension from the G Suite marketplace
    • User guide for the extension
  • One needs to accept/reject all suggestions in a gdoc as the extension works poorly when a document is edited in the suggestion mode

• Approach 2 - Online converter:

  • Google-docs-to-markdown/

• Also need to go through Cleaning up converted markdown

• You might need to remove artifacts manually

Markdown -> Gdocs

• Approach 1:
  • Run

    > pandoc MyFile.md -f markdown -t odt -s -o MyFile.odt

  • Download the template in odt format
  • Run

    > pandoc code_organization.md -f markdown -t odt -s -o code_org.odt --reference-doc /Users/saggese/Downloads/Gdoc\ -\ Template.odt

  • Open it with TextEdit, copy-paste to Gdoc
• Approach 2:
  • Instead of copy-paste the markdown into Gdocs, you can copy the rendered markdown in a Gdoc
    • Gdocs does a good job of maintaining the formatting, levels of the headers, the links, and so on
• Approach 3:
  • https://markdownlivepreview.com/
  • TODO(gp): Check if the roundtrip works