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:
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
") that will throw HTML errors into the Markdown output images.
- Build the book with Bookdown, including one full-length 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 07-chart.Rmd, Table 1: Chart types covered in this book
- Manually delete any remaining
<iframe...elements (unless they are non-executable code snippets)
- Manually mark up “Variable List:” for production team in two places in Chapter 5 (and chapter 2?)
- Save and push the modified Markdown file up to GitHub repo
TODO: Check to see if triple back tics render correctly in the Markdown full-book output.
NOTE: Tried to insert unicode character
for four-whitespace characters appended to level 3 subheads in chap 5, but PDF engine Latex could not process. Then tried to switch to
latex_engine: xelatex to deal with unicode characters, but received different error. Replaced unicode symbol with hyphen-space, which is good enough.
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
- Convert with:
pandoc handsondataviz-modified.md --from markdown --to asciidoc --standalone --output handsondataviz-modified.asciidoc