Changelog
Source:NEWS.md
CHANGES IN litedown VERSION 1.0
CRAN release: 2026-11-02
The Markdown backend has been changed from the commonmark package to a copy of ‘cmark-gfm’ bundled with litedown, with our own patches and extensions. Features that used to be emulated with fragile text processing in R (LaTeX math, superscript/subscript/strikethrough, raw content blocks, and inline attributes on links and images) are now handled directly by the Markdown parser, which is faster and more reliable, especially for large documents and documents with multibyte (e.g., CJK) characters. This also fixes several long-standing rendering bugs (#33, #135, #139). The commonmark package is no longer a dependency (#141, #142, #143). Rendering output is essentially unchanged, with one minor exception: superscript, subscript, and strikethrough now require the delimiters to “hug” their content (e.g.,
a^b^works, buta ^ b ^no longer produces a superscript), consistent with how*emphasis*works.Improved the
litedown::roam()interface (details): the toolbar is sticky and its buttons are real, labeled buttons; results of rendering to disk appear as dismissible toasts (with a link to the output) instead of blocking dialogs; the page shows a banner and reconnects automatically when the server stops; the scroll position is kept when the page auto-reloads, and polling pauses in background tabs; errors are shown on the page with a traceback of your code (linking to the failing line of a code chunk) and a link to go back, instead of as plain text; wrapped lines of code blocks align to the right of the line numbers; the file listing shows relative modification times, dims files starting with_or., and has a filter box and sorting menu; the new-file dialog validates the filename, offers presets (blank, article, slides, book), and previews the YAML.Added a new function
pkg_site(), which builds a website for an R package from a template bundled with litedown (undersystem.file('site', package = 'litedown')). The template contains pages for the package description, news, manual, vignettes, examples, and source code, and can be customized page by page (a file that already exists in the site directory will not be overwritten by the template). Previously this template only lived in the GitHub Action https://github.com/yihui/actions/tree/main/litedown-site, which means a package site could not be built locally, and the template could get out of sync with the installed version of litedown.pkg_desc(type = "dl")now generates a compact description in a sidebar (a fenced Div with the classessideandside-right): theDescriptionandSuggestsfields are omitted, andURLandBugReportsare merged into aLinksfield with short text links (e.g.,Browse source codeandReport a bug) instead of long bare URLs. The site template ofpkg_site()uses it to put the description in a sidebar on the home page when the package has aREADME.md.pkg_desc(type = "dl")shows only the authors (roleaut) by default when the author list is long, and the full list is hidden behind<details>. The site template’s footer is now a plain_footer.md(instead of_footer.Rmd), in which$authors$and$version$are substituted bypkg_site().Added a new
peleengine to draw diagrams with Pele, a lightweight renderer for the Mermaid syntax. It takes the same input as themermaidengine (and shares its implementation), and the required JS is added to the HTML output automatically. The diagrams in the litedown documentation (https://pkg.yihui.org/litedown/book/) now use it.Added a function
pkg_articles()to list package vignettes (it was previously inlined in thearticles.Rmdtemplate ofpkg_site()).pkg_manual(),pkg_articles(), andpkg_examples()gain an argumentgroupsto group help pages, vignettes, or examples, which defaults to the subfieldmanual,articles, orexamplesofsitein_litedown.yml(similar to_pkgdown.yml), e.g.,site: {manual: {Sites: [pkg_site, "roam*"]}}(group titles are the keys). Items not in any group are listed underOther, and a name that matches nothing is an error. Help pages with the keywordinternal(e.g., re-exports) are listed only if a group names them. Without groups, the default listing is unchanged.Moved the vignette
slidesto the exampleexamples/045-snap-slides.Rmd, which is rendered on the package site: https://pkg.yihui.org/litedown/examples/045-snap-slides.htmlfuse_site()withrebuild: "outdated"(the default) now also rebuilds pages when_litedown.ymlis newer than their output files, instead of only comparing each page with its own source file.On the home page of
pkg_site(), theLinksin the sidebar no longer include the URL of the package site itself (i.e.,https://USER.github.io/PKG/, or the fieldurlundersitein_litedown.yml), and badges inREADME.md(between<!-- badges: start -->and<!-- badges: end -->) are placed in the right sidebar.The navigation menu of a package site gets a GitHub icon on the right if the
BugReportsfield points to a GitHub repo.The local cache of the latest version of the jsDelivr assets is now invalidated when litedown is upgraded, and actually expires after a week (the age was previously compared in the wrong time units).
Fixed a bug that the navigation menu of a website only contained the page being previewed (instead of all pages) when previewing a single file via
roam().Fixed a bug that
fuse()(andmark()) failed to compile a.texfile to PDF when the output was in a different directory, becauselatexmkwas not run in the output directory and could not find relative paths in the.texfile such as plot files (thanks, @reedacartwright, #168).Fixed an infinite recursion (node stack overflow) in
fuse()when a code chunk’s source contained a`<...>`sequence that matched no chunk label (e.g., a JavaScript template literal such as`<${x}>`). Such a sequence is now left unchanged, while a real`<label>`include still expands to that chunk’s source.Fixed a bug that backtick text containing a brace object (e.g., a JavaScript object literal with nested braces such as
`{ cols: { cyl: { type: "select" } } }`) was mistakenly treated as an inline code expression. The`{lang} source`form now requires an engine name immediately after the opening{.The chunk option
echocan now take a numeric vector of line numbers to select which lines of the source code to display, e.g.,echo = -1hides the first line, andecho = 2:3shows only the second and third lines (thanks, @jangorecki, #93).The navigation menu of a site no longer includes
doc/index.html(the vignette index of an R package).Added a new function
pkg_examples()to list the examples under theexamples/directory of a package, so theexamples.Rmdpage of thepkg_site()template no longer assumes that the site is built in the package root directory.pkg_news()now links issue numbers (and@usernames) that immediately follow an opening parenthesis, e.g.,#1in(#1, #2).The default stylesheet no longer sets
font-size: .9emonbody, so body text is slightly larger (about 11%); the relative sizes of elements such ascode, footnotes, and captions are unchanged.HTML output now uses
<embed>instead of<img>for PDF files included via, and the PDF is base64 encoded when resources are embedded (a?queryor#hashin the path is ignored when locating the file, and the#hash, e.g.,#page=2, is kept).The default HTML template now uses semantic elements: the frontmatter is wrapped in
<header class="frontmatter">, the body in<main><article>, and the TOC is a<nav id="TOC">instead of a<div>. The classbodyis no longer used (use the selectormain articlein custom CSS instead), the metadata variablebody-classnow sets the class of<article>(the default is empty), and a new variablebody-tagcan change the tag. Each chapter of a book is an<article class="chapter">(instead of<div class="chapter body">). This makes the HTML structure semantically correct. The site menu now has the classsite-nav. Also see the new examples of custom styles, including an interactive page for tweaking the major CSS settings and pages that use stylesheets from the web, and the new book section Custom CSS/JS (thanks, @eijoac @eddelbuettel, #76).The JavaScript and CSS for paged HTML (
pages.jsandpages.css) have been improved: lists, block quotes, and other elements can be broken across pages at any level (not only a few tags), keeping their indentation and numbering; widows, orphans, and headings alone at the bottom of a page are avoided; the content is taken from<main>(or<article>, or<body>) and the frontmatter from<header>, which can be changed via the attributesdata-pages-rootanddata-pages-frontof<body>; the pagination waits for diagrams to settle and shows its progress, can be triggered by the eventpagesjs:paginate(e.g., via the argumentwaitofxfun::browser_print()to print a page to PDF), and is faster. See the rewritten section Paged HTML for details.Added a JS asset
nav-highlight.jsto highlight the current page in<nav>, which is enabled for sites by default (details).The appearance of the default CSS and several other CSS assets can now be customized via CSS variables such as
--accentand--muted-bg, without writing selectors (details). The CSS playground generates these variables, too.The
@appendixJS asset is no longer loaded by thearticlefeature ofvest()or by sites and books. A heading with the attribute.appendixis no longer wrapped in adiv.appendixcontainer; it only has the classappendix.
CHANGES IN litedown VERSION 0.11
CRAN release: 2026-08-26
The
bibliographyfield can now point to an R file containingbibentry()calls (e.g.,inst/REFERENCES.R) in addition to.bibfiles, and both types can be mixed (thanks, @marberts, #136).Fixed a bug in
mark()that a trailing newline was appended to the wrong lines when a closing HTML tag was followed by a code block (thanks, @ben-schwen, #135).
CHANGES IN litedown VERSION 0.10
CRAN release: 2026-07-11
Added minimal book and website project templates that can be discovered by RStudio from
File>New Project>New Directory>Project using litedown. You can also create them programmatically withlitedown:::proj_skeleton(path, type), wheretypeis"book"or"site"(thanks, @jangorecki, #97).Added
fuse_exit(), which can be called inside a code chunk to exitfuse()early and discard the rest of the document. It takes an optionalappendargument to add text after the current chunk (thanks, @TimTaylor, #117).Added support for optimizing PNG plot files via the global option
litedown.tinypng. When set toTRUEand the tinyimg package is installed, PNG images generated from code chunks will be optimized bytinyimg::tinypng()to reduce file size. For other PNG files (e.g., images manually included in the document), users can calltinyimg::tinypng('.')to optimize all PNG files under the current directory (thanks, @bastistician, #116).Added new engines
exec,sh,bash,zsh, andpowershellto run arbitrary commands viasystem2()and capture the output. Theexecengine requires the chunk optioncommand; thesh/bash/zsh/powershellengines use the engine name as the command.When the
outputargument ofmark()is a.pdffile, Markdown will be converted to a full.texfile instead of a LaTeX fragment before it is compiled to PDF.Fixed a bug that sections in the appendix could not be cross-referenced.
Added a meta variable
langfor HTML output, which is the language of the document (e.g.,en-USfor US English). This variable is used in the<html lang="...">tag of the HTML output file. By default, the language is detected from the system locale, but you can also set it via thelangfield undermetain YAML metadata, e.g.,lang: en-GBfor British English (thanks, @TimTaylor, #121).Fixed a bug when embedding JS resources: previously
</was escaped to<\/to avoid</script>from being present in the JS source, but the escaping was too general (e.g.,</may appear in a regex/</g). Now we only escape</script>to<\/script>.For
fuse_site(), the generated site menu now automatically includes landing pages for one-level subdirectories containingindex.html(e.g.,playground/index.html), so subdirectory index pages appear in the navigation.Fixed a re-entrancy bug that chunk options
fig.pathandcache.pathin nestedfuse()calls caused overridden figure/cache files (thanks, @nanxstats, #127).Fixed a bug that
detect_pkg()doesn’t work whenR CMD checkchecks package vignettes.
CHANGES IN litedown VERSION 0.9
CRAN release: 2025-12-18
Provided a new chunk option
filterto filter the output elements via a custom function. This makes it possible to re-order output elements. As a result, text output and plots from afor-loop can be interleaved (thanks, @reedacartwright, #106).The chunk option
attr.sourcewill default to.lang(wherelangis the engine name) only when it is not provided, i.e.,NULL. Previously the value.langwould still be used whenattr.sourcehas been provided. Now it’s possible to completely override it, e.g.,attr.source = 'language-r'as in #107 (thanks, @ThomasSoeiro).The chunk option
collapse = TRUEalso applies to message blocks, including warnings, messages, and errors (thanks, @ThomasSoeiro, #108).pkg_desc()gained a new argumenttypeand the package description can be generated to either a table or a definition list now.The
embed_resourcesoption was buggy for deferred JS resources. Previously they were moved to<head>, but deferred scripts should be executed after the full DOM is ready, so they are moved before</body>instead if they are to be embedded.Fixed a bug in
pkg_manual()that may lead to omission of certain items when building TOC.
CHANGES IN litedown VERSION 0.8
CRAN release: 2025-11-02
Added a new chunk option
fig.keepto select plots to be kept in a code chunk (thanks, @Gabrielforest, #99). See https://pkg.yihui.org/litedown/book/#sec:option-fig for documentation.Improved support for LaTeX footnotes. The footnote identifier no longer has to be a number, and the footnote can include arbitrary elements (not necessarily a single paragraph).
The chunk option
results = 'hide'will implycollapse = TRUE, i.e., when text output is hidden, the source blocks will be merged (thanks, @jangorecki, #87).fuse(text = '# text')will be treated as Markdown input instead of R code input (thanks, @chuxinyuan, #102).Fixed the bug that the chunk option
fig.pathdoes not work when it does not contain/(thanks, @J-Moravec, #88).get_context('full_input')gives the full path to the input file offuse()(thanks, @rikivillalba, #104).
CHANGES IN litedown VERSION 0.7
CRAN release: 2025-04-08
pkg_manual()will exclude help pages with the keywordinternal(thanks, @TimTaylor, #78).pkg_news()will add links to Github users and issue numbers if the package is hosted on Github.Allow
,and.in superscripts and subscripts (thanks, @janlisec, #81).Special characters in bibliography entries such as
{\"u}can be correctly read now (thanks, @bastistician).Fixed a bug that inline code expressions (
`{lang} expr`) cannot be correctly located when the line has leading spaces that are not meaningful.Deleted vignettes
markdown-examplesandmarkdown-output. They are rendered on the package site now: https://pkg.yihui.org/litedown/examples/test-options.html
CHANGES IN litedown VERSION 0.6
CRAN release: 2025-02-27
Added a Markdown rendering option
offlineto download web resources when this option is set to true, so that the HTML output can be viewed offline (thanks, @TimTaylor, #73). See https://pkg.yihui.org/litedown/book/#sec:offline for more info.Added a function
get_context()to query thefuse()context such as the input file path or the output format (thanks, @MichaelChirico #67, @vincentarelbundock #70).Added a function
raw_text()to output raw text content in a code chunk (thanks, @vincentarelbundock, #69).Dropped the chunk option
ref.labeland added a new chunk optionfill, which is more general (ref.label = "LABEL"can be achieved by`<LABEL>`inside a chunk). See https://pkg.yihui.org/litedown/book/#sec:option-fill for more information.Fixed a bug that
fuse()fails to print the error location when the whole input document consists of a single chunk that throws an error (thanks, @kevinushey, yihui/knitr#2387).fuse_book()will ignore YAML headers in book chapters except for the index chapter.
CHANGES IN litedown VERSION 0.5
CRAN release: 2025-01-07
Added a wizard in
roam()to create new.Rmd/.md/.Rfiles with selected HTML features.Added a new engine
embedto embed text files via a code chunk.Changed the meaning of the chunk option
order: previously, higher values indicate earlier execution; now higher values indicate later execution. This is a breaking change, but the new meaning should feel more natural. For example,order = imeans to execute the chunk in the i-th step, andorder = i - 1.5means to move the chunk back 1.5 step in the queue so it will be executed earlier than its previous chunk. See https://pkg.yihui.org/litedown/book/#sec:option-order for details.Shortened the output format names
litedown::html_formattohtml, andlitedown::latex_formattolatex. The nameslitedown::*can still be used if you like.Added options
dollar,signif, andpowerto format numbers from inline code. See https://pkg.yihui.org/litedown/book/#sec:inline-code for details.When embedding SVG images in HTML output, embed their raw XML content instead of base64 encoding them.
Empty table headers are removed in HTML output (they may be generated from data frames or matrices without column names).
Added support for the chunk option
collapse = TRUE(thanks, @J-Moravec, #40).Added support for the chunk option
fig.dim, which is a shortcut forfig.widthandfig.height.Added a new function
vest()as another way to add CSS/JS assets to HTML output.Provided templates and a Github action
yihui/litedown/siteto build package websites. See https://pkg.yihui.org/litedown/book/#sec:pkg-site for details.Added an argument
examplestopkg_manual()to run examples and show their output (thanks, @TimTaylor, #54).Fixed a bug that the default CSS wouldn’t be added when a math expression exists on the page (thanks, @calvinw, #61).
Fixed a bug that cross-references to other chapters of a book could not be resolved when previewing a single chapter.
Fixed a bug that the file navigation by line numbers on code blocks stopped working in
litedown::roam()due to yihui/lite.js@5e06d19.Fixed a bug that
Rcode blocks could not be embedded when using prism.js for syntax highlighting (thanks, @TimTaylor, #53).pkg_manual()will point out the name of the problematic Rd file when the Rd file fails to convert to HTML (thanks, @BSchamberger).Dropped knitr and rmarkdown from the
Suggestsfield inDESCRIPTION. Previously, litedown allowedrmarkdown::render()to use the output formatslitedown::html_formatandlitedown::latex_format. Nowrmarkdown::render()is no longer supported, andlitedown::fuse()must be used instead.
CHANGES IN litedown VERSION 0.4
CRAN release: 2024-11-06
Provided an option
options(litedown.roam.cleanup = TRUE)to clean up the*__files/directory after previewing.Rmdor.Rfiles vialitedown::roam()(thanks, @TimTaylor, #36).Added the keyboard shortcut
Ctrl + K(orCommand + Kon macOS) for rendering a file to disk in thelitedown::roam()preview.Cross-references also work for LaTeX output now.
Fixed an error in the internal function
detect_pkg()duringR CMD checkon CRAN.Set
options(bitmapType = 'cairo')on macOS only whenxquartzis available. Previously onlycapabilities('cairo')was checked, which was not enough. This option can also be manually set viaoptions(bitmapType)in a code chunk if the automatic switch tocairois not desired.Fixed the bug that indented or quoted code blocks are not correctly indented or quoted when a code expression contains multiple lines.
Fixed the bug that the span syntax
[text](){...}doesn’t work whentextcontains markup (e.g., bold or italic).
CHANGES IN litedown VERSION 0.3
CRAN release: 2024-10-16
-
Added a new engine
mdto output Markdown text both verbatim and as-is, which can be useful for showing Markdown examples, e.g., -
Added a new engine
mermaidto generate Mermaid diagrams, e.g., Added helper functions
pkg_desc(),pkg_news(),pkg_citation(),pkg_code(), andpkg_manual()to get various package information for building the full package documentation as a single-file book (thanks, @jangorecki @llrs #24, @TimTaylor #22).LaTeX math environments such as equations can be numbered and cross-referenced now (thanks, @hturner, #32).
Section headings containing the class name “unlisted” will be excluded in the table of contents.
Provided a way to write
<span>with attributes based on empty links, i.e.,[text](){.class #id ...}. The empty URL here tellsmark()to treat the link as a<span>instead of<a>.Added back/forward/refresh/print buttons to the toolbar in the
litedown::roam()preview interface.Changed the behavior of
.Rmdand.Rfile links in thelitedown::roam()interface: previously, clicking on an.Rmdor.Rfilename will execute them; now it will only show their content, because fully executing the code may be expensive or even dangerous (especially when the files were not authored by you). A new “Run” button has been provided in the interface, on which you can click on to run a file in memory and preview it (i.e., the old behavior of clicking on filenames). You should use this button only if you trust the file.Added the JS asset
@mathjax-configto enable equation numbering by default when the JS math library is set to MathJax (thanks, @hturner, #32).Set
options(bitmapType = 'cairo')infuse()ifcapabilities('cairo')is TRUE, which will generate smaller bitmap plot files (e.g.,.png) than usingquartzorXlib, and is also a safer option forfuse()to be executed in parallel (rstudio/rmarkdown#2561).Added a new vignette engine
litedown::bookto make it possible to build multiple vignettes into a book. To use this engine, declare\VignetteEngine{litedown::book}only in the book index file (e.g.,index.Rmd) but not in other book chapter files.Added support for an array of multiple authors in the YAML metadata (thanks, @AlbertLei, #28). If the
authorfield in YAML is an array of length > 1, each author will be written to a separate<h2>in HTML output, or concatenated by\andin LaTeX output. Note that you can also write multiple authors in a single string (e.g.,author: "Jane X and John Y") instead of using an array (author: ["Jane X", "John Y"]), in which case the string will be treated as a single author (they will be put inside a single<h2>in HTML output).Fixed the bug that the leading
-,+, or*in a LaTeX math expression was recognized as the bullet list marker, which would invalidate the math expression (thanks, @hturner, #33).Changed the first
-to:in automatically generated element IDs, including section, figure, and table IDs, e.g., the IDsec-intro-methodsis changed tosec:intro-methods, andfig-nice-plotis changed tofig:nice-plot. You can still use-when manually assigning IDs to elements, e.g.,# Intro Methods {#sec-intro-methods}. For backward compatibility, cross-references using-will be resolved if the:version of the ID can be found, e.g.,@sec-intro-methodswill be resolved to@sec:intro-methodsif the former cannot be found but the latter can.Fixed a bug that when LaTeX math environments are written in raw LaTeX blocks (i.e.,
```{=latex}),mark()will not load the math JS library such as MathJax or KaTeX unless$ $or$$ $$expressions are present in the document.As-is output accepts attributes via the chunk option
attr.asisnow. If provided, as-is output will be wrapped in a fenced Div with these attributes.Numeric output from inline code will no longer be formatted if the value is wrapped in
I().The prefix for the automatic IDs of
h1headings has been changed fromsec:tochp:. For other levels of headings, the prefix is stillsec:.Provided a new option
embed_cleanupto clean up plot files that have been embedded in HTML output (thanks, @TimTaylor, #16).fuse()supports the output formatlitedown::markdown_formatnow, which generates the intermediate Markdown from R Markdown without further rendering Markdown to other formats. Using this output format is equivalent tofuse(..., output = '.md')orfuse(..., output = 'markdown')(thanks, @mikmart, #35).
CHANGES IN litedown VERSION 0.2
CRAN release: 2024-09-08
A data frame (or matrix/tibble) wrapped in
I()is fully printed to a table now by default. WithoutI(), data objects are truncated to 10 rows by default when printing to tables.When
options(litedown.fig.alt = TRUE)and the chunk optionfig.altis unset,fuse()will emit reminders about the missing alt text for code chunks containing plots (thanks, @TimTaylor, #23). Providing alt text can improve the accessibility of images in HTML output. To avoid omitting the alt text inadvertently, you can set the optionlitedown.fig.altin your.Rprofile.Added the meta variable
plain-titlefor HTML output, which is the plain version of the document title (i.e., without HTML tags), and used in the<title>tag.Check boxes from
- [ ] ...are no longer disabled in HTML output.The implicit latest version of jsdelivr resources will be resolved to an explicit version, e.g.,
https://cdn.jsdelivr.net/npm/@xiee/utils/css/default.csswill be resolved tohttps://cdn.jsdelivr.net/npm/@xiee/utils@X.Y.Z/css/default.css, whereX.Y.Zis the current latest version. This will make sure the HTML output containing jsdelivr resources is stable.