markdown.Rmd

---
title: "Using nomnoml in R markdown"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using nomnoml in R markdown}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(nomnoml)
```


You can use `nomnoml` chunks in R Markdown with HTML output.  Here is an example R Markdown, including the yaml header.  Notice that you can use `{nomnoml}` chunks and these will be rendered by the `nomnoml` engine.

````markdown
---
title: "A Diagram"
output: html_document
---

`r ''````{r, setup, include=FALSE}
library(nomnoml)
```

`r ''````{nomnoml}
#stroke: orange
#.box: fill=#8f8 dashed visual=ellipse

[A]-[B]-[<box>C]
```
````

## Chunk examples

Here is a rendered example of a chunk, using the default plot size:


```{nomnoml, svg=TRUE}
#stroke: #a86128
#direction: down
[<frame>Decorator pattern|
  [<abstract>Component||+ operation()]
  [Client] depends --> [Component]
  [Decorator|- next: Component]
  [Decorator] decorates -- [ConcreteComponent]
  [Component] <:- [Decorator]
  [Component] <:- [ConcreteComponent]
]
```


And the same diagram, this time with specified size:


```{nomnoml, svg=TRUE, width="2in", height="2in"}
#stroke: #a86128
#direction: down
[<frame>Decorator pattern|
  [<abstract>Component||+ operation()]
  [Client] depends --> [Component]
  [Decorator|- next: Component]
  [Decorator] decorates -- [ConcreteComponent]
  [Component] <:- [Decorator]
  [Component] <:- [ConcreteComponent]
]
```


## Unicode chunks

Unicode escapes (using R conventions) can be used in code chunks.

In the next example, the unicode character `\u03b1` displays as greek alpha (`r "\u03B1"`).

```` markdown
`r ''````{nomnoml, escape = TRUE}
[Hello]-\u03B1[Unicode!]
```
````

```{nomnoml echo=FALSE, svg = TRUE, height = "1in"}
[Hello]-\u03B1[Unicode!]
```

Of course, you can use the unicode character directly

```` markdown
`r ''````{nomnoml, escape = TRUE}
[Hello]-α[Unicode!]
```
````

```{nomnoml echo=FALSE, svg = TRUE, height = "1in"}
[Hello]-α[Unicode!]
```

To include backslashes in labels, specify `escape = TRUE`:

```` markdown
`r ''````{nomnoml, escape = TRUE}
[Hello]-\A[Escape character!]
```
````


```{nomnoml echo=FALSE, svg = TRUE, height = "1in", escape = TRUE}
[Hello]-\A[Escape character!]
```


## Multiple nodes per line

During 2023 the `nomnoml.js` library added support for multiple nodes in a single line.  The R package incorporates these changes since version 0.3.0.

This means it's possible to create diagrams like this:

```{nomnoml svg = TRUE}
#direction: right
[<start>start] -> [process] -> [<end>end]
```