4 ms·

GitHub will natively support Mermaid diagrams

72 points by polycaster 5y ago

adverbly 5y ago
Amazing! Mermaid is great. Happy to see it get more widespread adoption! This will make it much easier to keep documentation up to date. Much easier to change 1 line than to generate new images and take an updated screenshot or export, especially if you dont have the source file for whatever editor generated the original image.
anduru_h 5y ago
As someone who just learned what Mermaid is...this is amazing. Great feature add. Does anyone have good recommendations for learning the syntax / alternatives?
- derefnull 5y ago
  I also just learned about Mermaid. Looks great. PlantUML is what I’ve been using to achieve similar documentation goals with text https://hn.algolia.com/?q=plantuml https://hn.algolia.com/?q=plantuml previous discussions https://plantuml.com/ https://plantuml.com/
  - anduru_h 5y ago
    Awesome! Really appreciate this.
- justsomehnguy 5y ago
  > alternatives dot/Graphviz https://en.wikipedia.org/wiki/DOT_(graph_description_language) https://en.wikipedia.org/wiki/DOT_(graph_description_languag... https://en.wikipedia.org/wiki/Graphviz https://en.wikipedia.org/wiki/Graphviz Can be used in PowerShell: https://github.com/KevinMarquette/PSGraph https://github.com/KevinMarquette/PSGraph
core-utility 5y ago
This is a great addition. Diagrams are a huge hole in documentation-as-code, particularly in something that should be easy to dynamically generate.
jka 5y ago
Nice to see GitHub catching up[1] with GitLab in this area. [1] - https://web.archive.org/web/20210509204433/https://about.gitlab.com/handbook/tools-and-tips/mermaid/ https://web.archive.org/web/20210509204433/https://about.git...
clock99 5y ago
bob1029 5y ago
There are so many times I would have used this. At least 20% of my issues could have benefited from an in-line diagram tool. Being able to quickly draw out complex sequence/state diagrams would make my otherwise dense bricks of narrative descriptions much more palatable for many teammates.
bussierem 5y ago
I'm very excited about this! I’m looking forward to combining this with ARCHITECTURE.md[0] files to make some kick-ass documentation for our company’s devs for our repo(s). [0]: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html
GauntletWizard 5y ago
Mermaid would not be my first choice of diagramming software (that would be plain old Graphviz with PlantUML for more full featured graphs), but I'm glad to see some diagramming support on GitHub natively. There's already quite a few tools that let you embed via hotlink or generated link your graph. [1] https://graphviz.org/ https://graphviz.org/ [2] https://plantuml.com/ https://plantuml.com/
mindcrime 5y ago
That... is frickin awesome! I am definitely looking forward to starting to use this. Good joerb, GitHub!
NmAmDa 5y ago
Hopefully LaTeX will be next. Many scientific projects are now on Github and will benefit from that.
cebert 5y ago
This is really exciting. My team is trying to move off Confluence in favor of storing more documentation and design artifacts in GitHub. This will help make that more possible.
bradwood 5y ago
Gitlab's had this for ages.

72 points by polycaster 5y ago

Amazing! Mermaid is great. Happy to see it get more widespread adoption! This will make it much easier to keep documentation up to date. Much easier to change 1 line than to generate new images and take an updated screenshot or export, especially if you dont have the source file for whatever editor generated the original image.

anduru_h 5y ago

As someone who just learned what Mermaid is...this is amazing. Great feature add. Does anyone have good recommendations for learning the syntax / alternatives?

derefnull 5y ago
I also just learned about Mermaid. Looks great. PlantUML is what I’ve been using to achieve similar documentation goals with text https://hn.algolia.com/?q=plantuml https://hn.algolia.com/?q=plantuml previous discussions https://plantuml.com/ https://plantuml.com/
- anduru_h 5y ago
  Awesome! Really appreciate this.
justsomehnguy 5y ago
> alternatives dot/Graphviz https://en.wikipedia.org/wiki/DOT_(graph_description_language) https://en.wikipedia.org/wiki/DOT_(graph_description_languag... https://en.wikipedia.org/wiki/Graphviz https://en.wikipedia.org/wiki/Graphviz Can be used in PowerShell: https://github.com/KevinMarquette/PSGraph https://github.com/KevinMarquette/PSGraph

core-utility 5y ago

This is a great addition. Diagrams are a huge hole in documentation-as-code, particularly in something that should be easy to dynamically generate.

jka 5y ago

Nice to see GitHub catching up[1] with GitLab in this area. [1] - https://web.archive.org/web/20210509204433/https://about.gitlab.com/handbook/tools-and-tips/mermaid/ https://web.archive.org/web/20210509204433/https://about.git...

clock99 5y ago

bob1029 5y ago

There are so many times I would have used this. At least 20% of my issues could have benefited from an in-line diagram tool. Being able to quickly draw out complex sequence/state diagrams would make my otherwise dense bricks of narrative descriptions much more palatable for many teammates.

bussierem 5y ago

I'm very excited about this! I’m looking forward to combining this with ARCHITECTURE.md[0] files to make some kick-ass documentation for our company’s devs for our repo(s). [0]: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

GauntletWizard 5y ago

Mermaid would not be my first choice of diagramming software (that would be plain old Graphviz with PlantUML for more full featured graphs), but I'm glad to see some diagramming support on GitHub natively. There's already quite a few tools that let you embed via hotlink or generated link your graph. [1] https://graphviz.org/ https://graphviz.org/ [2] https://plantuml.com/ https://plantuml.com/

mindcrime 5y ago

That... is frickin awesome! I am definitely looking forward to starting to use this. Good joerb, GitHub!

NmAmDa 5y ago

Hopefully LaTeX will be next. Many scientific projects are now on Github and will benefit from that.

cebert 5y ago

This is really exciting. My team is trying to move off Confluence in favor of storing more documentation and design artifacts in GitHub. This will help make that more possible.

bradwood 5y ago

Gitlab's had this for ages.