Repository navigation
-
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.html -
fuse_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.