search

hugomods / kroki

Hugo Kroki Module
https://kroki.hugomods.com
MIT License
3 stars 0 forks source link

[Feature request] HugoMods module to integrate Kroki diagraming service #4

Closed ezzle closed 7 months ago

ezzle commented 7 months ago

Hi

Requested Feature

A HugoMods module to support the kroki unified API for diagraming

Embedding options

  1. image tag (! link and action inside the svg do not work)
  2. embeed tag
  3. inline svg

diagram definition options

  1. via data
  2. as code block content

What'is Kroki

Kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, Symbolator, TikZ, UMLet, Vega, Vega-Lite, WaveDrom, WireViz... and more to come! https://kroki.io/

Third party integration

Initial shortcode approach from Joe Mooring Use a fenced code block to embed an SVG image of a diagram in your [Hugo](https://gohugo.io/) site using the free [Kroki](https://kroki.io/) service. Unlike JavaScript solutions that require client-side rendering, this approach embeds an SVG image in your page. https://www.veriphor.com/articles/diagrams/ https://www.veriphor.com/articles/diagrams/#source-code

Inside Perplex Theme This theme includes a codeblock render hook which allows to enhance the diagrams in a similar way as images. https://perplex.desider.at/doc/plugin/kroki/

Best regards,

Tshitshi

razonyang commented 7 months ago

LGTM, never hear about it, need to dive into the docs.

razonyang commented 7 months ago
  • image tag (! link and action inside the svg do not work)
  • embeed tag
  • inline svg

@ezzle Hi, would you mind explaining those terms/use-cases in detail, so that I can define the SVG output properly. We can output the diagrams as raw <svg> content or external file used on <img src="/path/to/diagram.svg" /> element.

ezzle commented 7 months ago

Thank you for the support. You could begin with the inline option

Default option = Pefered

inline svg = output the diagrams as raw <svg> content = Raw svg directly inside the doc

<html>
<body>

<h1>My first SVG</h1>

<svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
  <circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
</svg>

</body>
</html>

Common use case when no link in the svg

image tag (! link and action inside the svg do not work) = external file used on <img src="/path/to/diagram.svg" /> element. An issue with this option, links in the svg are not clickable. https://github.com/kazumatu981/markdown-it-kroki/issues/2

A nice to have, as a alternative to img tag

embeed tag = external resource used on but on an embed element with src either from external file src="/path/to/diagram.svg or from direct call to kroki api <embed src="https://kroki.io/plantuml/svg/...."> https://www.w3schools.com/tags/tag_embed.asp https://stackblitz.com/edit/vite-qdacts?file=docs%2Findex.md

Best regards,

Tshitshi

razonyang commented 7 months ago

Thanks for the detials, will try to draft first implementation tonight

razonyang commented 7 months ago

A simple guide to test and preview the module.

1. Import the module

// hugo.toml
[[module.imports]]
path = "github.com/hugomods/kroki"

2. Using via Code Block

```kroki {_type="graphviz" _output="embed" class="class-one class-two" id="my-kroki-1" data-foo="bar"}
digraph G {Hello->World}

- `_type`: the diagram type.
- `_output`: `inline` (default) or `embed`.
- You can apply any valid attributes on the diagrams, such as the `class`, `id` and `data-foo`.

## 3. Using via Shortcode

```markdown
{{< kroki _name="diagrams/foo.dot" _type="graphviz" _output="embed" class="x y z" id="xyz" >}}

4. Tweak Styles

Both of <svg> and <embed> elements will have the .kroki class name, apply styles on svg.kroki and embed.kroki to suit your theme's styles.

About the <img> tag.

According to your explainations above, seems we don't need it?

About release.

Will draft a release once you're satisifed with it.

ezzle commented 7 months ago

Thank you. I am testing and will inform you

Best regards,

Tshitshi

Le lun. 11 mars 2024 à 14:11, Razon Yang @.***> a écrit :

A simple guide to test and preview the module.

  1. Import the module

// hugo.toml [[module.imports]]path = "github.com/hugomods/kroki"

  1. Using via Code Block


- `_type`: the diagram type.
- `_output`: `inline` (default) or `embed`.
- You can apply any valid attributes on the diagrams, such as the `class`, `id` and `data-foo`.

## 2. Using via Code Block

```markdown
```kroki {_type="graphviz" _output="embed" class="class-one class-two" id="my-kroki-1" data-foo="bar"}
digraph G {Hello->World}

- `_type`: the diagram type.
- `_output`: `inline` (default) or `embed`, optional.
- You can apply any valid attributes on the diagrams elements, such as the `class`, `id` and `data-foo`.

## 3. Using via Shortcode

```markdown
{{< kroki _name="diagrams/foo.dot" _type="graphviz" _output="embed" class="x y z" id="xyz" >}}

   - _name: the file name, both of page resource and site resource are
   supported.
   - _type as same as code block way.
   - _output as same as code block way.
   - You can also attach any custom attributes.

4. Tweak Styles

Both of <svg> and <embed> elements will have the .kroki class name, apply
styles on svg.kroki and embed.kroki to suit your theme's styles.
About the <img> tag.

According to your explainations above, seems we don't need it?
About release.

Will draft a release once you're satisifed with it.

—
Reply to this email directly, view it on GitHub
<https://github.com/hugomods/kroki/issues/4#issuecomment-1988408005>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ALX32WMFJTUO4KFIRFOWJ4TYXWUO5AVCNFSM6AAAAABEQIGFX6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOBYGQYDQMBQGU>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
ezzle commented 7 months ago

Hi Razon, Thank you very much.

Later will create a repo for debugging and share the link.

The current testing just tried to validate that the 2 options are operational. The result: only 1 option is ok for me.

Later, more testing with real-life use cases and in combination with other hugomods modules. Thank you for the excellent work and the extreme reactivity.

Best regards,

Tshitshi

ezzle commented 7 months ago

Update : All tests OK

Tested with real-life use cases and mixing with toggle module : All fine, inclusive with file from page ressource as well as from global ressource.

Good job!

I think you can release a first public version.

Best regards.

Tshitshi

razonyang commented 7 months ago

Done, https://github.com/hugomods/kroki/releases/tag/v0.1.0

ezzle commented 7 months ago

Thx

Le jeu. 14 mars 2024 à 09:19, Razon Yang @.***> a écrit :

Done, https://github.com/hugomods/kroki/releases/tag/v0.1.0

— Reply to this email directly, view it on GitHub https://github.com/hugomods/kroki/issues/4#issuecomment-1996821846, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALX32WOV2I2TIJPCVT7DD7TYYFMQPAVCNFSM6AAAAABEQIGFX6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJWHAZDCOBUGY . You are receiving this because you authored the thread.Message ID: @.***>

razonyang commented 7 months ago

FYI, docs site is live now https://kroki.hugomods.com/, which provides detailed usages and examples.

ezzle commented 7 months ago

Excellent!

Thank you

Tshitshi

Le ven. 15 mars 2024 à 09:45, Razon Yang @.***> a écrit :

FYI, docs site is live now https://kroki.hugomods.com/, which provides detailed usages and examples.

— Reply to this email directly, view it on GitHub https://github.com/hugomods/kroki/issues/4#issuecomment-1999184058, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALX32WNZC4ZU6VC2MFFTBLLYYKYJZAVCNFSM6AAAAABEQIGFX6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJZGE4DIMBVHA . You are receiving this because you authored the thread.Message ID: @.***>