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