Choosing between MkDocs, Quarto, and pkgdown for your project.
Compares MkDocs, Quarto, and pkgdown to help choose the right documentation framework.
/plugin marketplace add Data-Wise/craft/plugin install data-wise-craft@Data-Wise/craftsite/docs/Choosing between MkDocs, Quarto, and pkgdown for your project.
R Package? → pkgdown (standard) or Quarto (modern alternative)
Python/Node/DevTools? → MkDocs (recommended)
Academic/Research? → Quarto (supports R, Python, Julia)
Need speed? → MkDocs (fastest setup)
| Feature | MkDocs | Quarto | pkgdown |
|---|---|---|---|
| Best for | Dev tools, Python, Node | Research, multi-language | R packages |
| Setup time | 2 minutes | 5 minutes | 3 minutes |
| Language | Python | R/Python/Julia | R only |
| Theme | Material (beautiful) | Bootstrap | Bootstrap |
| Code execution | No | Yes (R, Python) | Yes (R vignettes) |
| GitHub Pages | Easy | Easy | Built-in |
| Learning curve | Low | Medium | Low |
| Flexibility | High | Very high | Medium |
What it is:
Pros: ✅ Fastest setup (2 minutes) ✅ Beautiful Material theme ✅ Great navigation ✅ Works with any project type ✅ Easy to deploy ✅ Extensive plugin ecosystem
Cons: ❌ Doesn't execute code ❌ Requires Python ❌ Not standard for R packages
Best for:
Setup:
/site:mkdocs:init # Quick setup
/site:mkdocs:preview # Preview
/site:deploy # Deploy
Commands:
/site:mkdocs:init - Initialize MkDocs/site:mkdocs:preview - Quick preview/site:mkdocs:status - Check statusWhat it is:
Pros: ✅ Executes R/Python/Julia code ✅ Scientific publishing features ✅ Beautiful output ✅ Multi-language support ✅ Active development (from RStudio) ✅ Great for reproducible research
Cons: ❌ Slower than MkDocs ❌ More complex configuration ❌ Larger learning curve ❌ Overkill for simple docs
Best for:
Setup:
# Create _quarto.yml manually
/site:init # Detects Quarto
/site:preview # Preview
/site:deploy # Deploy
Manual init example:
project:
type: website
output-dir: _site
website:
title: "My Project"
navbar:
left:
- href: index.qmd
text: Home
What it is:
Pros: ✅ Standard for R packages ✅ Auto-generates from R docs ✅ R community standard ✅ Vignette integration ✅ Function reference auto-generated
Cons: ❌ R packages only ❌ Less flexible than others ❌ Bootstrap theme (older style) ❌ Requires R environment
Best for:
Setup:
# In R console
usethis::use_pkgdown()
pkgdown::build_site()
Commands:
/site:init (detects R package)MkDocs: ❌ No
Quarto: ✅ Yes
pkgdown: ✅ Yes (R only)
MkDocs:
Quarto:
pkgdown:
All three: Easy GitHub Pages deployment
MkDocs:
/site:deploy # Automated
Quarto:
/site:deploy # Automated
pkgdown:
pkgdown::build_site()
# Then push _site/ to gh-pages
docs/ → *.qmd files_quarto.yml*.qmd → *.mdmkdocs.yml_quarto.ymlaltdoc package for integration1st choice: pkgdown
/site:init detects automaticallyAlternative: Quarto + altdoc
1st choice: MkDocs
/site:mkdocs:init for quick setup1st choice: MkDocs
/site:mkdocs:init1st choice: Quarto
1st choice: Quarto
Generic (auto-detect):
/site:init # Detects best framework
/site:preview # Preview any framework
/site:deploy # Deploy any framework
MkDocs-specific (fast, no questions):
/site:mkdocs:init # Force MkDocs
/site:mkdocs:preview # Quick preview
/site:mkdocs:status # Status check
Why both?
Choose MkDocs if:
Choose Quarto if:
Choose pkgdown if:
Not sure?
/site:init # Let it auto-detect
Want MkDocs (fast)?
/site:mkdocs:init # Quick setup
Need help deciding?
/hub # Context-aware suggestions
See also:
/site - Site command hub/site:init - Initialize site (auto-detect)/site:mkdocs:init - Quick MkDocs setup/help workflows - Documentation workflows