Skip to content

litedown 1.0

Latest

Choose a tag to compare

@yihui yihui released this 02 Nov 14:53
· 35 commits to main since this release
  • 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, but a ^ 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 (under system.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 classes side and side-right): the Description and Suggests fields are omitted, and URL and BugReports are merged into a Links field with short text links (e.g., Browse source code and Report a bug) instead of long bare URLs. The site template of pkg_site() uses it to put the description in a sidebar on the home page when the package has a README.md.

  • pkg_desc(type = "dl") shows only the authors (role aut) 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 by pkg_site().

  • Added a new pele engine to draw diagrams with Pele, a lightweight renderer for the Mermaid syntax. It takes the same input as the mermaid engine (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 the articles.Rmd template of pkg_site()). pkg_manual(), pkg_articles(), and pkg_examples() gain an argument groups to group help pages, vignettes, or examples, which defaults to the subfield manual, articles, or examples of site in _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 under Other, and a name that matches nothing is an error. Help pages with the keyword internal (e.g., re-exports) are listed only if a group names them. Without groups, the default listing is unchanged.

  • Moved the vignette slides to the example examples/045-snap-slides.Rmd, which is rendered on the package site: https://pkg.yihui.org/litedown/examples/045-snap-slides.html

  • fuse_site() with rebuild: "outdated" (the default) now also rebuilds pages when _litedown.yml is newer than their output files, instead of only comparing each page with its own source file.

  • On the home page of pkg_site(), the Links in the sidebar no longer include the URL of the package site itself (i.e., https://USER.github.io/PKG/, or the field url under site in _litedown.yml), and badges in README.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 BugReports field 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() (and mark()) failed to compile a .tex file to PDF when the output was in a different directory, because latexmk was not run in the output directory and could not find relative paths in the .tex file 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 echo can now take a numeric vector of line numbers to select which lines of the source code to display, e.g., echo = -1 hides the first line, and echo = 2:3 shows 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 the examples/ directory of a package, so the examples.Rmd page of the pkg_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., #1 in (#1, #2).

  • The default stylesheet no longer sets font-size: .9em on body, so body text is slightly larger (about 11%); the relative sizes of elements such as code, footnotes, and captions are unchanged.

  • HTML output now uses <embed> instead of <img> for PDF files included via ![](foo.pdf), and the PDF is base64 encoded when resources are embedded (a ?query or #hash in 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 class body is no longer used (use the selector main article in custom CSS instead), the metadata variable body-class now sets the class of <article> (the default is empty), and a new variable body-tag can 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 class site-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.js and pages.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 attributes data-pages-root and data-pages-front of <body>; the pagination waits for diagrams to settle and shows its progress, can be triggered by the event pagesjs:paginate (e.g., via the argument wait of xfun::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.js to 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 --accent and --muted-bg, without writing selectors (details). The CSS playground generates these variables, too.

  • The @appendix JS asset is no longer loaded by the article feature of vest() or by sites and books. A heading with the attribute .appendix is no longer wrapped in a div.appendix container; it only has the class appendix.