Manually Modify Markdown Output

The O’Reilly production team has agreed to accept our full-book Markdown file into their workflow, which is easier for them to work with than the full-book MSWord file. Note that our Bookdown index.Rmd file includes code to generate a full-book Markdown:

bookdown::markdown_document2:
  default

See this not-fully-documented Bookdown solution about generating Markdown output: https://stackoverflow.com/questions/58164239/compile-bookdown-to-markdown. We experimented to see if “strict” Markdown would produce cleaner output, following this RMarkdown guide https://bookdown.org/yihui/rmarkdown/markdown-document.html, but saw no difference when compared to the default settings.

We need to do a bit of manual cleanup before ORM production team can convert the full-book Markdown file into AsciiDoc format for their Atlas platform, unless we find a way to automate these steps. See workaround notes in the Images and Tables sections above. Remember to avoid mischievous characters in R code-chunk image captions (such as < or > or ") that will throw HTML errors into the Markdown output images.

  • Build the book with Bookdown, including one large Markdown file (docs folder, suffix .md)
  • Manually rename it as HandsOnDataViz-modified.md
  • Manually paste in these Markdown tables to replace HTML tables (unless ORM can handle this part)
    • from index.Rmd, table of authors
    • from 05-chart.Rmd, Table 1: Chart types covered in this book
  • Manually replace any <iframe... HTML or GIF elements with their PNG substitutes, and new ALT text (unless authors come up with a better way to automate this)
  • Manually delete any remaining <iframe... elements (unless they are non-executable code snippets)
  • Save and push the modified Markdown file up to GitHub repo

Note: Previously, we tried to use Pandoc to convert the modified.md file to asciidoc, but encountered many errors.

OLD Pandoc conversion steps (for reference only):

  • Use command line to navigate to subfolder with pwd and cd.
  • Convert with: pandoc handsondataviz-modified.md --from markdown --to asciidoc --standalone --output handsondataviz-modified.asciidoc