hugodown

hugodown is an experimental R package from the r-lib organization that connects RMarkdown to the Hugo static site generator by converting .Rmd files into .md files that Hugo renders into HTML.

What is hugodown?

hugodown is an experimental R package maintained by r-lib that bridges RMarkdown and the Hugo website generator. It takes .Rmd files as input and produces Hugo-compatible .md files as output, which are then converted to HTML by Hugo's own build process. hugodown enforces a strict role separation: it handles the transformation from Markdown with R code to plain Markdown, while Hugo handles the transformation from Markdown to the final website. This package is similar in purpose to blogdown but focuses exclusively on Hugo websites and uses a single RMarkdown output format.

Key Features

• Explicit re-rendering — R code is only re-run when you knit a post, which avoids rebuilding everything on every site change and makes it easier for long-running blogs and multi-contributor projects.
• Pinned Hugo versions — local previews are pinned to a specific Hugo version, reducing incompatibilities between Hugo and your chosen theme when working across different blogs.
• Theme setup helpers — support for a limited set of Hugo themes, with automatic tweaks so that html widgets, syntax highlighting, and math display work out of the box.
• Site-outdated detection — the site_outdated() function lists all .Rmd files that have changed since their .md was last rendered, so you know exactly what needs to be re-knitted.
• Post scaffolding — use_post() creates a new post using the Hugo archetype, filling in default content from templates.
• Background preview server — hugo_start() launches a Hugo server in the background, so you can see your site update as you edit.

Who is it for?

hugodown is aimed at R users who author content in RMarkdown and want to publish it as a Hugo website. It suits bloggers who prefer to knit posts only when needed rather than rebuilding the entire site, and teams with multiple contributors where a shared site benefits from explicit re-rendering. It also helps users who want Hugo themes to work correctly with html widgets, syntax highlighting, and math without manual configuration.

What can you do with hugodown?

• Bloggers using RMarkdown: create a new post with use_post(), knit it to generate Hugo-ready Markdown, and preview the site with hugo_start().
• Teams managing a shared Hugo site: use site_outdated() to identify posts that need re-rendering and avoid stale output in the published site.
• Users migrating from blogdown: follow the documented steps to convert an existing blogdown site, including adjusting the archetype to use hugodown::md_document() and removing the root index.Rmd.

How does hugodown work?

To use hugodown, set output: hugodown::md_document() in the YAML metadata of your .Rmd files. Knitting then produces a .md file designed to work with Hugo. In RStudio, you can open the site's .Rproj file, call hugo_start() to start a background preview server, and use the Knit button or the keyboard shortcut Cmd+Shift+K (Mac) or Ctrl+Shift+K (Windows/Linux) to render posts. The Hugo server only adds .Rmd content to the preview after knitting.

Alternatives

• blogdown — the more established R package for building Hugo sites with RMarkdown. Unlike hugodown, blogdown integrates more closely with Hugo's build process and supports more output formats, while hugodown re-runs R code only when explicitly knitted and pins Hugo versions for local previews.

FAQ

Is hugodown available on CRAN?

No. hugodown is not available from CRAN yet and may never be, but the development version can be installed from GitHub with devtools::install_github("r-lib/hugodown").

How is hugodown different from blogdown?

hugodown enforces a strict partition: it only converts .Rmd to .md, and Hugo converts .md to HTML. It re-runs R code only when you knit, pins local Hugo versions, and provides theme setup helpers, but it does not support within-page cross-references for figures, tables, and equations.

Does hugodown work with any Hugo theme?

No. hugodown provides support for a limited number of themes, automatically adjusting them so that html widgets, syntax highlighting, and math display work out of the box.

How do I create a new post with hugodown?

Use the use_post() function, which creates a new post and fills in default content from the Hugo archetype configured in your site.