What is Reddit's opinion of
mermaid?
From 3.5 billion Reddit comments
38 reviews of this app found across Reddit:
The hardest thing in writing documentation is somewhat similar to how we try to code the same way in a team using code conventions.
Defining your team's documentation conventions and having everyone on board is freakin' hard.
Here's what I've been preaching to my team and those who work with us.
Start with high level infrastructure stuff using something like https://c4model.com/ The 2 first levels are usually enough to figure out where I should do a fix or where I should attempt to work.
Before coding something, start with writing functional specifications first. IMHO, a good reference for writing no-bullshit-functional-specs is https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/
Its form could be simple sentences and bullet points just like within the article. A flow diagram or a sequence diagram is sometimes more efficient in communicating the overall intent. My preferred tool to draw those diagrams is https://mermaid-js.github.io/mermaid-live-editor Since it's all text, you can even commit your diagrams within your code repository.
I usually don't care much about inline comments unless it's really trippy and complicated.
I do care about good naming conventions for your classes, methods, functions and variables.
+1 for C4 diagrams
Also mermaid js comes with a lot of great graph layouts https://mermaid-js.github.io/mermaid/#/
It's like writing a bulleted list in markdown that gets rendered to a graph
Also not tech but keeping an engineering lab notebook helps a lot. Just large bound graph paper that you can sketch ideas on then scan into Figma or whatever. Slightly more formal than a whiteboard
The chart you're showing is called a Gantt chart. The best way I've discovered to create Gantt charts in R is to use mermaid.js, which is available via the DiagrammeR package.
I really like https://mermaid-js.github.io/mermaid/ for design diagrams. It supports all the common ones (state, sequence, relationship, etc). The diagrams are clear and the web editors with live updates makes it easy to learn.
Having the diagram source be a markup language makes them easy to update as the architecture changes. They can be checked into git, and I've heard gitlab can render the diagrams directly without needing to export to SVG or PNG.
There's Mermaid, which is written as code, compatible with markdown and is natively supported on Github/Gitlab and others, allowing you to write your diagrams instead of drag&dropping them, storing them in git, and visualising them alongside your regular docs.
great list.
For documentation diagram, take a look at mermaid-js
> Small python tools I've hacked together to parse compiler/objdump output:
I'm curious about this. How do you monitor stack usage?
Additionally, diagrams. Things like class, sequence, and c4 diagrams are super useful to know how to read and create.
Check out meta languages like mermaid, plantuml, and C4.
mermaid - https://mermaid-js.github.io/mermaid/#/
plant uml - https://plantuml.com/
c4 - https://c4model.com/
This is now supported. source: https://www.notion.so/What-s-New-157765353f2c4705bd45474e5ba8b46c
> Create flowcharts, pie charts, user journey diagrams and more with **[Mermaid](https://mermaid-js.github.io/mermaid/#/README)\*\*, right inside a code block. No need to screenshot or embed charts from other tools! Mermaid syntax is easy to learn, even if you don’t usually write code.
>
> Just select **`Mermaid`** in the language dropdown at the top left of any code block to get started. Once you’ve written your code, use the second dropdown at the top left to see a live **`Preview`** of your chart, or select **`Split`** to see your code and chart together.
Mermaid.js can describe FSMs in text. I've used it for other things, and it integrates into a ton of stuff that uses markdown. Might be worth a look if you want something simple.
I omitted to mention Markmap / conflated it with Mermaid here, but I think my point was - neither "for now" option takes full advantage of Notion, and both seem like a more natural fit in Obsidian than in Notion.
Are you imagining they should use Markmap as the underlying mechanism for supporting mindmaps? I guess Notion supports Markdown already, but there would I think need to be another UI step to flip into Markmap mode and to allow the data entry through menus rather than just Markmap code, ie. Menu options as proxies for Markmap code.
Sounds cool if you end up with something exportable as an open format. Though I suppose you're left with a functional mindmap but one that doesn't necessarily leverage Notion features like databases, except that you can use hyperlinks to DB pages ... ?
So I'm in constant pursuit of some way to chart relationships between my pages, and I've been especially eager to set something up so I could click on the node so it would take me to that Notion page.
I searched through the Mermaid documentation and found their Interaction part gives instructions for setting up hyperlinks.
And, amazingly, you can paste the Notion link in the appropriate space, replace the https with notion, and it clicks you through to the Notion page in the Notion app.
There are a few text based diagram tools like:
Platuml: https://plantuml.com/
Mermaid: https://mermaid-js.github.io/mermaid/#/
Graphviz yes, with the common dot tool (but there are a few others)
This kroki website have a nice cheatsheet of available text based diagram tools: https://kroki.io/
looks like the click directive works in joplin see here. i can link to a note and a header within it via
click [node] "joplin://[note id]#[header slug]
but it's not working to link to a header within the same node.
Try mermaid.live-- that's a free site that implements the mermaid library.
If you can explain your code line by line, especially control statements and calls to subfunctions, you can quite easily define those as objects, and the library takes care of the "drawing" itself. You just need to script out "A((One)) --> B{Two} --yes--> C[Three]", etc. It's already integrated into Visual Studio and there are plugins for other IDEs. You can even push documentation as code into git.
I've had good success with Mermaid for git diagrams. It's still experimental but fairly easy to use and renders well in tools like GitLab that support it.
https://mermaid-js.github.io/mermaid/#/README?id=git-graph-exclamation-experimental
I've used mermaid before, it's basically markdown diagrams. They have various diagram types for sequence diagrams, ER diagrams, etc. Bonus points for being able to commit it to git since it's all text.
For more custom diagrams I have used diagrams.net (what Lucid Charts is based off of/uses).
I use mermaid which basically extends markdown with visualization support. Not the prettiest looking thing out of the box but styling is fully customizable and being able to version and commit markdown files with embedded diagrams is amazing.
Mermaid is a nice tool for diagrams. Since it uses a Markdown-like syntax, it's good for adding it to version control.
The static IP is needed, and 2K is not all that much for one. I didn't want to use a reverse proxy or forwarding service because I have a VoIP server and I need minimal latency.
The Optiplex series does look nice. I know a vendor who has hundreds of them. At some point in the future, I'll probably get something like that and get a smaller rack.
It is definitely great for that sort of thing.
Personally, I like to generate mine programmatically from my source data so I've been getting down with Mermaid: https://mermaid-js.github.io/mermaid/#/
I've messed around with mermaid a bit and it's pretty cool, but depends on how you're trying to host/update the diagram... Most scheduling software that's decent is going to be paid if you want much more than what mermaid offers. If it's not changing why not just draw it out in PowerPoint or something?
Comparing anything to Office 365 will pretty much mean the other thing loses, it's a really good deal. Cloud storage? They all cost the same, more or less, but O365 gets you real Office. Buy it for OneNote storage, well, you still got the rest of the office suite on the side, and so on.
One thing that doesn't get mentioned much that we are mostly not OneNote's target customers. The team is very focused on the classroom, and new features for office workers, execs and PhD researchers or the like are really slim. For the more standalone notetaking apps, the office worker, executive and the researcher are generally the target customers, so that's where new features get aimed at.
A prototypical new OneNote feature is better ways to manage class notebooks. Evernote adds a task manager and a calendar, Obsidian and Roam introduce ways to write charts with mermaid, Notion catches up on block transclusion, etc. For these tools, we are the target user. For OneNote, it's the schoolteacher.
I am currently working on something very similar for my own home setup. Happy to share my insights and also eager to see how other people are doing their documentation.
Since the documentation should be very acceeible also also quick and easy to update, I chose to write it in markdown, which then can be exported to HTML or PDF or whatever is needed using pandoc.
For the most part, I list stuff in tables: Device inventory, backup targets and frequency, data classification. When there is more information required than a table can show, I just write it as a short list above or below the table (for example when specific folders are excluded or when certain types of data should not be stored together on the same device). For diagrams I use mermaid flowcharts. While certainly not the most appropriate or beautifil solution, I really like how well this integrates with markdown and it gets the job done for me.
Hi 3rddog,
I use different templates. This one is called FiSeR and the diagram code is made in the mermaid format.
Mermaid -> https://mermaid-js.github.io/mermaid/#/
experiment with the examples and you will get used to it very fast. Like I said above: if I had used this in university from the beginning, like many students do, my notes would have looked incredible :D
Template -> https://github.com/f1se4/fiser_iatemplate
If you do a lot of computer Spence or math stuff, you will like https://github.com/jhermsmeier/github-math-iatemplate too
I will try to make my own template with the nice looking Duo font from iA but with graph and code-Syntax highlighting
The first thing that comes to mind is some kind of Gantt chart. Visualization is always something I've wanted to work on/improve for SimPy models, usually only wind up visualizing other outputs. There are a lot of different ways to create Gantt charts, I like mermaid.js because it's free and while I've never done it should be able to be automated.
If you're thinking more like visualizing the flow of things of course that's going to vary drastically whether you have explicit locations for things or would have to try and find some automatic way of laying out stations in the flowchart.
Would something like mermaid be of interest to you? It's one of those text-to-chart type programs like ERD, PlantUML, etc. It has a Gantt chart feature. We like tools like these anyway because it makes it more pleasant to share stuff in line-oriented version control systems like git.
Take notes on the fly with OneNote. I then export the OneNote of the lecture as a PDF and write a summary note of the lecture in Obsidian. I link the PDF of the OneNote to the summary note.
You can use LateX math natively in Obisidan. Mermaid is natively build in as well and lets you build flow charts. There is a Community charts plug-in. Or you just either snip-then-insert them as embedded pictures.
You can extract the mathematics of the handwritten notes with something like Mathpix. The notes need to be neat, though. Something like that is also handy to get math from a book or website into your notes.
Of note: I personally use my lecture notes (or notes on YT videos) as source artifact. Meaning I actually make an entry in my reference manager (in my case, Zotero) and import the OneNote PDF into that. I then use the Obsidian Citation plugin to generate reference notes.
Also a recommendation if you use it like that: use PANDOC-style references in your notes. They look like this: [@einstein1906b, p. 142-163]. This way, you have everything ready to later re-use your notes in LateX documents without overhauls, and preserve sourcing information! Really handy in end-of-term papers! (And I assume that you'll use LateX sooner or later if you're studying in a math-heavy subject).
Personally, I like the project wiki approach more than a GDD approach, so I use MKDocs.
Far as graphs go, MKDocs supports Mermaid with this plugin
I guess if you're going to pay even minimal hosting costs then you could probably provide a full-featured API and adjust rate-limits an what-not later, when or if traffic becomes some kind of problem (e.g. too-high costs).
What kind of requests are you thinking would be "slow"?
Are you thinking of providing 'calculator' info, e.g. production/factory plans/networks?
What I've been thinking about is a tool to analyze an 'existing' plan/network (factory). A factory would be input as 'diagram markup' (e.g. using something like Mermaid, a JavaScript library that can, among other things, make flowchart diagrams from markup). The tool would let you know the throughput of the factory, and each component building, so you could, e.g. underclock buildings to smooth power consumption, or know how much of a resource node is being used.
I might look at 'forking' the Satisfactory Tools data JSON file (and whatever they use to generate it) and use that in my hypothetical tool.
Also, just curious – what are you going to write your API in? I've been writing a lot of Elixir code so that's what I'll probably use myself.
the arrows was a bad example because Dot also has them seen as they are fundamental to a digraph. I'm not actually all that familiar with either, only played around with them for a bit because I was looking to document something, but got discouraged when I saw that markdown integration is so far off and specific to each tool when I'd like it to be more universal. If you look at the flowchart example you can see all the different syntax for styling things differently. I assume they're trying to design the syntax to be intuitive and less verbose, but it just ends up creating so much syntax that it's hard to know what's going on. E.g using different combinations of [ and ( to create different styles like [(, ((, [[, ([. However it does also look like mermaid has some support for css as well. Dot looks more extensible if you for example see that a lot of styling is based on attributes.
Mermaid JS is also an option.
There are fewer options than plantuml, but the syntax is similar and produces a little more "beautiful" diagrams
^(I still prefer plantuml though)
If you need to draw diagrams or workflows checkout mermaid.js It generates diagrams from a markdown text. Text is easier to maintain compared to image and you will have a better commit history
If You don't need to insert pictures use Mermaid
I realize that could be way too complex for a simple tool / private project. Maybe give it some commands, like in Mermaid https://mermaid-js.github.io/mermaid/#/examples
Still, I want the output to be plan text / ASCII / UTF8
u/Franktic2 thank you. As DevOps Engineer by trade I really like your desire to find a new and better way for things that everyone considers the "standard" way.
While I don't think I could read your PTN as fast as Tab or SN, I could probably learn to write it as fast, if not faster. Which makes me wonder if your system might serve as yaml or markdown. I write almost all of my documents in markdown, it would be incredibly useful to have a language like PTN drop a line of tablature in the middle of a document, not unlike using mermaid https://mermaid-js.github.io/mermaid/#/ to drop a flow chart in the middle of document.
Well, it has been a learning experience. and a couple of people got two versions of transcriptions for their requests. Can't beat that.
Cheers.
For a quick Gantt chart, I've used the live editor for MermaidJS. Save the markup and edit later.
​
UML for adventures? Ugh. No.
Diagramming stuff is a good way to present info but a really hard way to create it. Long experience has taught me to keep my diagrams in text format, and then let a computer draw it for me. Much easier to change and update that way.
So check this out: https://mermaid-js.github.io/mermaid/#/stateDiagram or https://mermaid-js.github.io/mermaid/#/flowchart?id=flowcharts-basic-syntax
It will do your UML class diagrams too: https://mermaid-js.github.io/mermaid/#/classDiagram
Personally, I'd use VS Code and the mermaid plugin, or even the online editor to generate the diagrams if it was just once in a while.