diff --git a/DESCRIPTION b/DESCRIPTION index 25b0cda..3cd5c85 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: litedown Type: Package Title: A Lightweight Version of R Markdown -Version: 0.2.10 +Version: 0.2.11 Authors@R: c( person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name", comment = c(ORCID = "0000-0003-0645-5666")), person() diff --git a/NEWS.md b/NEWS.md index 5a099d3..2a0d0ef 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,16 @@ # CHANGES IN litedown VERSION 0.3 +- Added a new engine `md` to output Markdown text both verbatim and as-is, which can be useful for showing Markdown examples, e.g., + + ````md + ```{md} + You can see both the _source_ and _output_ of + this `md` chunk. + ``` + + You can also use `{md} the engine **inline**`. + ```` + - Added helper functions `pkg_desc()`, `pkg_news()`, `pkg_citation()`, and `pkg_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). diff --git a/R/fuse.R b/R/fuse.R index 0d340eb..6309615 100644 --- a/R/fuse.R +++ b/R/fuse.R @@ -939,6 +939,16 @@ eng_r = function(x, inline = FALSE, ...) { do.call(xfun::record, c(list(code = x$source, envir = fuse_env()), args)) } +# the Markdown engine: echo Markdown source verbatim, and also output it as-is +eng_md = function(x, inline = FALSE, ...) { + s = x$source + if (inline) { + f = unlist(match_all(s, '`+')) # how many backticks to quote the text? + f = if (length(f)) paste0('`', max(f)) else '`' + one_string(c(f, s, f, s), ' ') + } else list(new_source(s), new_asis(s)) +} + #' Language engines #' #' Get or set language engines for evaluating code chunks and inline code. @@ -962,7 +972,7 @@ eng_r = function(x, inline = FALSE, ...) { #' litedown::engines() # built-in engines engines = new_opts() engines( - r = eng_r, + r = eng_r, md = eng_md, css = function(x, ...) eng_html(x, '', ...), js = function(x, ...) eng_html(x, '', ...) ) diff --git a/docs/02-syntax.Rmd b/docs/02-syntax.Rmd index 1441367..9b2437e 100644 --- a/docs/02-syntax.Rmd +++ b/docs/02-syntax.Rmd @@ -78,7 +78,7 @@ line. Valid examples: -``` md +``` tex $x + y$ $x + y$ text $x + y$ text @@ -108,11 +108,14 @@ $$ LaTeX math environments are also supported, e.g., below are an `align` environment and an `equation` environment: -```{=latex} +```{md, attr.source='.tex', attr.asis='.callout-example'} \begin{align} a^{2}+b^{2} & = c^{2}\\ -\sin^{2}(\theta)+\cos^{2}(\theta) & = 1\label{eq:pyth-identity} -\end{align} \begin{equation} +\sin^{2}(\theta)+\cos^{2}(\theta) & = 1 +\label{eq:pyth-identity} +\end{align} + +\begin{equation} \begin{split} (a+b)^2 &=(a+b)(a+b)\\ &=a^2+2ab+b^2 @@ -120,20 +123,13 @@ a^{2}+b^{2} & = c^{2}\\ \end{equation} ``` -These math environments can be written in raw LaTeX blocks, and they work for -both LaTeX and HTML output, e.g., - -```` markdown -```{=latex} -\begin{align} -a^{2}+b^{2} & = c^{2}\\ -\sin^{2}(\theta)+\cos^{2}(\theta) & = 1 -\end{align} -``` -```` +These math environments can be written as either nake LaTeX code or raw LaTeX +blocks (```` ```{=latex} ````), but we recommend that you use raw LaTeX blocks +because they are more robust. LaTeX math environments work for both LaTeX and +HTML output. For HTML output, it is up to the JavaScript library (MathJax or KaTeX) whether a -math environment can be rendered. +math environment can be rendered (@sec:js-math). ### Superscripts and subscripts @@ -361,39 +357,44 @@ parentheses, you can use `@eq:` instead of `@eqn:`, e.g., `Eq. [@eq:*]` (using the label "Eq." and square brackets). In addition to equation numbers, you can also specify a tag for an equation via -`\tag{}` and refer to the equations by its tag. +`\tag{}` and refer to the equations by its tag, e.g., +```{md, attr.source='.tex', attr.asis='.callout-example'} For a right-angled triangle, we are all familiar with @eqn:pyth-theorem. \begin{equation} a^2 + b^2 = c^2 \label{eq:pyth-theorem} \tag{PT} \end{equation} +``` #### Arbitrary elements You can cross-reference any other type of elements by adding empty anchors of the form `[](#@ID)` into them, e.g., -::: callout-tip -[ ](#@clt:example) This is a numbered tip callout. +```{md, attr.asis='.callout-example'} +::: {style="background: ghostwhite; padding: 1px 1em;"} +[](#@blk:example) This is a numbered block. ::: -We can cross-reference @clt:example. +We can cross-reference @blk:example. +``` For HTML output, we can style the numbers and references with CSS. Element numbers are wrapped in ``, and references are wrapped in ``, where `*` is the ID prefix -(e.g., `fig`, `tab`, and `eqn`). For example, we can add the label "Tip" to the -number and reference of the callout above: +(e.g., `fig`, `tab`, and `eqn`). For example, we can add the label "Block" to +the number and reference of the block above: ```{css} -.ref-number-clt::before, .cross-ref-clt::before { - content: "Tip "; +.ref-number-blk::before, .cross-ref-blk::before { + content: "Block "; } -.ref-number-clt { +.ref-number-blk { font-weight: bold; + font-style: italic; } -.ref-number-clt::after { +.ref-number-blk::after { content: ". " } ``` diff --git a/docs/index.Rmd b/docs/index.Rmd index 1fbc290..74c9b8d 100644 --- a/docs/index.Rmd +++ b/docs/index.Rmd @@ -6,7 +6,7 @@ date: "`{r} Sys.Date()`" # Preface {.unnumbered} -::: callout-caution +::: callout-important The **litedown** package is still new and experimental. The documentation is very incomplete. Besides, **litedown** was designed for minimalists with a limited scope. Average users should perhaps consider using **rmarkdown** or