| name | render-book |
| description | Render the book into HTML (gitbook) or PDF formats. Use when the user wants to "render the book", "build the book", "generate the book", or create HTML/PDF output. |
Rendering Book
Render the "Data Science with R" book into HTML or PDF formats using R's bookdown package.
Why? Automates the complex R commands required to build the book, ensuring consistent output for both web (HTML) and print (PDF) formats.
Quick Start
- Check Dependencies: Ensure R and
bookdown are installed.
- Pre-flight: Check
_output.yml for deprecated flags.
- Choose Format: HTML (default) or PDF (slow, heavy build).
- Execute: Run the appropriate command.
- Verify: Check logs and output files.
Prerequisites
Workflow Steps
0. Pre-flight Check (Optional)
Check _output.yml for deprecated Pandoc arguments.
grep "highlight-style" _output.yml
[!TIP]
If found, consider replacing with --syntax-highlighting to avoid warnings.
1. Render HTML (Gitbook)
This is the default and most common format.
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')"
[!TIP]
The output will be generated in docs/index.html.
2. Render PDF
Use this for generating the print version.
[!NOTE]
PDF generation involves heavy LaTeX compilation and may download large assets. Expect this to take significantly longer than HTML.
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')"
[!CAUTION]
PDF generation requires a LaTeX installation (like TinyTeX). If it fails, try installing TinyTeX in R: tinytex::install_tinytex().
3. Render All Formats
Generates all formats defined in _output.yml.
Rscript -e "bookdown::render_book('index.Rmd', 'all')"
4. Quality Check (Log Analysis)
After rendering, check for hidden warnings that don't fail the build:
grep -E "Warning|undefined|multiply-defined" Data-Science-with-R.log
Verification
Verify the output exists and was recently modified (within last 5 minutes):
find docs/ -name "*.pdf" -mmin -5
find docs/ -name "index.html" -mmin -5
Troubleshooting
| Problem | Cause | Solution |
|---|
command not found: Rscript | R is not in PATH | Install R or add it to your PATH. |
LaTeX failed to compile | Missing LaTeX packages | Run tinytex::install_tinytex() in R. |
there is no package called 'bookdown' | Missing R package | Run install.packages("bookdown") in R. |
| Slow PDF build/hangs | Downloading assets or large LaTeX compile | Wait; check network or compilation logs. |
Deprecated: ... highlight-style | Old Pandoc args in _output.yml | Update _output.yml (see Pre-flight check). |
Common Mistakes
-
Running from wrong directory: Always run from the book root (where index.Rmd lives).
cd docs && Rscript -e "bookdown::render_book(...)"
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')"
-
Editing docs/ directly: Never edit files in docs/. They get overwritten on each render. Edit the .Rmd source files instead.
-
Forgetting to save .Rmd files: Ensure all changes are saved before rendering. Unsaved changes won't appear in output.
-
Running PDF before HTML: If you've never built the book, build HTML first to catch errors faster. PDF builds are slow and LaTeX errors are harder to debug.
Sample Output
Successful HTML build:
Output created: docs/index.html
Successful PDF build:
Output created: docs/Data-Science-with-R.pdf
Failed build (missing package):
Error in library(ggplot2) : there is no package called 'ggplot2'
Calls: ... -> source -> withVisible -> eval -> eval -> library
Execution halted
[!TIP]
Package errors show which package is missing. Install it with install.packages("package_name").
Quality Rules
Testing
Evaluation Scenarios
| Scenario | Expected Behavior | Failure Indicator |
|---|
| Fresh HTML build | Creates docs/index.html with all chapters | Missing chapters or broken links |
| Fresh PDF build | Creates docs/Data-Science-with-R.pdf | LaTeX errors or missing PDF |
| Missing R package | Clear error naming the missing package | Cryptic error without package name |
Invalid .Rmd syntax | Error with file name and line number | Build hangs or no error context |
Validation Commands
test -f docs/index.html && echo "HTML OK" || echo "HTML MISSING"
test -f docs/Data-Science-with-R.pdf && echo "PDF OK" || echo "PDF MISSING"
grep -c "Warning" docs/*.log 2>/dev/null || echo "No warnings"