Skip to content

Latest commit

 

History

History

02-february

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

bookdown Tutorial

Resources & Examples

Pros & Cons of bookdown

Cons

  1. Some people forget how to write unless they're in Office
  2. Office has helpful grammar checks

Pros

  1. markdown is super easy
    1. leverages your existing knitr knowledge
    2. same syntax used in GitHub issues & Stack Overflow
    3. can facilitate similar products, like blogdown
  2. publish early drafts
    1. accessible by wide group
    2. editable by wide group (with GitHub PRs)
  3. plain text is editable with almost anything
  4. all the benefits of GitHub
    1. collaboration
    2. tracking & recover changes
    3. move between machines (e.g., quick additions w/ tablet)
  5. leverages R --all the modeling & graphs
  6. multiple output formats every time
    1. html on server
    2. pdf
    3. epub
  7. No real server is involved.
    1. When the bookdown files are compiled, self-contained html/pdf/epub can be read on any client.
    2. unlike problems with Wordpress sites
    3. the site should last longer, without as much maintenance
  8. VS Code has a portable spelling list
  9. As a consumer/reader
    1. different formats
    2. searchable
    3. editable
    4. transparent -if I need to reproduce/follow

Pre-reqs

Demo

Decisions

  1. knit-merge (k-m) vs merge-knit (m-k)
  2. special headers (section 2.2.3)
  3. cross-references & references
    1. table of contents, figures, tables, & equations
    2. bibliography
    3. index
    4. captions
  4. css styling

Tips & Lessons Learned

  1. Start with md files. Escalate to Rmd only if necessary

  2. Set heading names to facilitate references. The explicit value also helps search & replace.

  3. Don't number the files (e.g., 01-intro.md, 02-install.md). Use _bookdown.yml to order chapters.

  4. Add whenever you can.

    1. Full-scale writing at a desktop during quiet time and then render & push.
    2. Add a few sentences in the browser, but not yet render & push.
    3. Jot in a scratch pad and move it around later.

  5. Combination of Visual Studio Code & RStudio.

    1. VS Code packages that help markdown development.
      1. markdownlint
      2. previewing
      3. spell check

Discussion

  1. How to improve collaboration and combining chapters?
  2. Deployment scenarios:
    1. public throughout the book's whole life span --ideal for bookdown
    2. private during writing, then public
    3. private --accessible only to authors
    4. private --accessible only to team (some don't have RStudio, and just need the output)