4 ms·

Show HN: Programmatically Generate Diagrams for GitHub Readmes

220 points by rschachte 8y ago

alexmercier 7y ago
Unfortunately Github doesn't support Mermaid language natively. Meanwhile, I've created an extension (Firefox & Chrome) that adds support for it: https://github.com/BackMarket/github-mermaid-extension https://github.com/BackMarket/github-mermaid-extension
montroser 8y ago
That is a clever method for embedding, and I like the minimal syntax. We've been using Plectica[1] for these sorts of diagrams and finding it to be pretty great. Not sure if they support export to svg out of the box yet though. [1]: https://plectica.com/welcome/technologists https://plectica.com/welcome/technologists
- rschachte 8y ago
  Ah, that's a neat tool! I've actually been kind of looking for something like this for work. Thanks for sharing.
  - pm90 8y ago
    Lucidchart?
jph 8y ago
Great work! Would you be interested in adding capabilities for PlantUML? The syntax is very similar. If so, I'll donate $50 to you or your favorite charity. Demo diagrams with syntax examples -- see the final one for an example document that I want to render for my team's devops pipeline: https://github.com/joelparkerhenderson/demo_plantuml/ https://github.com/joelparkerhenderson/demo_plantuml/
- rschachte 8y ago
  Hey there! Not a bad idea. Can you make an issue on the repo?
KuhlMensch 8y ago
Question: how does the local embed link translate into an asset uploaded to github user content? https://camo.githubusercontent.com/461a806ab46b5db76dcb02048e6a38705399202d/68747470733a2f2f692e696d6775722e636f6d2f365647324a57632e706e67 https://camo.githubusercontent.com/461a806ab46b5db76dcb02048...
- rschachte 7y ago
  It would work the same way as imgur or another image hosting provider. The app is in it's beginning phases to show the concept, but I'm adding blob storage on Azure. The image would get interpolated no different than anything else.
jerieljan 8y ago
This is nice. Good stuff. I've always automated my Markdeep[1] documentation's inline PlantUML diagrams with a few scripts here and there (simply looks for .puml files, exports PNG and SVG and hosts everything on a static site), but I've never imagined using a service for supplying the generated output. I want to bounce off this idea somehow. [1]: https://casual-effects.com/markdeep/ https://casual-effects.com/markdeep/
SlowRobotAhead 8y ago
Used WSD web sequence diagram at Amazon, handy, never thought it was too much of a pain to snip it out and embed that somewhere; but I get the idea.
agranig 8y ago
mermaid-filter is also a great part in the tool-chain, especially with pandoc.
- rschachte 7y ago
  Cool!
adamhepner 8y ago
I will chip in as a happy user of PlantText[1]. It allows you to edit PlantUML diagrams, renders them, and you can either download them as PNGs, SVG, or ASCII. I'm pretty sure you can also directly link to an image, although I'm not sure about ToS, so don't do it without fact-checking. Oh, and it saves your content locally. [1]: https://www.planttext.com/ https://www.planttext.com/.
bestouff 8y ago
FWIW Gitlab already renders Mermaid natively, and it's totally client-side (done in the browser) which means there's no rendering server to install, no image to host differently is each branch, etc. Cf https://docs.gitlab.com/ee/user/markdown.html#mermaid https://docs.gitlab.com/ee/user/markdown.html#mermaid
- StavrosK 7y ago
  Wow, thanks for this! I had no idea, this is extremely useful.
  - bestouff 7y ago
    It is. We write all our technical documentation (as well as specs, etc. even meeting minutes) using markdown with embedded mermaid diagrams, and during CI have it transformed (via pandoc and ad-hoc scripting) into PDF with corporate company headers. Looks gorgeous and has all the benefits of version controlled textual doc.
burtonator 7y ago
I did a big heads down on this about 6 months ago as I was writing a paper and needed a ton of sequence diagrams to explain protocols. PlantUML is a major pain. I didn't know about Mermaid at the time. Latex has a ton of code for building better charts but they're all very very low level. What's needed is a higher level abstraction here. It should be possible to have much higher level charts without having to be a latex god.
askme2 7y ago
Readers may also want to check out nomnoml.com. It’s definitely a more stripped down version of Mermrender. I used it for my thesis paper and was happy enough with it. I’ll definitely be checking this tech out.

220 points by rschachte 8y ago

Unfortunately Github doesn't support Mermaid language natively. Meanwhile, I've created an extension (Firefox & Chrome) that adds support for it: https://github.com/BackMarket/github-mermaid-extension https://github.com/BackMarket/github-mermaid-extension

montroser 8y ago

That is a clever method for embedding, and I like the minimal syntax. We've been using Plectica[1] for these sorts of diagrams and finding it to be pretty great. Not sure if they support export to svg out of the box yet though. [1]: https://plectica.com/welcome/technologists https://plectica.com/welcome/technologists

rschachte 8y ago
Ah, that's a neat tool! I've actually been kind of looking for something like this for work. Thanks for sharing.
- pm90 8y ago
  Lucidchart?

jph 8y ago

Great work! Would you be interested in adding capabilities for PlantUML? The syntax is very similar. If so, I'll donate $50 to you or your favorite charity. Demo diagrams with syntax examples -- see the final one for an example document that I want to render for my team's devops pipeline: https://github.com/joelparkerhenderson/demo_plantuml/ https://github.com/joelparkerhenderson/demo_plantuml/

rschachte 8y ago
Hey there! Not a bad idea. Can you make an issue on the repo?

KuhlMensch 8y ago

Question: how does the local embed link translate into an asset uploaded to github user content? https://camo.githubusercontent.com/461a806ab46b5db76dcb02048e6a38705399202d/68747470733a2f2f692e696d6775722e636f6d2f365647324a57632e706e67 https://camo.githubusercontent.com/461a806ab46b5db76dcb02048...

rschachte 7y ago
It would work the same way as imgur or another image hosting provider. The app is in it's beginning phases to show the concept, but I'm adding blob storage on Azure. The image would get interpolated no different than anything else.

jerieljan 8y ago

This is nice. Good stuff. I've always automated my Markdeep[1] documentation's inline PlantUML diagrams with a few scripts here and there (simply looks for .puml files, exports PNG and SVG and hosts everything on a static site), but I've never imagined using a service for supplying the generated output. I want to bounce off this idea somehow. [1]: https://casual-effects.com/markdeep/ https://casual-effects.com/markdeep/

SlowRobotAhead 8y ago

Used WSD web sequence diagram at Amazon, handy, never thought it was too much of a pain to snip it out and embed that somewhere; but I get the idea.

agranig 8y ago

mermaid-filter is also a great part in the tool-chain, especially with pandoc.

rschachte 7y ago
Cool!

adamhepner 8y ago

I will chip in as a happy user of PlantText[1]. It allows you to edit PlantUML diagrams, renders them, and you can either download them as PNGs, SVG, or ASCII. I'm pretty sure you can also directly link to an image, although I'm not sure about ToS, so don't do it without fact-checking. Oh, and it saves your content locally. [1]: https://www.planttext.com/ https://www.planttext.com/.

bestouff 8y ago

FWIW Gitlab already renders Mermaid natively, and it's totally client-side (done in the browser) which means there's no rendering server to install, no image to host differently is each branch, etc. Cf https://docs.gitlab.com/ee/user/markdown.html#mermaid https://docs.gitlab.com/ee/user/markdown.html#mermaid

StavrosK 7y ago
Wow, thanks for this! I had no idea, this is extremely useful.
- bestouff 7y ago
  It is. We write all our technical documentation (as well as specs, etc. even meeting minutes) using markdown with embedded mermaid diagrams, and during CI have it transformed (via pandoc and ad-hoc scripting) into PDF with corporate company headers. Looks gorgeous and has all the benefits of version controlled textual doc.

burtonator 7y ago

I did a big heads down on this about 6 months ago as I was writing a paper and needed a ton of sequence diagrams to explain protocols. PlantUML is a major pain. I didn't know about Mermaid at the time. Latex has a ton of code for building better charts but they're all very very low level. What's needed is a higher level abstraction here. It should be possible to have much higher level charts without having to be a latex god.

askme2 7y ago

Readers may also want to check out nomnoml.com. It’s definitely a more stripped down version of Mermrender. I used it for my thesis paper and was happy enough with it. I’ll definitely be checking this tech out.