Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: update Getting Started page #5112

Merged
merged 2 commits into from
Dec 19, 2023
Merged

Docs: update Getting Started page #5112

merged 2 commits into from
Dec 19, 2023

Conversation

huynhicode
Copy link
Member

📑 Summary

This PR contains updates to the Getting Started page:

  • Add a section for Mermaid Chart
  • update verbiage throughout the page

Resolves # n/a

📏 Design Decisions

Design decisions are made by the Mermaid Chart team.

📋 Tasks

Make sure you

Copy link

netlify bot commented Dec 4, 2023

Deploy Preview for mermaid-js ready!

Name Link
🔨 Latest commit 2469419
🔍 Latest deploy log https://app.netlify.com/sites/mermaid-js/deploys/6581fa12adb2bb000869790f
😎 Deploy Preview https://deploy-preview-5112--mermaid-js.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

Copy link

codecov bot commented Dec 4, 2023

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (a1563c9) 79.78% compared to head (2469419) 75.95%.
Report is 14 commits behind head on master.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #5112      +/-   ##
==========================================
- Coverage   79.78%   75.95%   -3.83%     
==========================================
  Files         164      164              
  Lines       13820    13820              
  Branches      693      693              
==========================================
- Hits        11026    10497     -529     
- Misses       2644     3161     +517     
- Partials      150      162      +12     
Flag Coverage Δ
e2e 80.97% <ø> (-4.78%) ⬇️
unit 42.94% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

see 16 files with indirect coverage changes

Copy link
Member

@aloisklink aloisklink left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me!

Feel free to merge once you fix the broken links (you can ignore Link Checker failures that aren't related to your changes).

Comment on lines 22 to 26
1. [Using the Mermaid Chart Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
1. [Using the Mermaid Live Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
1. [Using Mermaid Plugins and Integrations](getting-started.html#_3-using-mermaid-plugins)
1. [Calling the Mermaid JavaScript API](getting-started.html#_4-calling-the-mermaid-javascript-api)
1. [Adding Mermaid as a dependency](getting-started.html#_5-adding-mermaid-as-a-dependency)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should prefer linking to .md instead of .html, so that the docs still work in markdown, but because these links are in the same file, we don't need them at all!

Also, the live editor link is pointing to the wrong place.

I've also updated the numbering, since although Markdown will automatically output the correct numbers, there are some users that will read the raw text, so we should the correct numbers there too.

Suggested change
1. [Using the Mermaid Chart Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
1. [Using the Mermaid Live Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
1. [Using Mermaid Plugins and Integrations](getting-started.html#_3-using-mermaid-plugins)
1. [Calling the Mermaid JavaScript API](getting-started.html#_4-calling-the-mermaid-javascript-api)
1. [Adding Mermaid as a dependency](getting-started.html#_5-adding-mermaid-as-a-dependency)
1. [Using the Mermaid Chart Editor](#_1-using-the-mermaid-chart-editor)
2. [Using the Mermaid Live Editor](#_2-using-the-mermaid-live-editor)
3. [Using Mermaid Plugins and Integrations](#_3-using-mermaid-plugins)
4. [Calling the Mermaid JavaScript API](#_4-calling-the-mermaid-javascript-api)
5. [Adding Mermaid as a dependency](#_5-adding-mermaid-as-a-dependency)


## 1. Using the Live Editor
<br />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a super big fan of these <br /> (or adding any HTML to markdown files). It does make the generated website look nicer, though, so I see a reason for leaving them in.

Maybe I'm biased since I normally spend most of my time reading these docs in plain text 😆

### Mermaid Plugins

You can generate Mermaid diagrams from within popular applications using plug-ins.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention the most common use-case of mermaid here, which is probably GitHub's/GitLab's integration?

Suggested change
For many apps that support markdown (e.g. [GitHub][] and [GitLab][]), you can add mermaid diagrams to markdown by making a `mermaid` code block, like so:
````markdown
The following code-block will be rendered as a mermaid diagram:
```mermaid
flowchart LR
Hello --> World
```
````
[GitHub]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
[GitLab]: https://docs.gitlab.com/ee/user/markdown.html#mermaid

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯 we should add these.


- [ChatGPT](https://docs.mermaidchart.com/plugins/chatgpt)
- [JetBrains IDE](https://docs.mermaidchart.com/plugins/jetbrains-ide)
- [Microsoft PowerPoint & Word](https://docs.mermaidchart.com/plugins/microsoft-office)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link is broken.

@huynhicode huynhicode merged commit f02114e into master Dec 19, 2023
17 of 24 checks passed
@huynhicode huynhicode deleted the update-getting-started branch December 19, 2023 20:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants