document the "Tracy" version of YAML syntax

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: litedown
 Type: Package
 Title: A Lightweight Version of R Markdown
-Version: 0.4.8
+Version: 0.4.9
 Authors@R: c(
    person("Yihui", "Xie", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0003-0645-5666", URL = "https://yihui.org")),
    person()
@@ -28,7 +28,7 @@ Suggests:
     tinytex
 License: MIT + file LICENSE
 URL: https://github.com/yihui/litedown
-BugReports: https://github.com/yihui/litedown/discussions
+BugReports: https://github.com/yihui/litedown/issues
 VignetteBuilder: litedown
 RoxygenNote: 7.3.2
 Encoding: UTF-8

R/site.R

@@ -125,9 +125,8 @@ nav_menu = function(info) {
 #' `bookdown::render_book()`, but one major differences is that all HTML output
 #' is written to one file, instead of one HTML file per chapter.
 #'
-#' If the output format ([html_format()] or [latex_format()]) needs to be
-#' customized, the settings should be written in the config file
-#' `_litedown.yml`, e.g.,
+#' If the output format needs to be customized, the settings should be written
+#' in the config file `_litedown.yml`, e.g.,
 #'
 #' ```
 #' ---
@@ -231,7 +230,7 @@ fuse_book = function(input = '.', output = NULL, envir = parent.frame()) {
       }
     }
     # remove YAML in the preview mode since we only need the body
-    if (length(preview)) out = xfun::yaml_body(split_lines(out))$body
+    if (length(preview)) out = yaml_body(split_lines(out))$body  # TODO: use parse = FALSE
 
     if (format != 'html') return(out)
     # add input filenames to the end for HTML output and wrap each file in a div

R/utils.R

@@ -1136,7 +1136,7 @@ base64_url = function(url, code, ext) {
       }
     ) else warning(
       'Unable to determine the font path in MathJax. Please report an issue to ',
-      'https://github.com/yihui/litedown/discussions and mention the URL ', url, '.'
+      'https://github.com/yihui/litedown/issues and mention the URL ', url, '.'
     )
   }
   # find `attr: url(resource)` and embed url resources in CSS

docs/01-start.Rmd

@@ -154,7 +154,7 @@ After all code has been executed, the output blocks will be merged to a Markdown
 document, which can be further rendered to a target output format such as HTML
 and LaTeX.
 
-:::: {.figure .box}
+:::: {#fig:humpty-dumpty .figure .box}
 ![Humpty
 Dumpty](https://upload.wikimedia.org/wikipedia/commons/b/b2/Humpty_Dumpty_1_-_WW_Denslow_-_Project_Gutenberg_etext_18546.jpg)
 

docs/02-fuse.Rmd

@@ -274,7 +274,7 @@ actual output but for illustration only).
 }
 ```
 
-::::: {.figure .box}
+::::: {#fig:attr-structure .figure .box}
 ::: {.attr-blocks .fenced-chunk}
 ``` {.md .open-fence .code-fence}
 :::: {.chunk}

docs/03-syntax.Rmd

@@ -8,15 +8,95 @@
 > (and Bob Dylan)
 :::
 
-## Basic syntax
+A Markdown document consists of a YAML frontmatter providing the document
+metadata, and a Markdown body. The frontmatter is optional, and (if provided)
+should be written using the syntax introduced in @sec:yaml-syntax. The syntax
+for the body is introduced in @sec:markdown-basic and @sec:markdown-addon.
+
+## YAML syntax
+
+YAML stands for "YAML Ain't Markup Language", which aims at being a
+"human-friendly data serialization language". You may judge how "human-friendly"
+it is[^03-syntax-1] by yourself after reading its specifications at
+<https://yaml.org>.
+
+[^03-syntax-1]: At least [it was not quite friendly to
+    Norwegian](https://news.ycombinator.com/item?id=36745212) until YAML 1.2.
+
+What we introduce in this section is a significantly trimmed-down version of
+YAML used by **litedown**. For now, let's call it TRACY, a recursive acronym for
+"TRACY Really Ain't Complete YAML" and also in honor of [Tracy
+Teal](https://en.wikipedia.org/wiki/Tracy_Teal) since she was once a nice boss
+of mine.
+
+The following example shows all types of data that TRACY supports:
+
+``` yaml
+a: 1
+b: "string"
+c: true
+d: null
+# e is also null
+e:
+# an expression
+f: !expr 1 + 1
+# vectors
+g: [1, 2, 3]
+h: ["foo", "bar"]
+# a nested list
+i:
+  i1: -1e8
+  i2: "another string"
+  i3:
+    i31: [true, false, true]
+any_character.is-okay: string not quoted
+```
+
+The TASTY specifications are:
+
+1.  Each line should be of the form `field: value`. The `field` name can use any
+    character. The `value` cannot span across multiple lines. If a line starts
+    with `#`, it will be ignored (i.e., it is treated as a comment). Any line
+    that is not of the form `field: value` or a comment are ignored.
+
+2.  Values must be character, numeric, logical, expressions, null, or vectors.
+
+    -   Character strings are quoted in either single or double quotes. Quotes
+        are optional when the values cannot be interpreted as other types of
+        values (e.g., numeric or logical).
+
+    -   Numeric values must consist of numbers (0-9), `+`, `-`, and `e`, and can
+        be converted to numbers.
+
+    -   Logical values must be either `true` or `false`, and cannot be other
+        values (e.g., `yes`, `YES`, `no`, `NO`,[^03-syntax-2] `on`, `off`,
+        `TRUE`, `FALSE`, `T`, `F`, `to be`, or `not to be`).
+
+    -   Expressions start with `!expr` followed by R code.
+
+    -   Null values can be either literally `null` or empty.
+
+    -   A vector consists of comma-separated character/numeric/logical values in
+        `[ ]`.
+
+3.  If `value` is empty, and the next line is of the form `field: value`
+    indented by 2 spaces, the next line will be treated as a child member of the
+    current line. One field can have multiple chidren indented to the same
+    level, and each child can have its children (further indented by 2 spaces).
+
+[^03-syntax-2]: TRACY is a good friend of Norwegian.
+
+See @sec:yaml-metadata for all possible fields supported in **litedown**.
+
+## Basic Markdown {#sec:markdown-basic}
 
 For the full list of supported document elements, please read the GFM spec.
 Below is a quick summary:
 
 -   Headings start with a number of `#`'s, e.g., `## level-two heading`.
 
 -   Inline elements: `**strong**`, `_emphasis_`, `~~strikethrough~~`,
-    `[text](link)`, and `![alt](image/path)`.[^03-syntax-1]
+    `[text](link)`, and `![alt](image/path)`.[^03-syntax-3]
 
 -   Inline code is written in a pair of backticks, e.g., `` `code` ``. Code
     blocks can be indented, or fenced by ```` ``` ````.
@@ -31,12 +111,12 @@ Below is a quick summary:
     table, which can be generated by `knitr::kable(x, "pipe")` or
     `xfun::md_table()`).
 
-[^03-syntax-1]: Please note that for links and images, their URLs [should not
+[^03-syntax-3]: Please note that for links and images, their URLs [should not
     contain spaces](https://spec.commonmark.org/current/#link-destination). If
     they do, the URLs must be enclosed in `<>`, e.g.,
     `![alt](<some dir/a subdir/foo.png>).`
 
-## Add-on features
+## Add-on features {#sec:markdown-addon}
 
 In addition to GFM features, the **litedown** package also supports the
 following features.
@@ -162,19 +242,15 @@ Insert a footnote here.[^1]
 [^1]: This is the footnote.
 ```
 
-The support is limited for LaTeX output at the moment,[^03-syntax-2] and there
-are two caveats if the document is intended to be converted to LaTeX:
-
-[^03-syntax-2]: If you know C, I'll truly appreciate it if you could help with
-    the LaTeX implementation in GFM:
-    <https://github.com/github/cmark-gfm/issues/314>
+The support is limited for LaTeX output at the moment, and there are two caveats
+if the document is intended to be converted to LaTeX:
 
 -   The footnote content must be a single paragraph.
 
--   Only numbers[^03-syntax-3] are supported as identifiers, and other types of
+-   Only numbers[^03-syntax-4] are supported as identifiers, and other types of
     identifiers are not recognized.
 
-[^03-syntax-3]: The specific number doesn't matter, as long as it's a unique
+[^03-syntax-4]: The specific number doesn't matter, as long as it's a unique
     footnote number in the document. For example, the first footnote can be
     `[^100]` and the second can be `[^64]`. Eventually they will appear as `[1]`
     and `[2]`. If you use the RStudio visual editor to edit Markdown documents,
@@ -441,13 +517,17 @@ You can cross-reference any other type of elements by adding empty anchors of
 the form `[](#@ID)` into them, e.g.,
 
 ```{md, attr.asis = '.callout-output'}
-::: {style="background: ghostwhite; padding: 1px 1em;"}
+::: {#blk:example style="background: ghostwhite; padding: 1px 1em;"}
 [](#@blk:example) This is a numbered block.
 :::
 
 We can cross-reference @blk:example.
 ```
 
+Note that we also added the ID (`#blk:example`) to the fenced Div to make it the
+target of the cross reference, i.e., when you click on the reference, the
+browser will navigate to the Div.
+
 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

docs/04-mark.Rmd

@@ -437,9 +437,8 @@ output:
 
 ### Format-specific variables
 
-Other variables need to be specified under
-`output -> litedown::*_format -> meta`, where `*` can be `html` or `latex`,
-e.g.,
+Other variables need to be specified under `output -> * -> meta`, where `*` can
+be `html` or `latex`, e.g.,
 
 ``` yaml
 ---
@@ -553,8 +552,8 @@ and the values of variables in the metadata will be passed to your template.
 ### Setting options in YAML
 
 Besides metadata variables, the aforementioned Markdown options
-(@sec:markdown-options) can also be set in YAML under
-`output -> litedown::*_format -> options`, e.g.,
+(@sec:markdown-options) can also be set in YAML under `output -> * -> options`,
+e.g.,
 
 ``` yaml
 output:

docs/07-site.Rmd

@@ -14,8 +14,8 @@ Books and websites are usually based on multiple input files under a directory.
 For a directory to be recognized as a book or website project, it needs to
 contain a configuration file named `_litedown.yml`.
 
-If you want to customize the output formats `html_format` or `latex_format` for
-books or websites, you should do it in `_litedown.yml`, e.g.,
+If you want to customize the output formats for books or websites, you should do
+it in `_litedown.yml`, e.g.,
 
 ``` yaml
 output:
@@ -85,7 +85,7 @@ page.
 
 The `_litedown.yml` file should contain a top-level field named `site`, and you
 are likely to customize the `meta` variables `css`, `include_before`, and
-`include_after` for the `html_format`, e.g.,
+`include_after` for the `html` format, e.g.,
 
 ``` yaml
 site: