add an md engine for show both Markdown source and output

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 = "[email protected]", comment = c(ORCID = "0000-0003-0645-5666")),
    person()

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).

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, '<style type="text/css">', '</style>', ...),
   js = function(x, ...) eng_html(x, '<script>', '</script>', ...)
 )

docs/02-syntax.Rmd

@@ -78,7 +78,7 @@ line.
 
 Valid examples:
 
-``` md
+``` tex
 $x + y$
   $x + y$
 text $x + y$ text
@@ -108,32 +108,28 @@ $$
 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
   \end{split}
 \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 `<span class="ref-number-*"></span>`, and references are
 wrapped in `<span class="cross-ref-*"></span>`, 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: ". "
 }
 ```

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