Docs: update Getting Started page #5112

huynhicode · 2023-12-04T21:49:55Z

📑 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

📖 have read the contribution guidelines
💻 have added necessary unit/e2e tests.
📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
🔖 targeted develop branch

netlify · 2023-12-04T21:50:01Z

✅ 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... Use your smartphone camera to open QR code link.

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

codecov · 2023-12-04T21:52:26Z

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

@@            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

aloisklink

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).

aloisklink · 2023-12-05T10:30:53Z

packages/mermaid/src/docs/intro/getting-started.md

+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)


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)

aloisklink · 2023-12-05T10:34:31Z

packages/mermaid/src/docs/intro/getting-started.md


-## 1. Using the Live Editor
+<br />


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 😆

aloisklink · 2023-12-05T10:42:15Z

packages/mermaid/src/docs/intro/getting-started.md

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


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

💯 we should add these.

aloisklink · 2023-12-05T10:43:41Z

docs/intro/getting-started.md

+
+- [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)


This link is broken.

update getting started page

276b5c7

huynhicode requested review from knsv, sidharthv96, aloisklink, ashishjain0512, jgreywolf and pbrolin47 December 4, 2023 21:50

aloisklink approved these changes Dec 5, 2023

View reviewed changes

aloisklink added the Area: Documentation label Dec 5, 2023

additional updates

2469419

jgreywolf approved these changes Dec 19, 2023

View reviewed changes

huynhicode merged commit f02114e into master Dec 19, 2023
17 of 24 checks passed

huynhicode deleted the update-getting-started branch December 19, 2023 20:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: update Getting Started page #5112

Docs: update Getting Started page #5112

huynhicode commented Dec 4, 2023

netlify bot commented Dec 4, 2023 •

edited

codecov bot commented Dec 4, 2023 •

edited

aloisklink left a comment

aloisklink Dec 5, 2023

aloisklink Dec 5, 2023

aloisklink Dec 5, 2023

sidharthv96 Dec 5, 2023

aloisklink Dec 5, 2023

		### Mermaid Plugins

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

+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

Docs: update Getting Started page #5112

Docs: update Getting Started page #5112

Conversation

huynhicode commented Dec 4, 2023

📑 Summary

📏 Design Decisions

📋 Tasks

netlify bot commented Dec 4, 2023 • edited

✅ Deploy Preview for mermaid-js ready!

codecov bot commented Dec 4, 2023 • edited

Codecov Report

aloisklink left a comment

Choose a reason for hiding this comment

aloisklink Dec 5, 2023

Choose a reason for hiding this comment

aloisklink Dec 5, 2023

Choose a reason for hiding this comment

aloisklink Dec 5, 2023

Choose a reason for hiding this comment

sidharthv96 Dec 5, 2023

Choose a reason for hiding this comment

aloisklink Dec 5, 2023

Choose a reason for hiding this comment

netlify bot commented Dec 4, 2023 •

edited

codecov bot commented Dec 4, 2023 •

edited