-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
Add default file format when Quarto format is
typst
(#7)
* 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]>
1 parent
cc97e8b
commit 1f6fb19
Showing
11 changed files
with
817 additions
and
260 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,216 @@ | ||
--- | ||
title: D2 Extension For Quarto | ||
format: html | ||
eval: false | ||
filters: | ||
- d2 | ||
d2: | ||
layout: "elk" | ||
--- | ||
|
||
This [Quarto](https://quarto.org) extension allows you to render [D2](https://d2lang.com) diagrams directly within your markdown documents. | ||
|
||
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. | ||
|
||
This extension was inspired by [`ram02z/d2-filter`](https://github.com/ram02z/d2-filter). | ||
|
||
## Installation | ||
|
||
### Prerequisites | ||
|
||
Ensure that you have [D2](https://d2lang.com/tour/install) installed on your system. | ||
|
||
### Install | ||
|
||
Run the following command to add this extension to your current project: | ||
|
||
``` bash | ||
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. | ||
|
||
|
||
```{.d2} | ||
x -> y: hello world | ||
``` | ||
|
||
|
||
And for more complex diagrams. | ||
|
||
```{.d2 width="50%" echo="true"} | ||
logs: { | ||
shape: page | ||
style.multiple: true | ||
} | ||
user: User {shape: person} | ||
network: Network { | ||
tower: Cell Tower { | ||
satellites: { | ||
shape: stored_data | ||
style.multiple: true | ||
} | ||
satellites -> transmitter | ||
satellites -> transmitter | ||
satellites -> transmitter | ||
transmitter | ||
} | ||
processor: Data Processor { | ||
storage: Storage { | ||
shape: cylinder | ||
style.multiple: true | ||
} | ||
} | ||
portal: Online Portal { | ||
UI | ||
} | ||
tower.transmitter -> processor: phone logs | ||
} | ||
server: API Server | ||
user -> network.tower: Make call | ||
network.processor -> server | ||
network.processor -> server | ||
network.processor -> server | ||
server -> logs | ||
server -> logs | ||
server -> logs: persist | ||
server -> network.portal.UI: display | ||
user -> network.portal.UI: access { | ||
style.stroke-dash: 3 | ||
} | ||
``` | ||
|
||
|
||
The enclosing curly brakets are optional if you are only using document level options. Quarto block-level options, e.g. `#|`, are not currently supported. | ||
|
||
|
||
```d2 | ||
Database -> S3: backup | ||
Database -> S3 | ||
Database -> S3: backup | ||
``` | ||
|
||
|
||
## Usage | ||
|
||
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. | ||
|
||
## Attributes | ||
|
||
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"`, `"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"`. | ||
- `sketch`: Whether to use a "sketch" style for the diagram. Default is `false`. | ||
- `pad`: Amount of padding around the diagram. Default is `100`. | ||
- `caption`: Caption to add to the diagram. | ||
- `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 using the `file` parameter. 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 | ||
```{.d2 theme="CoolClassics" layout="elk" pad=20 caption="This is a caption" width="50%"} | ||
x -> y -> z | ||
``` | ||
```` | ||
|
||
## Global Options | ||
|
||
You can set global options for the d2 filter using the `d2` field in the document metadata. Here's an example: | ||
|
||
````markdown | ||
--- | ||
title: "D2 Example" | ||
filters: | ||
- d2 | ||
d2: | ||
layout: elk | ||
theme: "GrapeSoda" | ||
--- | ||
|
||
```{.d2 width="40%" echo=true} | ||
x -> y -> z | ||
``` | ||
```` | ||
|
||
## 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. | ||
|
||
````markdown | ||
```{.d2 folder="./images" filename="my_diagram"} | ||
x -> y -> z | ||
``` | ||
```` | ||
|
||
:::{.callout-note} | ||
If the `folder` attribute is not provided and the output format is HTML, the image will be embedded inline in the document. | ||
::: | ||
|
||
## Interactive diagrams | ||
|
||
Interactive diagrams will only work when the Quarto output format is HTML, the figure format is `"svg"`, and the embed mode is `"raw"`. Example: | ||
|
||
````markdown | ||
--- | ||
title: "D2 Example" | ||
format: html | ||
filters: | ||
- d2 | ||
d2: | ||
format: svg | ||
embed_mode: raw | ||
--- | ||
|
||
```{.d2 width="40%"} | ||
x { | ||
link: "https://quarto.org" | ||
} | ||
y { | ||
tooltip: "This is a tooltip" | ||
} | ||
x -> y -> z | ||
``` | ||
```` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -10,3 +10,7 @@ d2: | |
```{.d2 width="40%" echo=true} | ||
x -> y -> z | ||
``` | ||
|
||
```{.d2 file=test.d2 echo=true} | ||
x -> y -> z | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
file -> is -> working |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
--- | ||
title: "D2 Example" | ||
format: typst | ||
filters: | ||
- d2 | ||
d2: | ||
layout: elk | ||
format: svg | ||
theme: "GrapeSoda" | ||
--- | ||
|
||
```{.d2 width="6in" echo=true} | ||
direction: right | ||
x -> y -> z | ||
``` | ||
|
||
|
||
```{.d2 format=png width="3in" echo=true} | ||
a -> b | ||
``` |