` without the `
`
+wrapper via `
$title$
` instead of using `$title_$`.
+
+When these top-level variables are also provided as `meta` variables for an
+output format, the latter will override the former, e.g.,
+
+``` yaml
+title: "Global Title"
+output:
+ litedown::html_format:
+ meta:
+ title: "Title for HTML output"
+ litedown::latex_format:
+ meta:
+ title: "Title for LaTeX output"
+```
+
+### Format-specific variables
Other variables need to be specified under
`output -> litedown::*_format -> meta`, where `*` can be `html` or `latex`,
@@ -352,76 +400,97 @@ templates:
(HTML/LaTeX) code or a code file to be included in the header, before the
body, or after the body of the output.
-Variables specific to the HTML template:
+--------------------------------------------------------------------------------
+
+The following variables are for HTML templates:
+
+#### **The `css` variable**
+
+A vector of CSS files to be included in the output. The default value is
+`litedown:::pkg_file('resources', 'default.css')`.
+
+If you want to use built-in CSS files in this package, you can only specify the
+base name, e.g., `default` means `default.css` in this package.
-- `css`: A vector of CSS files to be included in the output. The default value
- is `litedown:::pkg_file('resources', 'default.css')`.
+You can also use web resources, e.g., `https://example.org/style.css`. One
+special case is [jsdelivr](https://www.jsdelivr.com) resources: if a `css` value
+starts with `@`, it will be recognized as a jsdelivr.com resource. if you are
+not familiar with jsdelivr, you may read its documentation to understand the
+following example URLs. The shorthand syntax is as follows (`CDN` stands for
+`https://cdn.jsdelivr.net`):
- If you want to use built-in CSS files in this package, you can only specify
- the base name, e.g., `default` means `default.css` in this package.
+- `@foo` (without a filename extension) will be converted to
+ `CDN/npm/@xiee/utils/css/foo.min.css`, e.g., `@default` means
+ `CDN/npm/@xiee/utils/css/default.min.css`. If you prefer the `.css`
+ extension over `.min.css`, you can use `@default.css`.
- You can also use web resources, e.g., `https://example.org/style.css`. One
- special case is [jsdelivr](https://www.jsdelivr.com) resources: if a `css`
- value starts with `@`, it will be recognized as a jsdelivr.com resource. if
- you are not familiar with jsdelivr, you may read its documentation to
- understand the following example URLs. The shorthand syntax is as follows
- (`CDN` stands for `https://cdn.jsdelivr.net`):
+- `@foo@version` (a filename followed by a version number) will be converted
+ to `CDN/npm/@xiee/utils@version/css/foo.min.css`, e.g., `@article@1.12.0`
+ means `CDN/npm/@xiee/utils@1.12.0/css/article.min.css`.
- - `@foo` (without a filename extension) will be converted to
- `CDN/npm/@xiee/utils/css/foo.min.css`, e.g., `@default` means
- `CDN/npm/@xiee/utils/css/default.min.css`. If you prefer the `.css`
- extension over `.min.css`, you can use `@default.css`.
+- `@path/to/file` (i.e., a value that contains slashes) will be converted to
+ `CDN/path/to/file`, e.g., `@npm/@xiee/utils/js/center-img.js` will be
+ converted to `CDN/npm/@xiee/utils/js/center-img.min.js`.
- - `@foo@version` (a filename followed by a version number) will be
- converted to `CDN/npm/@xiee/utils@version/css/foo.min.css`, e.g.,
- `@article@1.12.0` means
- `CDN/npm/@xiee/utils@1.12.0/css/article.min.css`.
+- `@path/to/file-1,file-2` (comma-separated values and later values do not
+ contain slashes) will be converted to
+ `CDN/combine/path/to/file-1,path/to/file-2` (this can be useful to
+ [combine](https://www.jsdelivr.com/documentation#id-combine-multiple-files)
+ multiple resources and load all at once).
- - `@path/to/file` (i.e., a value that contains slashes) will be converted
- to `CDN/path/to/file`, e.g., `@npm/@xiee/utils/js/center-img.js` will be
- converted to `CDN/npm/@xiee/utils/js/center-img.min.js`.
+- `@path-1/to/file-1,path-2/to/file-2` (comma-separated values and later
+ values contain slashes) will be converted to
+ `CDN/combine/path-1/to/file-1,path-2/to/file-2`.
- - `@path/to/file-1,file-2` (comma-separated values and later values do not
- contain slashes) will be converted to
- `CDN/combine/path/to/file-1,path/to/file-2` (this can be useful to
- [combine](https://www.jsdelivr.com/documentation#id-combine-multiple-files)
- multiple resources and load all at once).
+This provides a way to reduce the output HTML file size by loading CSS from the
+web instead of embedding inside HTML, at the cost of requiring Internet
+connection when viewing the HTML file. If you need the external web resources to
+work after you go offline, you can enable `"https"` in the Markdown option
+`embed_resources` in advance to embed the resources.
- - `@path-1/to/file-1,path-2/to/file-2` (comma-separated values and later
- values contain slashes) will be converted to
- `CDN/combine/path-1/to/file-1,path-2/to/file-2`.
+#### The `js` variable
- This provides a way to reduce the output HTML file size by loading CSS from
- the web instead of embedding inside HTML, at the cost of requiring Internet
- connection when viewing the HTML file. If you need the external web
- resources to work after you go offline, you can enable `"https"` in the
- Markdown option `embed_resources` in advance to embed the resources.
+A vector of JavaScript files to be included in the output. The syntax is the
+same as the `css` variable, e.g., `snap` means `snap.js` in this package, and
+`@snap` means a "jsdelivr" resource.
-- `js`: A vector of JavaScript files to be included in the output. The syntax
- is the same as the `css` variable, e.g., `snap` means `snap.js` in this
- package, and `@snap` means a "jsdelivr" resource.
+#### The `body-class` variable
-- `body-class`: A class name for the main body (the default value is `body`).
+A class name for the main body (the default value is `body`).
-Variables specific to the LaTeX template:
+--------------------------------------------------------------------------------
-- `classoption`: A string containing options for the document class.
+The following variables are for LaTeX templates:
-- `documentclass`: The document class (by default, `article`).
+#### The `classoption` variable
-Note that you can use either underscores or hyphens in the variable names.
-Underscores will be normalized to hyphens internally, e.g., `header_includes`
+A string containing options for the document class.
+
+#### The `documentclass` variable
+
+The document class (by default, `article`).
+
+### Naming convention of variables
+
+A variable name must consist of alphanumeric characters and hyphens only. You
+could use underscores in variable names in the metadata, but please note that
+underscores will be normalized to hyphens internally, e.g., `header_includes`
will be converted to `header-includes`. This means if you use a custom template,
you must use hyphens instead of underscores as separators in variable names in
the template.
+### Using custom variables
+
The above are variables supported in the default templates. If you use a custom
-template, you can use arbitrary variable names consisting of alphanumeric
-characters and hyphens, except for `$body$` (which is a reserved name), and your
-metadata values will be passed to these variables in your template.
+template, you can use arbitrary variable names following the naming convention
+(except for `body`, which is a reserved name and cannot be used in metadata),
+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 can also be set
-in YAML under `output -> litedown::*_format -> options`, e.g.,
+Besides metadata variables, the aforementioned Markdown options
+(@sec:markdown-options) can also be set in YAML under
+`output -> litedown::*_format -> options`, e.g.,
``` yaml
output:
@@ -434,6 +503,8 @@ output:
languages: [diff, latex]
```
+### Other fields in YAML
+
See the help page `?litedown::html_format` for possible fields in addiction to
`meta` and `options` that can be specified under the format name, e.g.,
diff --git a/docs/04-assets.Rmd b/docs/04-assets.Rmd
index c987467..03d8a9a 100644
--- a/docs/04-assets.Rmd
+++ b/docs/04-assets.Rmd
@@ -25,7 +25,8 @@ output:
For the sake of brevity, we will omit the full YAML fields in examples
throughout this chapter but only use the `css` and `js` fields. A file name
`foo.js` denotes the file under the `js/` directory of the aforementioned
-`yihui/misc.js` repository. Similarly, `foo.css` is under the `css/` directory.
+[`yihui/misc.js` repository](https://github.com/yihui/misc.js). Similarly,
+`foo.css` is under the `css/` directory.
All these CSS/JS resources can be used offline, and there are two ways to do it.
One way is to clone the GitHub repo to your working directory, and use the files
@@ -64,7 +65,7 @@ You can learn more in `vignette('slides', package = 'litedown')`.
## HTML articles
-We can style an HTML page in an article format via the following CSS and JS:
+You can style an HTML page in an article format via the following CSS and JS:
``` yaml
css: ["@default", "@article"]
@@ -231,18 +232,18 @@ a quote, just use the blockquote syntax `>`, e.g.,
#### Margin embedding
-::: embed-right
-```{r, echo=FALSE}
-mtcars[1:4, 1:8]
-```
-:::
-
You can embed elements on the left or right margin using a fenced `Div` with the
class `.embed-left` or `.embed-right`. These elements will float to the left or
right and exceed the margin by about 200px, which can save some space in the
article body. You can use the extra space to explain the embedded element with
text.
+::: embed-right
+```{r, echo=FALSE}
+mtcars[1:4, 1:8]
+```
+:::
+
We have embedded a table of the first 4 rows of the `mtcars` data on the right
margin, which you can see if the browser window is wide enough.