Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/josephuspaye/gatsby-remark-graphviz
Gatsby plugin to compile DOT code-blocks into SVG images in Markdown processed by Remark
https://github.com/josephuspaye/gatsby-remark-graphviz
createweekly gatsby gatsby-plugin graphviz remark-plugin
Last synced: about 2 months ago
JSON representation
Gatsby plugin to compile DOT code-blocks into SVG images in Markdown processed by Remark
- Host: GitHub
- URL: https://github.com/josephuspaye/gatsby-remark-graphviz
- Owner: JosephusPaye
- License: mit
- Created: 2020-07-24T12:29:50.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T06:19:26.000Z (almost 2 years ago)
- Last Synced: 2024-11-20T05:27:51.899Z (2 months ago)
- Topics: createweekly, gatsby, gatsby-plugin, graphviz, remark-plugin
- Language: JavaScript
- Homepage:
- Size: 4.61 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Graphviz for Gatsby Remark
Intercepts code-blocks written in [DOT]() in your Markdown files and compiles them to SVG using GraphViz. Provides a quick and easy way to draw vector diagrams that are easy to modify and update.
This is a sub-plugin for `gatsby-transformer-remark`. As demoed below, add this plugin to the options of `gatsby-transformer-remark`.
---
This project is part of [#CreateWeekly](https://dev.to/josephuspaye/createweekly-create-something-new-publicly-every-week-in-2020-1nh9), my attempt to create something new publicly every week in 2020.
## Install
```bash
npm install --save @josephuspaye/gatsby-remark-graphviz
```
## How to use
First, install and configure the plugin as follows:
```javascript
// In your gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-transformer-remark',
options: {
plugins: [
'@josephuspaye/gatsby-remark-graphviz' // place before other plugins that modify code blocks, such as 'gatsby-remark-prismjs'
],
},
},
],
};
```
Then, write Markdown code blocks containing DOT source code describing a graph, with one of the following tags to trigger the plugin:
- `circo`
- `dot`
- `fdp`
- `neato`
- `osage`
- `patchwork`
- `twopi`
These tags are GraphViz layout algorithms, and more details about them can be found in the [GraphViz user guides](https://graphviz.org/documentation/#user-guides).
By default, the first `#` comment at the start of the code block will be used as the image caption, and subsequent `#` comments at the start of the code block will be used as alt text (see **Options** below).
See [GraphViz Pocket Reference](https://graphs.grevian.org/) for an introduction to GraphViz and how to write graphs using DOT.
## Example
The following code block written in Markdown:
````md
```neato
# A diagram showing system dependencies
# A more detailed description here to use as alt text
# More alt text follows
digraph {
A -> B
B -> C
C -> D
D -> A
}
```
````
Generates the following image:
A diagram showing system dependencies
From the following HTML (formatted for reading):
Click to expand
```html
A more detailed description here to use as alt text\nMore alt text follows
digraph {
A -> B
B -> C
C -> D
D -> A
}
ABCD
A diagram showing system dependencies
```
## Options
| Option | Type | Default | Description |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `generateAriaDescription` | Boolean | `true` | If `true`, generates and applies `aria-label` and `role="img"` to the SVG. Also generates `` and `` at the root of the SVG. [Important for accessibility](https://stackoverflow.com/a/4756461). |
| `optimize` | Boolean | `true` | If `true`, optimizes the generated SVG using [SVGO](https://github.com/svg/svgo). |
| `svgoPlugins` | Object | [See this](https://github.com/JosephusPaye/gatsby-remark-graphviz/blob/master/plugin.js#L10) | An object to enable or disable [SVGO optimisation plugins](https://github.com/svg/svgo#what-it-can-do). Each key is plugin name, and each value is a boolean that enables or disables the plugin. |
| `wrapperTag` | String | `div` | The tag to wrap the generated `` element in. |
| `wrapperClass` | String | `remark-graphviz-graph` | The class to apply to the wrapper of the generated `` element. |
| `firstCommentIsCaption` | String | `true` | If `true`, picks the first `#` comment at the top of the DOT source and uses that to generate a figure caption for the generated image. |
| `figureClass` | String | `remark-graphviz-figure` | The class to apply to the generated `` element. Only applies when `firstCommentIsCaption` is `true`. |
| `figcaptionClass` | String | `remark-graphviz-figcaption` | The class to apply to the generated `` element. Only applies when `firstCommentIsCaption` is `true`. |
Use the options as follows:
```javascript
// In your gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-transformer-remark',
options: {
plugins: [
{
resolve: '@josephuspaye/gatsby-remark-graphviz',
options: {
generateAriaDescription: true,
optimize: true,
svgoPlugins: {
inlineStyles: false,
removeTitle: false,
},
wrapperTag: 'span',
wrapperClass: 'my-graph-wapper is-fullwidth',
firstCommentIsCaption: true,
figureClass: 'my-graph-figure',
figcaptionClass: 'my-graph-figcaption',
},
},
],
},
},
],
};
```
## Licence
[MIT](LICENCE)