Skip to content

Commit

Permalink
Add default file format when Quarto format is typst (#7)
Browse files Browse the repository at this point in the history 
* Add default SVG format for Typst output

Also add DarkMauve and DarkFlagshipTerrastruct as explicit theme options

* Remove duplicate theme

DarkMauve was already in the theme list

* Allow uppercase layout values

Also:

- Adds is_nonempty_string helper function
- Appends random number for diagram file name
- Use d2 file extension not txt for input
- Allow alternate syntax for attribute classes on code blocks

* Fix d2 class check

Also:

- Add support for reading d2 diagrams from external files using `file` parameter. Block text is ignored if file parameter is supplied.
- Add support for alternate code block syntax without curly braces.
- Insert rendered diagrams into the Pandoc mediabag when `embed_type="link"`
- Refactor to add helper functions `setPreD2RenderOptions` and `setD2RenderFormat`

* Update CHANGELOG.md

* Use d2-render instead of svg-convert for temp directory

* Add support for gif format

Also

- add animate_interval parameter
- drop setD2RenderFormat helper function
- use quarto.project.output_directory to set default folder
- revise check for d2 code block class
- replace codeblock text if file is provided
- add support for tala layout

* Use outputPath (not mediabag) if folder is supplied

* Update README

* Fix typo

* Fix error in inline embedding logic

* Add check for d2 or txt file extension in file option

Also:

- add check to see if file exists
- Improve handling of code block formatting (when echo=true)
- remove duplicative processing for options.pad and options.animate_interval

* Update README

* Add partial support for code folding (#6)

Based on https://github.com/shafayetShafee/add-code-files

* Add typst format tests w/ multiple diagram formats

Also add external d2 file to test file argument

* Update CHANGELOG.md

---------

Co-authored-by: Robrecht Cannoodt <[email protected]>
  • Loading branch information
@elipousson @rcannood
elipousson and rcannood authored Mar 20, 2024
1 parent cc97e8b commit 1f6fb19
Show file tree
Hide file tree
Showing 11 changed files with 817 additions and 260 deletions.
17 changes: 14 additions & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,32 @@

* Added minimal CI testing using GitHub actions (#10).

* Make SVG as the default diagram format when using the [Typst output format](https://quarto.org/docs/output-formats/typst.html) (#7, @elipousson).

* Add support for reading d2 diagrams from external files using `file` parameter. Block text is replaced with file contents (#7, @elipousson).

* Use Pandoc mediabag for rendered diagram images when `embed_type="link"` (#7, @elipousson).

* Add support for alternate code block syntax without curly braces (#7, @elipousson).

## BUG FIXES

* Added tala to the list of layouts (#9, thanks @tosaddler!).
* Added [TALA](https://d2lang.com/tour/tala/) to the list of layouts (#9, @tosaddler).

## OTHER

* Refactor to add helper functions `setPreD2RenderOptions` and `is_nonempty_string`.

# quarto-d2 1.1.0

## NEW FUNCTIONALITY

- When the output type is html and the image format is svg, also setting the `embed_type="raw"` will embed the svg directly into the html document (#1). This is useful enabling interactive content such as hover or links to work.


# quarto-d2 1.0.0

Initial release. Main features:

- Render [D2](https://d2lang.com) diagrams directly within your [Quarto](https://quarto.org) markdown documents.
- Control the appearance and layout of your diagrams using global settings or code block attributes.
- Tune the width and height of the resulting figures using the "width" and "height" arguments.
- Tune the width and height of the resulting figures using the "width" and "height" arguments.
90 changes: 48 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# D2 Extension For Quarto


This [Quarto](https://quarto.org) extension allows you to render
[D2](https://d2lang.com) diagrams directly within your markdown
documents.
Expand Down Expand Up @@ -34,7 +35,13 @@ quarto add data-intuitive/quarto-d2
This will install the extension under the `_extensions` subdirectory. If
you’re using version control, you will want to check in this directory.

## Example
## Examples

D2 can be used for simple diagrams.

![](images/diagram-1.svg)

And for more complex diagrams.

<div>

Expand Down Expand Up @@ -85,68 +92,61 @@ user -> network.portal.UI: access {
}
```

<img src="./images/diagram-1.svg" style="width:50.0%" />
<img src="images/diagram-2.svg" style="width:50.0%" />

</div>

## Usage
The enclosing curly brakets are optional if you are only using document
level options. Quarto block-level options, e.g. `#|`, are not currently
supported.

To use the d2 filter, add the d2 filter to your quarto document. Next,
add the `.d2` class to any code blocks containing D2 diagram code. Here
is a basic example:

```` markdown
---
title: "D2 Example"
filters:
- d2
---

```{.d2}
x -> y
```
````

With this setup, the `d2` filter will process any code blocks with the
`.d2` class, applying the attributes you specify.

That’s it! Now you know how to use the `d2` filter to generate diagrams
in your quarto documents.
![](images/diagram-3.svg)

## Attributes

You can specify additional attributes to control the appearance and
layout of the diagram.
layout of the diagram and document:

- `theme`: Specifies the theme of the diagram. Default is
`"NeutralDefault"`. Options are `"NeutralDefault"`, `"NeutralGrey"`,
`"FlagshipTerrastruc"t`, `"CoolClassics"`, `"MixedBerryBlue"`,
`"GrapeSoda"`, `"Aubergine"`, `"ColorblindClear"`,
`"VanillaNitroCola"`, `"ShirelyTemple"`, `"EarthTones"`,
`"EvergladeGreen"`, `"ButteredToast"`, `"DarkMauve"`, `"Terminal"`,
`"TerminalGrayscale"`, `"Origami"`.
`"FlagshipTerrastruct"`, `"DarkFlagshipTerrastruct"`,
`"CoolClassics"`, `"MixedBerryBlue"`, `"GrapeSoda"`, `"Aubergine"`,
`"ColorblindClear"`, `"VanillaNitroCola"`, `"ShirelyTemple"`,
`"EarthTones"`, `"EvergladeGreen"`, `"ButteredToast"`, `"DarkMauve"`,
`"Terminal"`, `"TerminalGrayscale"`, and `"Origami"`.
- `layout`: Specifies the layout algorithm to use. Default is `"elk"`.
Options are `"dagre"`, `"elk"`, `"tala"`.
Options are `"dagre"`, `"elk"`, `"tala"`. layout is not case sensitive
so `"ELK"` or `"TALA"` are also supported.
- `format`: Specifies the format of the output image. Default is `svg`.
Option are `"svg"`, `"png"`, `"pdf"`.
Option are `"svg"`, `"png"`, `"pdf"`, `"gif"`.
- `sketch`: Whether to use a “sketch” style for the diagram. Default is
`false`.
- `pad`: Amount of padding around the diagram. Default is `100`.
- `pad`: Amount of padding around the diagram in pixels. Default is
`100`.
- `caption`: Caption to add to the diagram.
- `folder`: Folder where the generated diagram will be saved. If not
provided, the image will be embedded inline in the document (HTML
only).
- `filename`: Name of the output file.
- `width`: Width of the output image. Default is `100%`. Examples are
`"100px"`, `"50%"`, `"3cm"`.
- `height`: Height of the output image. Default is `auto`. Examples are
`"100px"`, `"50%"`, `"3cm"`.
- `echo`: Whether to echo the original diagram code in the output.
Default is `false`.

You can also replace the contents of the block with an external D2 file
by using the `file` parameter. `file` must be an existing file ending in
a “d2” or “txt” file extension. Other parameters related to rendering
and embedding diagrams include:

- `folder`: Folder where the generated diagram will be saved. If not
provided, the image will be embedded inline in the document (HTML
only).
- `filename`: Name of the output file.
- `embed_mode`: How to embed the diagram in the output. Default is
`"inline"` for HTML output and `"link"` for other output formats.
Options are `"inline"`, `"link"`, `"raw"`.

Note that for Typst format output the width and height can’t be supplied
as a percent value.

Here’s an example that uses multiple attributes:

```` markdown
Expand Down Expand Up @@ -175,6 +175,16 @@ x -> y -> z
```
````

## Setting an input file

You can specify an input d2 file. If `echo=true`, the contents of the
file block is replaced by the contents of the file.

```` markdown
```{.d2 file="./diagram.d2"}
```
````

## Setting output folder and file name

You can specify a folder where the generated diagram will be saved using
Expand All @@ -187,15 +197,11 @@ x -> y -> z
```
````

<div>

> **Note**
> [!NOTE]
>
> If the `folder` attribute is not provided and the output format is
> HTML, the image will be embedded inline in the document.
</div>

## Interactive diagrams

Interactive diagrams will only work when the Quarto output format is
Expand Down
61 changes: 35 additions & 26 deletions README.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ filters:
- d2
d2:
layout: "elk"
folder: "images"
---

This [Quarto](https://quarto.org) extension allows you to render [D2](https://d2lang.com) diagrams directly within your markdown documents.
Expand Down Expand Up @@ -34,10 +35,17 @@ quarto add data-intuitive/quarto-d2
This will install the extension under the `_extensions` subdirectory.
If you're using version control, you will want to check in this directory.

## Examples

D2 can be used for simple diagrams.

## Example

```{.d2}
x -> y: hello world
```


And for more complex diagrams.

```{.d2 width="50%" echo="true"}
logs: {
Expand Down Expand Up @@ -87,44 +95,36 @@ user -> network.portal.UI: access {
```


## Usage
The enclosing curly brakets are optional if you are only using document level options. Quarto block-level options, e.g. `#|`, are not currently supported.

To use the d2 filter, add the d2 filter to your quarto document. Next, add the `.d2` class to any code blocks containing D2 diagram code. Here is a basic example:


````markdown
---
title: "D2 Example"
filters:
- d2
---

```{.d2}
x -> y
```d2
Database -> S3: backup
Database -> S3
Database -> S3: backup
```
````

With this setup, the `d2` filter will process any code blocks with the `.d2` class, applying the attributes you specify.

That's it! Now you know how to use the `d2` filter to generate diagrams in your quarto documents.

## Attributes

You can specify additional attributes to control the appearance and layout of the diagram.
You can specify additional attributes to control the appearance and layout of the diagram and document:

- `theme`: Specifies the theme of the diagram. Default is `"NeutralDefault"`. Options are `"NeutralDefault"`, `"NeutralGrey"`, `"FlagshipTerrastruc"t`, `"CoolClassics"`, `"MixedBerryBlue"`, `"GrapeSoda"`, `"Aubergine"`, `"ColorblindClear"`, `"VanillaNitroCola"`, `"ShirelyTemple"`, `"EarthTones"`, `"EvergladeGreen"`, `"ButteredToast"`, `"DarkMauve"`, `"Terminal"`, `"TerminalGrayscale"`, `"Origami"`.
- `layout`: Specifies the layout algorithm to use. Default is `"elk"`. Options are `"dagre"`, `"elk"`, `"tala"`.
- `format`: Specifies the format of the output image. Default is `svg`. Option are `"svg"`, `"png"`, `"pdf"`.
- `theme`: Specifies the theme of the diagram. Default is `"NeutralDefault"`. Options are `"NeutralDefault"`, `"NeutralGrey"`, `"FlagshipTerrastruct"`, `"DarkFlagshipTerrastruct"`, `"CoolClassics"`, `"MixedBerryBlue"`, `"GrapeSoda"`, `"Aubergine"`, `"ColorblindClear"`, `"VanillaNitroCola"`, `"ShirelyTemple"`, `"EarthTones"`, `"EvergladeGreen"`, `"ButteredToast"`, `"DarkMauve"`, `"Terminal"`, `"TerminalGrayscale"`, and `"Origami"`.
- `layout`: Specifies the layout algorithm to use. Default is `"elk"`. Options are `"dagre"`, `"elk"`, `"tala"`. layout is not case sensitive so `"ELK"` or `"TALA"` are also supported.
- `format`: Specifies the format of the output image. Default is `svg`. Option are `"svg"`, `"png"`, `"pdf"`, `"gif"`.
- `sketch`: Whether to use a "sketch" style for the diagram. Default is `false`.
- `pad`: Amount of padding around the diagram. Default is `100`.
- `pad`: Amount of padding around the diagram in pixels. Default is `100`.
- `caption`: Caption to add to the diagram.
- `folder`: Folder where the generated diagram will be saved. If not provided, the image will be embedded inline in the document (HTML only).
- `filename`: Name of the output file.
- `width`: Width of the output image. Default is `100%`. Examples are `"100px"`, `"50%"`, `"3cm"`.
- `height`: Height of the output image. Default is `auto`. Examples are `"100px"`, `"50%"`, `"3cm"`.
- `echo`: Whether to echo the original diagram code in the output. Default is `false`.

You can also replace the contents of the block with an external D2 file by using the `file` parameter. `file` must be an existing file ending in a "d2" or "txt" file extension. Other parameters related to rendering and embedding diagrams include:

- `folder`: Folder where the generated diagram will be saved. If not provided, the image will be embedded inline in the document (HTML only).
- `filename`: Name of the output file.
- `embed_mode`: How to embed the diagram in the output. Default is `"inline"` for HTML output and `"link"` for other output formats. Options are `"inline"`, `"link"`, `"raw"`.

Note that for Typst format output the width and height can't be supplied as a percent value.

Here's an example that uses multiple attributes:

````markdown
Expand Down Expand Up @@ -152,6 +152,15 @@ x -> y -> z
```
````

## Setting an input file

You can specify an input d2 file. If `echo=true`, the contents of the file block is replaced by the contents of the file.

````markdown
```{.d2 file="./diagram.d2"}
```
````

## Setting output folder and file name

You can specify a folder where the generated diagram will be saved using the `folder` attribute. The `filename` attribute allows you to set a custom name for the output file.
Expand Down
Loading

0 comments on commit 1f6fb19

Please sign in to comment.