From b4f444869e6b3f996e5f1d58d83a6c94f6caff0d Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Thu, 12 Oct 2023 16:39:31 +0300 Subject: [PATCH 01/31] fix: add imperativeState and replace sequenceDb global variables with it --- .npmrc | 1 + .../src/diagrams/sequence/sequenceDb.js | 160 +++++++++--------- .../mermaid/src/utils/imperativeState.spec.ts | 78 +++++++++ packages/mermaid/src/utils/imperativeState.ts | 37 ++++ 4 files changed, 199 insertions(+), 77 deletions(-) create mode 100644 packages/mermaid/src/utils/imperativeState.spec.ts create mode 100644 packages/mermaid/src/utils/imperativeState.ts diff --git a/.npmrc b/.npmrc index 4c2f52b3b..e72930ead 100644 --- a/.npmrc +++ b/.npmrc @@ -1,2 +1,3 @@ +registry=https://registry.npmjs.org auto-install-peers=true strict-peer-dependencies=false diff --git a/packages/mermaid/src/diagrams/sequence/sequenceDb.js b/packages/mermaid/src/diagrams/sequence/sequenceDb.js index 6c3f1f64d..dbe8fdde5 100644 --- a/packages/mermaid/src/diagrams/sequence/sequenceDb.js +++ b/packages/mermaid/src/diagrams/sequence/sequenceDb.js @@ -2,57 +2,60 @@ import * as configApi from '../../config.js'; import { log } from '../../logger.js'; import { sanitizeText } from '../common/common.js'; import { - setAccTitle, - getAccTitle, - setDiagramTitle, - getDiagramTitle, - getAccDescription, - setAccDescription, clear as commonClear, + getAccDescription, + getAccTitle, + getDiagramTitle, + setAccDescription, + setAccTitle, + setDiagramTitle, } from '../common/commonDb.js'; +import { createImperativeState } from '../../utils/imperativeState.js'; -let prevActor = undefined; -let actors = {}; -let createdActors = {}; -let destroyedActors = {}; -let boxes = []; -let messages = []; -const notes = []; -let sequenceNumbersEnabled = false; -let wrapEnabled; -let currentBox = undefined; -let lastCreated = undefined; -let lastDestroyed = undefined; +const state = createImperativeState(() => ({ + prevActor: undefined, + actors: {}, + createdActors: {}, + destroyedActors: {}, + boxes: [], + messages: [], + notes: [], + sequenceNumbersEnabled: false, + wrapEnabled: undefined, + currentBox: undefined, + lastCreated: undefined, + lastDestroyed: undefined, +})); export const addBox = function (data) { - boxes.push({ + state.records.boxes.push({ name: data.text, wrap: (data.wrap === undefined && autoWrap()) || !!data.wrap, fill: data.color, actorKeys: [], }); - currentBox = boxes.slice(-1)[0]; + state.records.currentBox = state.records.boxes.slice(-1)[0]; }; export const addActor = function (id, name, description, type) { - let assignedBox = currentBox; - const old = actors[id]; + let assignedBox = state.records.currentBox; + const old = state.records.actors[id]; if (old) { // If already set and trying to set to a new one throw error - if (currentBox && old.box && currentBox !== old.box) { + if (state.records.currentBox && old.box && state.records.currentBox !== old.box) { throw new Error( 'A same participant should only be defined in one Box: ' + old.name + " can't be in '" + old.box.name + "' and in '" + - currentBox.name + + state.records.currentBox.name + "' at the same time." ); } // Don't change the box if already - assignedBox = old.box ? old.box : currentBox; + assignedBox = old.box ? old.box : state.records.currentBox; old.box = assignedBox; // Don't allow description nulling @@ -69,36 +72,42 @@ export const addActor = function (id, name, description, type) { description = { text: name, wrap: null, type }; } - actors[id] = { + state.records.actors[id] = { box: assignedBox, name: name, description: description.text, wrap: (description.wrap === undefined && autoWrap()) || !!description.wrap, - prevActor: prevActor, + prevActor: state.records.prevActor, links: {}, properties: {}, actorCnt: null, rectData: null, type: type || 'participant', }; - if (prevActor && actors[prevActor]) { - actors[prevActor].nextActor = id; + if (state.records.prevActor && state.records.actors[state.records.prevActor]) { + state.records.actors[state.records.prevActor].nextActor = id; } - if (currentBox) { - currentBox.actorKeys.push(id); + if (state.records.currentBox) { + state.records.currentBox.actorKeys.push(id); } - prevActor = id; + state.records.prevActor = id; }; const activationCount = (part) => { let i; let count = 0; - for (i = 0; i < messages.length; i++) { - if (messages[i].type === LINETYPE.ACTIVE_START && messages[i].from.actor === part) { + for (i = 0; i < state.records.messages.length; i++) { + if ( + state.records.messages[i].type === LINETYPE.ACTIVE_START && + state.records.messages[i].from.actor === part + ) { count++; } - if (messages[i].type === LINETYPE.ACTIVE_END && messages[i].from.actor === part) { + if ( + state.records.messages[i].type === LINETYPE.ACTIVE_END && + state.records.messages[i].from.actor === part + ) { count--; } } @@ -106,7 +115,7 @@ const activationCount = (part) => { }; export const addMessage = function (idFrom, idTo, message, answer) { - messages.push({ + state.records.messages.push({ from: idFrom, to: idTo, message: message.text, @@ -137,7 +146,7 @@ export const addSignal = function ( throw error; } } - messages.push({ + state.records.messages.push({ from: idFrom, to: idTo, message: message.text, @@ -149,63 +158,58 @@ export const addSignal = function ( }; export const hasAtLeastOneBox = function () { - return boxes.length > 0; + return state.records.boxes.length > 0; }; export const hasAtLeastOneBoxWithTitle = function () { - return boxes.some((b) => b.name); + return state.records.boxes.some((b) => b.name); }; export const getMessages = function () { - return messages; + return state.records.messages; }; export const getBoxes = function () { - return boxes; + return state.records.boxes; }; export const getActors = function () { - return actors; + return state.records.actors; }; export const getCreatedActors = function () { - return createdActors; + return state.records.createdActors; }; export const getDestroyedActors = function () { - return destroyedActors; + return state.records.destroyedActors; }; export const getActor = function (id) { - return actors[id]; + return state.records.actors[id]; }; export const getActorKeys = function () { - return Object.keys(actors); + return Object.keys(state.records.actors); }; export const enableSequenceNumbers = function () { - sequenceNumbersEnabled = true; + state.records.sequenceNumbersEnabled = true; }; export const disableSequenceNumbers = function () { - sequenceNumbersEnabled = false; + state.records.sequenceNumbersEnabled = false; }; -export const showSequenceNumbers = () => sequenceNumbersEnabled; +export const showSequenceNumbers = () => state.records.sequenceNumbersEnabled; export const setWrap = function (wrapSetting) { - wrapEnabled = wrapSetting; + state.records.wrapEnabled = wrapSetting; }; export const autoWrap = () => { // if setWrap has been called, use that value, otherwise use the value from the config // TODO: refactor, always use the config value let setWrap update the config value - if (wrapEnabled !== undefined) { - return wrapEnabled; + if (state.records.wrapEnabled !== undefined) { + return state.records.wrapEnabled; } return configApi.getConfig().sequence.wrap; }; export const clear = function () { - actors = {}; - createdActors = {}; - destroyedActors = {}; - boxes = []; - messages = []; - sequenceNumbersEnabled = false; + state.reset(); commonClear(); }; @@ -247,7 +251,7 @@ export const parseBoxData = function (str) { } } - const boxData = { + return { color: color, text: title !== undefined @@ -262,7 +266,6 @@ export const parseBoxData = function (str) { : undefined : undefined, }; - return boxData; }; export const LINETYPE = { @@ -321,8 +324,8 @@ export const addNote = function (actor, placement, message) { // eslint-disable-next-line unicorn/prefer-spread const actors = [].concat(actor, actor); - notes.push(note); - messages.push({ + state.records.notes.push(note); + state.records.messages.push({ from: actors[0], to: actors[1], message: message.text, @@ -414,7 +417,7 @@ function insertProperties(actor, properties) { * */ function boxEnd() { - currentBox = undefined; + state.records.currentBox = undefined; } export const addDetails = function (actorId, text) { @@ -468,7 +471,7 @@ export const apply = function (param) { } else { switch (param.type) { case 'sequenceIndex': - messages.push({ + state.records.messages.push({ from: undefined, to: undefined, message: { @@ -484,18 +487,18 @@ export const apply = function (param) { addActor(param.actor, param.actor, param.description, param.draw); break; case 'createParticipant': - if (actors[param.actor]) { + if (state.records.actors[param.actor]) { throw new Error( "It is not possible to have actors with the same id, even if one is destroyed before the next is created. Use 'AS' aliases to simulate the behavior" ); } - lastCreated = param.actor; + state.records.lastCreated = param.actor; addActor(param.actor, param.actor, param.description, param.draw); - createdActors[param.actor] = messages.length; + state.records.createdActors[param.actor] = state.records.messages.length; break; case 'destroyParticipant': - lastDestroyed = param.actor; - destroyedActors[param.actor] = messages.length; + state.records.lastDestroyed = param.actor; + state.records.destroyedActors[param.actor] = state.records.messages.length; break; case 'activeStart': addSignal(param.actor, undefined, undefined, param.signalType); @@ -519,25 +522,28 @@ export const apply = function (param) { addDetails(param.actor, param.text); break; case 'addMessage': - if (lastCreated) { - if (param.to !== lastCreated) { + if (state.records.lastCreated) { + if (param.to !== state.records.lastCreated) { throw new Error( 'The created participant ' + - lastCreated + + state.records.lastCreated + ' does not have an associated creating message after its declaration. Please check the sequence diagram.' ); } else { - lastCreated = undefined; + state.records.lastCreated = undefined; } - } else if (lastDestroyed) { - if (param.to !== lastDestroyed && param.from !== lastDestroyed) { + } else if (state.records.lastDestroyed) { + if ( + param.to !== state.records.lastDestroyed && + param.from !== state.records.lastDestroyed + ) { throw new Error( 'The destroyed participant ' + - lastDestroyed + + state.records.lastDestroyed + ' does not have an associated destroying message after its declaration. Please check the sequence diagram.' ); } else { - lastDestroyed = undefined; + state.records.lastDestroyed = undefined; } } addSignal(param.from, param.to, param.msg, param.signalType, param.activate); diff --git a/packages/mermaid/src/utils/imperativeState.spec.ts b/packages/mermaid/src/utils/imperativeState.spec.ts new file mode 100644 index 000000000..e78a7d495 --- /dev/null +++ b/packages/mermaid/src/utils/imperativeState.spec.ts @@ -0,0 +1,78 @@ +import { createImperativeState, domain } from './imperativeState.js'; + +describe('domain.optional', () => { + it('should set undefined without args', () => { + expect(domain.optional()).toBeUndefined(); + }); + + it('should set identity with args', () => { + const value = {}; + expect(domain.optional(value)).toEqual(value); + }); +}); + +describe('domain.identity', () => { + it('should set identity', () => { + const value = {}; + expect(domain.identity(value)).toEqual(value); + }); +}); + +describe('createImperativeState', () => { + it('should create state with values from initializer', () => { + const baz = { + flag: false, + }; + + const state = createImperativeState(() => ({ + foo: domain.optional(), + bar: domain.identity([]), + baz, + })); + + expect(state.records.foo).toBeUndefined(); + expect(state.records.bar).toEqual([]); + expect(state.records.baz).toBe(baz); + }); + + it('should update records', () => { + const state = createImperativeState(() => ({ + foo: domain.optional(), + bar: domain.identity([]), + baz: { + flag: false, + }, + })); + + state.records.foo = 5; + state.records.bar = ['hello']; + state.records.baz.flag = true; + + expect(state.records.foo).toEqual(5); + expect(state.records.bar).toEqual(['hello']); + expect(state.records.baz).toEqual({ + flag: true, + }); + }); + + it('should reset records', () => { + const state = createImperativeState(() => ({ + foo: domain.optional(), + bar: domain.identity([]), + baz: { + flag: false, + }, + })); + + state.records.foo = 5; + state.records.bar = ['hello']; + state.records.baz.flag = true; + state.reset(); + + expect(state.records.foo).toBeUndefined(); + expect(state.records.bar).toEqual([]); + expect(state.records.baz).toEqual({ + flag: false, + }); + }); +}); diff --git a/packages/mermaid/src/utils/imperativeState.ts b/packages/mermaid/src/utils/imperativeState.ts new file mode 100644 index 000000000..bc63844b1 --- /dev/null +++ b/packages/mermaid/src/utils/imperativeState.ts @@ -0,0 +1,37 @@ +export const createImperativeState = >(init: () => S) => { + const state = init(); + + return { + get records() { + return state; + }, + reset: () => { + Object.keys(state).forEach((key) => { + delete state[key]; + }); + Object.entries(init()).forEach(([key, value]: [keyof S, any]) => { + state[key] = value; + }); + }, + }; +}; + +export const domain = { + optional: (value?: V) => value, + identity: (value: V) => value, +} as const; + +/* +const state = createImperativeState(() => ({ + foo: domain.optional(), + bar: domain.identity([]), + baz: domain.optional(1), +})); + +typeof state.records: +{ + foo: string | undefined, // actual: undefined + bar: number[], // actual: [] + baz: number | undefined, // actual: 1 +} +*/ From 18ea27ac58afb342a78167fd59bae1db97a80f09 Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Fri, 13 Oct 2023 00:02:46 +0300 Subject: [PATCH 02/31] chore: add e2e test that shows db cleanup problem --- cypress/helpers/util.ts | 6 ++-- .../rendering/sequencediagram.spec.js | 28 +++++++++++++++++ .../platform/render-diagram-after-error.html | 31 +++++++++++++++++++ 3 files changed, 62 insertions(+), 3 deletions(-) create mode 100644 cypress/platform/render-diagram-after-error.html diff --git a/cypress/helpers/util.ts b/cypress/helpers/util.ts index c656f638d..aed5d7973 100644 --- a/cypress/helpers/util.ts +++ b/cypress/helpers/util.ts @@ -10,7 +10,7 @@ interface CypressConfig { type CypressMermaidConfig = MermaidConfig & CypressConfig; interface CodeObject { - code: string; + code: string | string[]; mermaid: CypressMermaidConfig; } @@ -25,7 +25,7 @@ const batchId: string = : Cypress.env('CYPRESS_COMMIT') || Date.now().toString()); export const mermaidUrl = ( - graphStr: string, + graphStr: string | string[], options: CypressMermaidConfig, api: boolean ): string => { @@ -82,7 +82,7 @@ export const urlSnapshotTest = ( }; export const renderGraph = ( - graphStr: string, + graphStr: string | string[], options: CypressMermaidConfig = {}, api = false ): void => { diff --git a/cypress/integration/rendering/sequencediagram.spec.js b/cypress/integration/rendering/sequencediagram.spec.js index 765913824..ca53986e8 100644 --- a/cypress/integration/rendering/sequencediagram.spec.js +++ b/cypress/integration/rendering/sequencediagram.spec.js @@ -930,4 +930,32 @@ context('Sequence diagram', () => { }); }); }); + context('db clear', () => { + it('should render diagram after fixing destroy participant error', () => { + renderGraph([ + `sequenceDiagram + Alice->>Bob: Hello Bob, how are you ? + Bob->>Alice: Fine, thank you. And you? + create participant Carl + Alice->>Carl: Hi Carl! + create actor D as Donald + Carl->>D: Hi! + destroy Carl + Alice-xCarl: We are too many + destroy Bo + Bob->>Alice: I agree`, + `sequenceDiagram + Alice->>Bob: Hello Bob, how are you ? + Bob->>Alice: Fine, thank you. And you? + create participant Carl + Alice->>Carl: Hi Carl! + create actor D as Donald + Carl->>D: Hi! + destroy Carl + Alice-xCarl: We are too many + destroy Bob + Bob->>Alice: I agree`, + ]); + }); + }); }); diff --git a/cypress/platform/render-diagram-after-error.html b/cypress/platform/render-diagram-after-error.html new file mode 100644 index 000000000..0adbba052 --- /dev/null +++ b/cypress/platform/render-diagram-after-error.html @@ -0,0 +1,31 @@ + + + + + + Mermaid Quick Test Page + + + +
+ + + + From 985eda2deeb180972f2b25ff20c53156c1eccb4b Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Fri, 13 Oct 2023 00:43:48 +0300 Subject: [PATCH 03/31] chore: add e2e test that shows db cleanup problem --- cypress/integration/rendering/sequencediagram.spec.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/cypress/integration/rendering/sequencediagram.spec.js b/cypress/integration/rendering/sequencediagram.spec.js index ca53986e8..fa1db3ab2 100644 --- a/cypress/integration/rendering/sequencediagram.spec.js +++ b/cypress/integration/rendering/sequencediagram.spec.js @@ -932,6 +932,10 @@ context('Sequence diagram', () => { }); context('db clear', () => { it('should render diagram after fixing destroy participant error', () => { + cy.on('uncaught:exception', (err) => { + return false; + }); + renderGraph([ `sequenceDiagram Alice->>Bob: Hello Bob, how are you ? From 6eae46b927e1568a072b14eb1da0202c465db661 Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Fri, 13 Oct 2023 00:48:05 +0300 Subject: [PATCH 04/31] chore: remove unused e2e tests file --- .../platform/render-diagram-after-error.html | 31 ------------------- 1 file changed, 31 deletions(-) delete mode 100644 cypress/platform/render-diagram-after-error.html diff --git a/cypress/platform/render-diagram-after-error.html b/cypress/platform/render-diagram-after-error.html deleted file mode 100644 index 0adbba052..000000000 --- a/cypress/platform/render-diagram-after-error.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - Mermaid Quick Test Page - - - -
- - - - From fc0ade29851bf403fcc1740d6d0bc91933d375a7 Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Fri, 13 Oct 2023 12:07:36 +0300 Subject: [PATCH 05/31] chore(sequence): update doc for actors/participant creation/deletion fix --- cypress/integration/rendering/sequencediagram.spec.js | 2 +- docs/syntax/sequenceDiagram.md | 8 ++++++++ packages/mermaid/src/docs/syntax/sequenceDiagram.md | 8 ++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/cypress/integration/rendering/sequencediagram.spec.js b/cypress/integration/rendering/sequencediagram.spec.js index fa1db3ab2..27e03da9c 100644 --- a/cypress/integration/rendering/sequencediagram.spec.js +++ b/cypress/integration/rendering/sequencediagram.spec.js @@ -930,7 +930,7 @@ context('Sequence diagram', () => { }); }); }); - context('db clear', () => { + context('render after error', () => { it('should render diagram after fixing destroy participant error', () => { cy.on('uncaught:exception', (err) => { return false; diff --git a/docs/syntax/sequenceDiagram.md b/docs/syntax/sequenceDiagram.md index fbfa59d13..1172e2994 100644 --- a/docs/syntax/sequenceDiagram.md +++ b/docs/syntax/sequenceDiagram.md @@ -131,6 +131,14 @@ sequenceDiagram Bob->>Alice: I agree ``` +#### Unfixable actor/participant creation/deletion error (v\+) + +If an error of the following type occurs when creating or deleting an actor/participant: + +> The destroyed participant **participant-name** does not have an associated destroying message after its declaration. Please check the sequence diagram. + +And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version. + ### Grouping / Box The actor(s) can be grouped in vertical boxes. You can define a color (if not, it will be transparent) and/or a descriptive label using the following notation: diff --git a/packages/mermaid/src/docs/syntax/sequenceDiagram.md b/packages/mermaid/src/docs/syntax/sequenceDiagram.md index cdcdaffeb..5f312fee5 100644 --- a/packages/mermaid/src/docs/syntax/sequenceDiagram.md +++ b/packages/mermaid/src/docs/syntax/sequenceDiagram.md @@ -83,6 +83,14 @@ sequenceDiagram Bob->>Alice: I agree ``` +#### Unfixable actor/participant creation/deletion error (v+) + +If an error of the following type occurs when creating or deleting an actor/participant: + +> The destroyed participant **participant-name** does not have an associated destroying message after its declaration. Please check the sequence diagram. + +And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version. + ### Grouping / Box The actor(s) can be grouped in vertical boxes. You can define a color (if not, it will be transparent) and/or a descriptive label using the following notation: From 3128ba73a0be2dc06122ca8c0b4bae884a884958 Mon Sep 17 00:00:00 2001 From: Faris Date: Mon, 16 Oct 2023 19:36:44 +0300 Subject: [PATCH 06/31] chore(sequence): Update packages/mermaid/src/docs/syntax/sequenceDiagram.md Co-authored-by: Sidharth Vinod --- packages/mermaid/src/docs/syntax/sequenceDiagram.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/mermaid/src/docs/syntax/sequenceDiagram.md b/packages/mermaid/src/docs/syntax/sequenceDiagram.md index 5f312fee5..e7df5d8c9 100644 --- a/packages/mermaid/src/docs/syntax/sequenceDiagram.md +++ b/packages/mermaid/src/docs/syntax/sequenceDiagram.md @@ -83,13 +83,13 @@ sequenceDiagram Bob->>Alice: I agree ``` -#### Unfixable actor/participant creation/deletion error (v+) +#### Unfixable actor/participant creation/deletion error If an error of the following type occurs when creating or deleting an actor/participant: > The destroyed participant **participant-name** does not have an associated destroying message after its declaration. Please check the sequence diagram. -And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version. +And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version to (v+). ### Grouping / Box From 3b5f5c78430640cfe048e947ac42e9994efd3cd2 Mon Sep 17 00:00:00 2001 From: Faris Nabiev Date: Mon, 16 Oct 2023 19:47:58 +0300 Subject: [PATCH 07/31] chore: fix autogen docs --- docs/syntax/sequenceDiagram.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/syntax/sequenceDiagram.md b/docs/syntax/sequenceDiagram.md index 1172e2994..2dff973e4 100644 --- a/docs/syntax/sequenceDiagram.md +++ b/docs/syntax/sequenceDiagram.md @@ -131,13 +131,13 @@ sequenceDiagram Bob->>Alice: I agree ``` -#### Unfixable actor/participant creation/deletion error (v\+) +#### Unfixable actor/participant creation/deletion error If an error of the following type occurs when creating or deleting an actor/participant: > The destroyed participant **participant-name** does not have an associated destroying message after its declaration. Please check the sequence diagram. -And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version. +And fixing diagram code does not get rid of this error and rendering of all other diagrams results in the same error, then you need to update the mermaid version to (v\+). ### Grouping / Box From c0b80df1cbd75ab28f151ff20b2f21184ccfda34 Mon Sep 17 00:00:00 2001 From: Steph <35910788+huynhicode@users.noreply.github.com> Date: Mon, 27 Nov 2023 11:36:56 -0800 Subject: [PATCH 08/31] update announcement bar verbiage --- .../src/docs/.vitepress/components/TopBar.vue | 19 +++++++++++-------- .../src/docs/.vitepress/theme/index.ts | 6 +++--- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue index d0a202c58..16da73c91 100644 --- a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue +++ b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue @@ -2,13 +2,16 @@
- - We've made our Product Hunt debut!   - Show us some love and help spread the word, plus receive 25% - off on annual Pro subscription! +

+ Happy Holidays! Get AI, team collaboration, storage, and more with + Mermaid Chart Pro. Use promo code: HOLIDAYS2023 to get + 25% off.View more details here. +

diff --git a/packages/mermaid/src/docs/.vitepress/theme/index.ts b/packages/mermaid/src/docs/.vitepress/theme/index.ts index 656157810..344d602bd 100644 --- a/packages/mermaid/src/docs/.vitepress/theme/index.ts +++ b/packages/mermaid/src/docs/.vitepress/theme/index.ts @@ -6,8 +6,8 @@ import Mermaid from './Mermaid.vue'; import Contributors from '../components/Contributors.vue'; // @ts-ignore import HomePage from '../components/HomePage.vue'; -// // @ts-ignore -// import TopBar from '../components/TopBar.vue'; +// @ts-ignore +import TopBar from '../components/TopBar.vue'; import { getRedirect } from './redirect.js'; @@ -22,7 +22,7 @@ export default { Layout() { return h(Theme.Layout, null, { // Keeping this as comment as it took a lot of time to figure out how to add a component to the top bar. - // 'home-hero-before': () => h(TopBar), + 'home-hero-before': () => h(TopBar), 'home-features-after': () => h(HomePage), }); }, From 8d53fa17da50627afc34fda2634395f6a8fdea84 Mon Sep 17 00:00:00 2001 From: Steph <35910788+huynhicode@users.noreply.github.com> Date: Mon, 27 Nov 2023 11:44:47 -0800 Subject: [PATCH 09/31] update announcements page --- docs/news/announcements.md | 13 +++++++++---- packages/mermaid/src/docs/news/announcements.md | 17 +++++++++++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/news/announcements.md b/docs/news/announcements.md index 79e32f2f0..ec1525f26 100644 --- a/docs/news/announcements.md +++ b/docs/news/announcements.md @@ -6,10 +6,15 @@ # Announcements -Check out our latest blog posts below. See more blog posts [here](blog.md). +## [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion 🎉 -## [5 Reasons You Should Be Using Mermaid Chart As Your Diagram Generator](https://www.mermaidchart.com/blog/posts/5-reasons-you-should-be-using-mermaid-chart-as-your-diagram-generator/) +### Use HOLIDAYS2023 to get 25% off a Pro subscription -14 November 2023 · 5 mins +With a Pro subscription, you will get access to: -Mermaid Chart, a user-friendly, code-based diagram generator with AI integrations, templates, collaborative tools, and plugins for developers, streamlines the process of creating and sharing diagrams, enhancing both creativity and collaboration. +- AI functionality +- Team collaboration and multi-user editing +- Unlimited diagrams +- and more! + +View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/holiday-promo). diff --git a/packages/mermaid/src/docs/news/announcements.md b/packages/mermaid/src/docs/news/announcements.md index 7093d6fba..3f0b1352d 100644 --- a/packages/mermaid/src/docs/news/announcements.md +++ b/packages/mermaid/src/docs/news/announcements.md @@ -1,9 +1,18 @@ +--- +outline: 'deep' # shows all h3 headings in outline in Vitepress +--- + # Announcements -Check out our latest blog posts below. See more blog posts [here](blog.md). +## [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion 🎉 -## [5 Reasons You Should Be Using Mermaid Chart As Your Diagram Generator](https://www.mermaidchart.com/blog/posts/5-reasons-you-should-be-using-mermaid-chart-as-your-diagram-generator/) +### Use HOLIDAYS2023 to get 25% off a Pro subscription -14 November 2023 · 5 mins +With a Pro subscription, you will get access to: -Mermaid Chart, a user-friendly, code-based diagram generator with AI integrations, templates, collaborative tools, and plugins for developers, streamlines the process of creating and sharing diagrams, enhancing both creativity and collaboration. +- AI functionality +- Team collaboration and multi-user editing +- Unlimited diagrams +- and more! + +View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/holiday-promo). From af9566df75f897d5e304cc8b9f2e27e119903724 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 28 Nov 2023 11:42:04 +0530 Subject: [PATCH 10/31] Update packages/mermaid/src/docs/.vitepress/components/TopBar.vue --- packages/mermaid/src/docs/.vitepress/components/TopBar.vue | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue index 16da73c91..025bfcf1a 100644 --- a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue +++ b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue @@ -8,7 +8,6 @@ 25% off.View more details here. From a1563c9f7d023371c358b654f904027b5e94dac1 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Tue, 28 Nov 2023 13:39:46 +0530 Subject: [PATCH 11/31] docs: Holiday promo v2 --- .../src/docs/.vitepress/components/TopBar.vue | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue index 025bfcf1a..ec68cff13 100644 --- a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue +++ b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue @@ -3,14 +3,16 @@ class="w-full top-bar bg-gradient-to-r from-[#bd34fe] to-[#ff3670] flex items-center text-center justify-center p-1 text-white" >

- Happy Holidays! Get AI, team collaboration, storage, and more with - Mermaid Chart Pro. Use promo code: HOLIDAYS2023 to get - 25% off.View more details here. + Get AI, team collaboration, storage, and more with + Mermaid Chart Pro. Start free trial today & get 25% off. +

From 9be9601927ac7a62450e1794d7c8c8be1a61f8d8 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Fri, 1 Dec 2023 12:04:30 +0530 Subject: [PATCH 12/31] chore: Update promo link --- docs/news/announcements.md | 2 +- packages/mermaid/src/docs/.vitepress/components/TopBar.vue | 2 +- packages/mermaid/src/docs/news/announcements.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/news/announcements.md b/docs/news/announcements.md index ec1525f26..d1eaa525e 100644 --- a/docs/news/announcements.md +++ b/docs/news/announcements.md @@ -17,4 +17,4 @@ With a Pro subscription, you will get access to: - Unlimited diagrams - and more! -View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/holiday-promo). +View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). diff --git a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue index ec68cff13..6fdf78c61 100644 --- a/packages/mermaid/src/docs/.vitepress/components/TopBar.vue +++ b/packages/mermaid/src/docs/.vitepress/components/TopBar.vue @@ -4,7 +4,7 @@ >

diff --git a/packages/mermaid/src/docs/news/announcements.md b/packages/mermaid/src/docs/news/announcements.md index 3f0b1352d..6e947065f 100644 --- a/packages/mermaid/src/docs/news/announcements.md +++ b/packages/mermaid/src/docs/news/announcements.md @@ -15,4 +15,4 @@ With a Pro subscription, you will get access to: - Unlimited diagrams - and more! -View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/holiday-promo). +View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). From 78c44bf7938c05a45e896367f0ba78807068f931 Mon Sep 17 00:00:00 2001 From: Steph <35910788+huynhicode@users.noreply.github.com> Date: Mon, 4 Dec 2023 11:07:55 -0800 Subject: [PATCH 13/31] add blog post --- docs/news/announcements.md | 12 ++++++++++-- docs/news/blog.md | 6 ++++++ packages/mermaid/src/docs/news/announcements.md | 12 ++++++++++-- packages/mermaid/src/docs/news/blog.md | 6 ++++++ 4 files changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/news/announcements.md b/docs/news/announcements.md index d1eaa525e..6e1daa81a 100644 --- a/docs/news/announcements.md +++ b/docs/news/announcements.md @@ -6,7 +6,7 @@ # Announcements -## [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion 🎉 +## 🎉 [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion ### Use HOLIDAYS2023 to get 25% off a Pro subscription @@ -17,4 +17,12 @@ With a Pro subscription, you will get access to: - Unlimited diagrams - and more! -View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). +Redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). + +## 🤓 Read our latest blog post + +### [7 best practices (+ examples) for good developer documentation](https://www.mermaidchart.com/blog/posts/7-best-practices-for-good-documentation/) + +4 December 2023 · 11 min + +Essential strategies for crafting grate developer documentation, with practical examples and insights from leading tech companies. diff --git a/docs/news/blog.md b/docs/news/blog.md index da20ed1bb..7c9deb012 100644 --- a/docs/news/blog.md +++ b/docs/news/blog.md @@ -6,6 +6,12 @@ # Blog +## [7 best practices (+ examples) for good developer documentation](https://www.mermaidchart.com/blog/posts/7-best-practices-for-good-documentation/) + +4 December 2023 · 11 min + +Essential strategies for crafting grate developer documentation, with practical examples and insights from leading tech companies. + ## [5 Reasons You Should Be Using Mermaid Chart As Your Diagram Generator](https://www.mermaidchart.com/blog/posts/5-reasons-you-should-be-using-mermaid-chart-as-your-diagram-generator/) 14 November 2023 · 5 mins diff --git a/packages/mermaid/src/docs/news/announcements.md b/packages/mermaid/src/docs/news/announcements.md index 6e947065f..430fc74d1 100644 --- a/packages/mermaid/src/docs/news/announcements.md +++ b/packages/mermaid/src/docs/news/announcements.md @@ -4,7 +4,7 @@ outline: 'deep' # shows all h3 headings in outline in Vitepress # Announcements -## [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion 🎉 +## 🎉 [Mermaid Chart](https://www.mermaidchart.com/) is running a Holiday promotion ### Use HOLIDAYS2023 to get 25% off a Pro subscription @@ -15,4 +15,12 @@ With a Pro subscription, you will get access to: - Unlimited diagrams - and more! -View details on how to redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). +Redeem the promo code on the [Mermaid Chart website](https://www.mermaidchart.com/app/user/billing/checkout?coupon=HOLIDAYS2023). + +## 🤓 Read our latest blog post + +### [7 best practices (+ examples) for good developer documentation](https://www.mermaidchart.com/blog/posts/7-best-practices-for-good-documentation/) + +4 December 2023 · 11 min + +Essential strategies for crafting grate developer documentation, with practical examples and insights from leading tech companies. diff --git a/packages/mermaid/src/docs/news/blog.md b/packages/mermaid/src/docs/news/blog.md index d9bf6a8b7..9192774f5 100644 --- a/packages/mermaid/src/docs/news/blog.md +++ b/packages/mermaid/src/docs/news/blog.md @@ -1,5 +1,11 @@ # Blog +## [7 best practices (+ examples) for good developer documentation](https://www.mermaidchart.com/blog/posts/7-best-practices-for-good-documentation/) + +4 December 2023 · 11 min + +Essential strategies for crafting grate developer documentation, with practical examples and insights from leading tech companies. + ## [5 Reasons You Should Be Using Mermaid Chart As Your Diagram Generator](https://www.mermaidchart.com/blog/posts/5-reasons-you-should-be-using-mermaid-chart-as-your-diagram-generator/) 14 November 2023 · 5 mins From 276b5c748a7cc74322b0fa9b4af229713215879f Mon Sep 17 00:00:00 2001 From: Steph <35910788+huynhicode@users.noreply.github.com> Date: Mon, 4 Dec 2023 13:47:20 -0800 Subject: [PATCH 14/31] update getting started page --- docs/intro/getting-started.md | 218 ++++++++++++----- .../mermaid/src/docs/intro/getting-started.md | 230 +++++++++++++----- 2 files changed, 324 insertions(+), 124 deletions(-) diff --git a/docs/intro/getting-started.md b/docs/intro/getting-started.md index 95d7b594e..6cd69e2d6 100644 --- a/docs/intro/getting-started.md +++ b/docs/intro/getting-started.md @@ -4,30 +4,61 @@ > > ## Please edit the corresponding file in [/packages/mermaid/src/docs/intro/getting-started.md](../../packages/mermaid/src/docs/intro/getting-started.md). -# A Mermaid User-Guide for Beginners +# Mermaid User Guide -Mermaid is composed of three parts: Deployment, Syntax and Configuration. +## Mermaid is composed of three parts -This section talks about the different ways to deploy Mermaid. Learning the [Syntax](syntax-reference.md) would be of great help to the beginner. +1. Deployment +2. Syntax +3. Configuration -> Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning. +This section talks about the different ways to **deploy** Mermaid. -**Absolute beginners are advised to view the Video [Tutorials](../config/Tutorials.md) on the Live Editor, to gain a better understanding of mermaid.** +If you are a beginner: -## Four ways of using mermaid: +- Check out the [Diagram Syntax](syntax-reference.md) page +- Check out the [Tutorials](../config/Tutorials.md) page -1. Using the Mermaid Live Editor at [mermaid.live](https://mermaid.live). -2. Using [mermaid plugins](../ecosystem/integrations-community.md) with programs you are familiar with. -3. Calling the Mermaid JavaScript API. -4. Deploying Mermaid as a dependency. +## Ways to use Mermaid -**Note: It is our recommendation that you review all approaches, and choose the one that is best for your project.** +1. [Using the Mermaid Chart Editor](getting-started.html#_1-using-the-mermaid-chart-editor) +2. [Using the Mermaid Live Editor](getting-started.html#_1-using-the-mermaid-chart-editor) +3. [Using Mermaid Plugins and Integrations](getting-started.html#_3-using-mermaid-plugins) +4. [Calling the Mermaid JavaScript API](getting-started.html#_4-calling-the-mermaid-javascript-api) +5. [Adding Mermaid as a dependency](getting-started.html#_5-adding-mermaid-as-a-dependency) -> More in depth information can be found at [Usage](../config/usage.md). +To learn more, visit the [Usage](../config/usage.md) page. -## 1. Using the Live Editor +## 1. Using the Mermaid Chart Editor -Available at [mermaid.live](https://mermaid.live) +Available at the [Mermaid Chart](https://www.mermaidchart.com/) website. + +Mermaid Chart is a web-based diagram editor that allows you to create and edit diagrams in your browser. It is built by the team behind Mermaid. + +Features include: + +- AI diagramming +- Collaboration & multi-user editing +- Storage +- and more + +To learn more, visit the [Mermaid Chart page](/ecosystem/mermaid-chart.html) in the Ecosystem section of the documentation. + +Or go to the [Mermaid Chart website](https://www.mermaidchart.com/app/sign-up) to sign up for a Free account. + +## 2. Using the Mermaid Live Editor + +Available at the [Mermaid Live Editor](https://mermaid.live) website. + +### Features + +
+ +#### • Diagram Code + +In the `Code` panel, write or edit Mermaid code, and instantly `Preview` the rendered result in the diagram panel. + +Here is an example of Mermaid code and its rendered result: ```mermaid-example graph TD @@ -51,79 +82,132 @@ graph TD F --> B ``` -In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it. +
-The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the [Advanced usage](../config/advanced.md) section. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page. +#### • Configurations + +Configuration options are available in the `Configuration` panel. The options are applied to the diagram in the `Preview` panel. + +For learn more, visit the [Configuration Reference](../config/setup/README.md) page ![Code,Config and Preview](./img/Code-Preview-Config.png) -### Editing History +
-Your code will be autosaved every minute into the Timeline tab of History which shows the most recent 30 items. +#### • Editing History -You can manually save code by clicking the Save icon in the History section. It can also be accessed in the Saved tab. This is stored in the browser storage only. +Your code will be autosaved and appear in the `Timeline` tab of the `History` section. Edits are saved every minute and only the last 30 edits are viewable. -### Saving a Diagram: +Alternatively, you can manually save code by clicking on the `Save` icon from the `History` section. -You may choose any of the methods below, to save it +> **Note** +> History is stored in the browser storage only. -**We recommend that you save your diagram code on top of any method you choose, in order to make edits and modifications further down the line.** +
+ +#### • Saving a diagram + +There are multiple ways of saving your diagram from the `Actions` section: + +- export PNG +- export SVG +- export as Markdown ![Flowchart](./img/Live-Editor-Choices.png) -### Editing your diagrams +
-Editing is as easy as pasting your **Diagram code**, into the `code` section of the `Live Editor`. +#### • Editing your diagrams -### Loading from Gists +To edit your diagram, you can copy paste existing Mermaid diagram code into the `Code` section of the `Live Editor`. -The Gist you create should have a code.mmd file and optionally a config.json. [Example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a) +Or: -To load a gist into the Editor, you can use +- create a new diagram from scratch +- use a Sample Diagram from the `Sample Diagrams` section -and to View, +
-## 2. Using Mermaid Plugins: +#### • Loading from Gists -You can generate mermaid diagrams from within popular applications using plug-ins. It can be done in the same way, you would use the Live Editor. Here's a list of [Mermaid Plugins](../ecosystem/integrations-community.md). +The Gist you create should have a `code.mmd` file and optionally a `config.json`, similar to this [example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a). -**This is covered in greater detail in the [Usage section](../config/usage.md)** +> **Note** +> To learn about Gists, visit the GitHub documentation page on [Creating gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists). -## 3. Calling the JavaScript API +Once you have created a Gist, copy paste the Gist URL into the respective field in the `Actions` section and click on the `Load Gist` button. -This method can be used with any common web server like Apache, IIS, nginx, node express. +Here is an example of a Gist being loaded into the Editor: -You will also need a text editing tool like Notepad++ to generate a .html file. It is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer). + + +And, here is the diagram view from the above example: + + + +## 3. Using Mermaid Plugins + +### Mermaid Plugins + +You can generate Mermaid diagrams from within popular applications using plug-ins. + +For a list of Mermaid Plugins and Integrations, visit the [Integrations page](../ecosystem/integrations-community.md). + +### Mermaid Chart Plugins + +Mermaid Chart plugins are available for: + +- [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) +- [Visual Studio Code](https://docs.mermaidchart.com/plugins/visual-studio-code) + +To learn more, visit the [Mermaid Chart Plugins](https://www.mermaidchart.com/plugins) page. + +## 4. Calling the Mermaid JavaScript API + +This method can be used with any common web server like `Apache`, `IIS`, `Nginx`, and `Node Express`. + +You will also need a text editing tool like `Notepad++` to generate an `html` file. It is then deployed by a web browser, i.e. `Firefox`, `Chrome`, `Safari`. + +> **Note** +> Internet Explorer is not supported. The API works by pulling rendering instructions from the source `mermaid.js` in order to render diagrams on the page. -### Requirements for the Mermaid API. +### Requirements for the Mermaid API -When writing the .html file, we give two instructions inside the html code to the web browser: +When writing the `html` file, we give two instructions inside the `html code` to the `web browser`: -a. The mermaid code for the diagram we want to create. +a. The Mermaid code for the diagram we want to create. -b. The importing of mermaid library through the `mermaid.esm.mjs` or `mermaid.esm.min.mjs` and the `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process. +b. The importing of the Mermaid library through the `mermaid.esm.mjs` or `mermaid.esm.min.mjs`, and the `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process. -**a. The embedded mermaid diagram definition inside a `

`:**
+#### Examples
+
+- This is an example of an embedded Mermaid diagram definition inside a `
`:
 
 ```html
 
   Here is a mermaid diagram:
   
-        graph TD 
-        A[Client] --> B[Load Balancer] 
-        B --> C[Server01] 
+        graph TD
+        A[Client] --> B[Load Balancer]
+        B --> C[Server01]
         B --> D[Server02]
   

 
 ```
 
-**Notes**: Every Mermaid chart/graph/diagram definition, should have separate `
` tags.
+> **Note**
+> Every Mermaid chart/graph/diagram definition should have separate `
` tags.
 
-**b. The import of mermaid and the `mermaid.initialize()` call.**
+

 
-`mermaid.initialize()` call takes all the definitions contained in all the `
` tags that it finds in the html body and renders them into diagrams. Example:
+- This is an example of a Mermaid import and the `mermaid.initialize()` call.
+
+> **Note**
+> A `mermaid.initialize()` call takes all the definitions contained within `
` tags and renders them into diagrams.
 
 ```html
 
@@ -134,8 +218,8 @@ b. The importing of mermaid library through the `mermaid.esm.mjs` or `mermaid.es
 
 ```
 
-**Notes**:
-Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `
` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `
` tags may have loaded on the execution of `mermaid.esm.min.mjs` file.
+> **Note**
+> Rendering in Mermaid is initialized by the `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `
` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `
` tags may have loaded on the execution of `mermaid.esm.min.mjs` file.
 
 `startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()`
 
@@ -143,9 +227,9 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doi
 | ----------- | --------------------------------- | ------- | ----------- |
 | startOnLoad | Toggle for Rendering upon loading | Boolean | true, false |
 
-### Working Examples
+

 
-**Here is a full working example of the mermaidAPI being called through the CDN:**
+In this example, the `mermaidAPI` is being called through the `CDN`:
 
 ```html
 
@@ -175,8 +259,9 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doi
 
 ```
 
-**Another Option:**
-In this example mermaid.js is referenced in `src` as a separate JavaScript file, in an example Path.
+

+
+In this example, `mermaid.js` is referenced in `src` as a separate JavaScript file:
 
 ```html
 
@@ -204,21 +289,30 @@ In this example mermaid.js is referenced in `src` as a separate JavaScript file,
 
 ```
 
----
+## 5. Adding Mermaid as a dependency
 
-## 4. Adding Mermaid as a dependency.
+Below are the steps for adding Mermaid as a dependency:
 
-1.  install node v16, which would have npm
+1.  Install `node v16`
 
-2.  download yarn using npm by entering the command below:
-    npm install -g yarn
+> **Note**
+> To learn more about downloading and installing `Node.js` and `npm`, visit the [npm Docs website](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
 
-3.  After yarn installs, enter the following command:
-    yarn add mermaid
+1.  Install `yarn` using `npm` with this command:
 
-4.  To add Mermaid as a Dev Dependency
-    yarn add --dev mermaid
+    `npm install -g yarn`
 
-**Comments from Knut Sveidqvist, creator of mermaid:**
+2.  After yarn installs, enter this command:
 
-- In early versions of mermaid, the `