Merge pull request mermaid-js#3907 from huynhicode/docs/formatting

docs: fix text overflow
surelion · Dec 23, 2022 · 8ed1ad5 · 8ed1ad5
2 parents c23cd49 + dbfb29d
commit 8ed1ad5
Show file tree

Hide file tree

Showing 11 changed files with 180 additions and 156 deletions.
diff --git a/docs/config/accessibility.md b/docs/config/accessibility.md
@@ -80,9 +80,12 @@ A **multiple line accessible description** _does not have a colon (`:`) after th
 
 Ex:
 
-    accDescr { The official Bob's Burgers corporate processes that are used
-            for making very, very big decisions.
-            This is actually a very simple flow: see the big decision and then make the big decision.}
+```markdown
+accDescr {
+This is a multiple line accessible description.
+It does not have a colon and is surrounded by curly brackets.
+}
+```
 
 See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.
 

diff --git a/docs/config/directives.md b/docs/config/directives.md
@@ -32,7 +32,8 @@ Mermaid basically supports two types of configuration options to be overridden b
 
 **NOTE:** These options listed here are not all the configuration options. To get hold of all the configuration options, please refer to the [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
 
-    Soon we plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs
+> **Note**
+> We plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs soon.
 
 ## Declaring directives
 

diff --git a/docs/config/n00b-advanced.md b/docs/config/n00b-advanced.md
@@ -10,17 +10,21 @@
 
 A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so:
 
-    stuff stuff
-      </div>
-      </body>
-    </html>
+```html
+...
+  </div>
+  </body>
+</html>
+```
 
 The actual mermaid file could for example look like this:
 
-    mermaid content...
-
----
+```javascript
+mermaid content ...
+```
 
 ## mermaid configuration options
 
-...
+```markdown
+(coming soon)
+```
diff --git a/docs/config/usage.md b/docs/config/usage.md
@@ -22,24 +22,21 @@ For the majority of users, Using the [Live Editor](https://mermaid.live/) would
 
 We have compiled some Video [Tutorials](./Tutorials.md) on how to use the mermaid Live Editor.
 
-**Installing and Hosting Mermaid on a Webpage**
+### Installing and Hosting Mermaid on a Webpage
 
-**Using the npm package**
+**Using the npm package:**
 
-    1. You will need to install node v16, which would have npm.
+1.  You will need to install `node v16`, which would have npm.
 
-    2. download yarn using npm.
+2.  Download `yarn` using npm.
 
-    3. enter the following command:
-        yarn add mermaid
+3.  Enter the following command: `yarn add mermaid`.
 
-    4. At this point, you can add mermaid as a dev dependency using this command:
-        yarn add --dev mermaid
+4.  At this point, you can add mermaid as a dev dependency using this command: `yarn add --dev mermaid`.
 
-    5. Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions.
-        as is shown in the example below
+5.  Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions as is shown in the example below.
 
-**Hosting mermaid on a web page.**
+**Hosting mermaid on a web page:**
 
 > Note:This topic explored in greater depth in the [User Guide for Beginners](../intro/n00b-gettingStarted.md)
 

diff --git a/docs/syntax/gantt.md b/docs/syntax/gantt.md
@@ -172,77 +172,88 @@ Final milestone : milestone, m2, 18:14, 2min
 
 The default input date format is `YYYY-MM-DD`. You can define your custom `dateFormat`.
 
-    dateFormat YYYY-MM-DD
+```markdown
+dateFormat YYYY-MM-DD
+```
 
 The following formatting options are supported:
 
-    Input       Example             Description:
-    YYYY        2014                4 digit year
-    YY          14                  2 digit year
-    Q           1..4                Quarter of year. Sets month to first month in quarter.
-    M MM        1..12               Month number
-    MMM MMMM    January..Dec        Month name in locale set by moment.locale()
-    D DD        1..31               Day of month
-    Do          1st..31st           Day of month with ordinal
-    DDD DDDD    1..365              Day of year
-    X           1410715640.579      Unix timestamp
-    x           1410715640579       Unix ms timestamp
-    H HH        0..23               24 hour time
-    h hh        1..12               12 hour time used with a A.
-    a A         am pm               Post or ante meridiem
-    m mm        0..59               Minutes
-    s ss        0..59               Seconds
-    S           0..9                Tenths of a second
-    SS          0..99               Hundreds of a second
-    SSS         0..999              Thousandths of a second
-    Z ZZ        +12:00              Offset from UTC as +-HH:mm, +-HHmm, or Z
+| Input      | Example        | Description                                            |
+| ---------- | -------------- | ------------------------------------------------------ |
+| `YYYY`     | 2014           | 4 digit year                                           |
+| `YY`       | 14             | 2 digit year                                           |
+| `Q`        | 1..4           | Quarter of year. Sets month to first month in quarter. |
+| `M MM`     | 1..12          | Month number                                           |
+| `MMM MMMM` | January..Dec   | Month name in locale set by `moment.locale()`          |
+| `D DD`     | 1..31          | Day of month                                           |
+| `Do`       | 1st..31st      | Day of month with ordinal                              |
+| `DDD DDDD` | 1..365         | Day of year                                            |
+| `X`        | 1410715640.579 | Unix timestamp                                         |
+| `x`        | 1410715640579  | Unix ms timestamp                                      |
+| `H HH`     | 0..23          | 24 hour time                                           |
+| `h hh`     | 1..12          | 12 hour time used with `a A`.                          |
+| `a A`      | am pm          | Post or ante meridiem                                  |
+| `m mm`     | 0..59          | Minutes                                                |
+| `s ss`     | 0..59          | Seconds                                                |
+| `S`        | 0..9           | Tenths of a second                                     |
+| `SS`       | 0..99          | Hundreds of a second                                   |
+| `SSS`      | 0..999         | Thousandths of a second                                |
+| `Z ZZ`     | +12:00         | Offset from UTC as +-HH:mm, +-HHmm, or Z               |
 
 More info in: https://momentjs.com/docs/#/parsing/string-format/
 
 ### Output date format on the axis
 
 The default output date format is `YYYY-MM-DD`. You can define your custom `axisFormat`, like `2020-Q1` for the first quarter of the year 2020.
 
-    axisFormat  %Y-%m-%d
+```markdown
+axisFormat %Y-%m-%d
+```
 
 The following formatting strings are supported:
 
-    %a - abbreviated weekday name.
-    %A - full weekday name.
-    %b - abbreviated month name.
-    %B - full month name.
-    %c - date and time, as "%a %b %e %H:%M:%S %Y".
-    %d - zero-padded day of the month as a decimal number [01,31].
-    %e - space-padded day of the month as a decimal number [ 1,31]; equivalent to %_d.
-    %H - hour (24-hour clock) as a decimal number [00,23].
-    %I - hour (12-hour clock) as a decimal number [01,12].
-    %j - day of the year as a decimal number [001,366].
-    %m - month as a decimal number [01,12].
-    %M - minute as a decimal number [00,59].
-    %L - milliseconds as a decimal number [000, 999].
-    %p - either AM or PM.
-    %S - second as a decimal number [00,61].
-    %U - week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
-    %w - weekday as a decimal number [0(Sunday),6].
-    %W - week number of the year (Monday as the first day of the week) as a decimal number [00,53].
-    %x - date, as "%m/%d/%Y".
-    %X - time, as "%H:%M:%S".
-    %y - year without century as a decimal number [00,99].
-    %Y - year with century as a decimal number.
-    %Z - time zone offset, such as "-0700".
-    %% - a literal "%" character.
+| Format | Definition                                                                                 |
+| ------ | ------------------------------------------------------------------------------------------ |
+| %a     | abbreviated weekday name                                                                   |
+| %A     | full weekday name                                                                          |
+| %b     | abbreviated month name                                                                     |
+| %B     | full month name                                                                            |
+| %c     | date and time, as "%a %b %e %H:%M:%S %Y"                                                   |
+| %d     | zero-padded day of the month as a decimal number \[01,31]                                  |
+| %e     | space-padded day of the month as a decimal number \[ 1,31]; equivalent to %\_d             |
+| %H     | hour (24-hour clock) as a decimal number \[00,23]                                          |
+| %I     | hour (12-hour clock) as a decimal number \[01,12]                                          |
+| %j     | day of the year as a decimal number \[001,366]                                             |
+| %m     | month as a decimal number \[01,12]                                                         |
+| %M     | minute as a decimal number \[00,59]                                                        |
+| %L     | milliseconds as a decimal number \[000, 999]                                               |
+| %p     | either AM or PM                                                                            |
+| %S     | second as a decimal number \[00,61]                                                        |
+| %U     | week number of the year (Sunday as the first day of the week) as a decimal number \[00,53] |
+| %w     | weekday as a decimal number \[0(Sunday),6]                                                 |
+| %W     | week number of the year (Monday as the first day of the week) as a decimal number \[00,53] |
+| %x     | date, as "%m/%d/%Y"                                                                        |
+| %X     | time, as "%H:%M:%S"                                                                        |
+| %y     | year without century as a decimal number \[00,99]                                          |
+| %Y     | year with century as a decimal number                                                      |
+| %Z     | time zone offset, such as "-0700"                                                          |
+| %%     | a literal "%" character                                                                    |
 
 More info in: <https://github.com/d3/d3-time-format/tree/v4.0.0#locale_format>
 
 ### Axis ticks
 
 The default output ticks are auto. You can custom your `tickInterval`, like `1day` or `1week`.
 
-    tickInterval 1day
+```markdown
+tickInterval 1day
+```
 
 The pattern is:
 
-    /^([1-9][0-9]*)(minute|hour|day|week|month)$/
+```javascript
+/^([1-9][0-9]*)(minute|hour|day|week|month)$/;
+```
 
 More info in: <https://github.com/d3/d3-time#interval_every>
 

diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts
@@ -146,9 +146,22 @@ const readSyncedUTF8file = (filename: string): string => {
   return readFileSync(filename, 'utf8');
 };
 
-const transformToBlockQuote = (content: string, type: string) => {
-  const title = type === 'warning' ? 'Warning' : 'Note';
-  return `> **${title}** \n> ${content.replace(/\n/g, '\n> ')}`;
+const blockIcons: Record<string, string> = {
+  tip: '💡 ',
+  danger: '‼️ ',
+};
+
+const capitalize = (word: string) => word[0].toUpperCase() + word.slice(1);
+
+const transformToBlockQuote = (content: string, type: string, customTitle?: string | null) => {
+  if (vitepress) {
+    const vitepressType = type === 'note' ? 'info' : type;
+    return `::: ${vitepressType} ${customTitle || ''}\n${content}\n:::`;
+  } else {
+    const icon = blockIcons[type] || '';
+    const title = `${icon}${customTitle || capitalize(type)}`;
+    return `> **${title}** \n> ${content.replace(/\n/g, '\n> ')}`;
+  }
 };
 
 const injectPlaceholders = (text: string): string =>
@@ -194,8 +207,8 @@ const transformMarkdown = (file: string) => {
     }
 
     // Transform codeblocks into block quotes.
-    if (['note', 'tip', 'warning'].includes(c.lang)) {
-      return [remark.parse(transformToBlockQuote(c.value, c.lang))];
+    if (['note', 'tip', 'warning', 'danger'].includes(c.lang)) {
+      return [remark.parse(transformToBlockQuote(c.value, c.lang, c.meta))];
     }
 
     return [c];

diff --git a/packages/mermaid/src/docs/config/accessibility.md b/packages/mermaid/src/docs/config/accessibility.md
@@ -74,10 +74,11 @@ A **multiple line accessible description** _does not have a colon (`:`) after th
 
 Ex:
 
-```
-accDescr { The official Bob's Burgers corporate processes that are used
-        for making very, very big decisions.
-        This is actually a very simple flow: see the big decision and then make the big decision.}
+```markdown
+accDescr {
+This is a multiple line accessible description.
+It does not have a colon and is surrounded by curly brackets.
+}
 ```
 
 See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.

diff --git a/packages/mermaid/src/docs/config/directives.md b/packages/mermaid/src/docs/config/directives.md
@@ -26,8 +26,8 @@ Mermaid basically supports two types of configuration options to be overridden b
 
 **NOTE:** These options listed here are not all the configuration options. To get hold of all the configuration options, please refer to the [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
 
-```
-Soon we plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs
+```note
+We plan to publish a complete list of top-level configurations & all the diagram specific configurations, with their possible values in the docs soon.
 ```
 
 ## Declaring directives

diff --git a/packages/mermaid/src/docs/config/n00b-advanced.md b/packages/mermaid/src/docs/config/n00b-advanced.md
@@ -4,21 +4,21 @@
 
 A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so:
 
-```
-stuff stuff
+```html
+...
   </div>
   </body>
 </html>
 ```
 
 The actual mermaid file could for example look like this:
 
-```
-mermaid content...
+```javascript
+mermaid content ...
 ```
 
----
-
 ## mermaid configuration options
 
-...
+```markdown
+(coming soon)
+```
diff --git a/packages/mermaid/src/docs/config/usage.md b/packages/mermaid/src/docs/config/usage.md
@@ -16,26 +16,21 @@ For the majority of users, Using the [Live Editor](https://mermaid.live/) would
 
 We have compiled some Video [Tutorials](./Tutorials.md) on how to use the mermaid Live Editor.
 
-**Installing and Hosting Mermaid on a Webpage**
+### Installing and Hosting Mermaid on a Webpage
 
-**Using the npm package**
+**Using the npm package:**
 
-```
-1. You will need to install node v16, which would have npm.
+1. You will need to install `node v16`, which would have npm.
 
-2. download yarn using npm.
+2. Download `yarn` using npm.
 
-3. enter the following command:
-    yarn add mermaid
+3. Enter the following command: `yarn add mermaid`.
 
-4. At this point, you can add mermaid as a dev dependency using this command:
-    yarn add --dev mermaid
+4. At this point, you can add mermaid as a dev dependency using this command: `yarn add --dev mermaid`.
 
-5. Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions.
-    as is shown in the example below
-```
+5. Alternatively, you can also deploy mermaid using the script tag in an HTML file with mermaid diagram descriptions as is shown in the example below.
 
-**Hosting mermaid on a web page.**
+**Hosting mermaid on a web page:**
 
 > Note:This topic explored in greater depth in the [User Guide for Beginners](../intro/n00b-gettingStarted.md)