diff --git a/docs/README.md b/docs/README.md index 57e6b8039..daec315ab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,9 @@ # About Mermaid -**Mermaid lets you represent diagrams using text and code.** This simplifies maintaining complex diagrams. It is a Javascript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. The main purpose of Mermaid is to help Documentation catch up with Development. +**Mermaid lets you create diagrams using text and code.** This simplifies the maintenance of complex diagrams. It is a Javascript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. + +>If you are familiar with Markdown you should have no problem learning [Mermaid's Syntax](./n00b-syntaxReference.md). -Many editors, wikis and other tools have mermaid integrations already making it easy to start using mermaid. A few of those are described in [Simple start to write diagrams](/n00b-gettingStarted). ![banner](img/header.png) @@ -11,18 +12,21 @@ Many editors, wikis and other tools have mermaid integrations already making it [![Build Status](https://travis-ci.org/mermaid-js/mermaid.svg?branch=master)](https://travis-ci.org/mermaid-js/mermaid) [![NPM](https://img.shields.io/npm/v/mermaid)](https://www.npmjs.com/package/mermaid) [![Coverage Status](https://coveralls.io/repos/github/mermaid-js/mermaid/badge.svg?branch=master)](https://coveralls.io/github/mermaid-js/mermaid?branch=master) [![Join our Slack!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=slack&label=slack)](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) [![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/Mermaid/mermaid) -> Doc-Rot is a Catch-22 that Mermaid helps to solve. +The main purpose of Mermaid is to help Documentation catch up with Development. +> Documentation-Rot is a Catch-22 that Mermaid helps to solve. + +Diagramming and Documentation costs precious developer time and gets outdated quickly. +But not having diagrams or docs ruins productivity and hurts organizational learning. -Diagramming and documentation costs precious developer time and gets outdated quickly. -But not having diagrams or docs ruins productivity and hurts organizational learning.
Mermaid addresses this Catch-22 by cutting the time, effort and tooling that is required to create modifiable diagrams and charts, for smarter and more reusable content. Mermaid, as a text-based diagramming tool allows for quick and easy updates, it can also be made part of production scripts (and other pieces of code), to make documentation much easier. -With Mermaid less time needs to be spent on making diagrams, as a separate documentation task.
> Mermaid is a Diagramming tool for everyone. Even non-programmers can create diagrams through the [Mermaid Live Editor](https://github.com/mermaid-js/mermaid-live-editor), Visit the [Tutorials Page](./Tutorials.md) for the Live Editor video tutorials. +Many editors, wikis and other tools also have mermaid integrations and plugins, making it easy to start using mermaid. A few of those are described in [Simple start to write diagrams](./n00b-gettingStarted.md). + Want to see what can be built with mermaid, or what applications already support it? Read the [Integrations and Usages for Mermaid](./integrations.md). For a more detailed introduction to Mermaid and some of it's more basic uses, look to the [Overview for Beginners](./n00b-overview.md) and [Usage](./usage.md). @@ -172,12 +176,10 @@ To select a version: Replace `` with the desired version number. -Alternatively, you can also adjust the version number in the page itself. - Latest Version: [https://unpkg.com/browse/mermaid@8.8.0/](https://unpkg.com/browse/mermaid@8.8.0/) ## Deploying Mermaid -To support mermaid on your website, all you have to do is add Mermaid’s JavaScript package +To Deploy Mermaid: ``` 1.You will need to install node v10 or 12, which would have npm @@ -191,13 +193,15 @@ To support mermaid on your website, all you have to do is add Mermaid’s JavaSc yarn add --dev mermaid ``` +## [Mermaid API](./Setup.md): **To deploy mermaid without a bundler, one can insert a `script` tag with an absolute address and a `mermaidAPI` call into the HTML like so:** + ```html ``` -**Doing so will command the mermaid parser to look for the `
` tags with `class="mermaid"` in your HTML Document. From these tags mermaid will try to read the diagram/chart definitons and render them as svg charts.** +**Doing so will command the mermaid parser to look for the `
` tags with `class="mermaid"`. From these tags mermaid will try to read the diagram/chart definitons and render them into svg charts.** **Examples can be found in** [Other examples](/examples) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 919c3b8f1..eb9b718b0 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -6,6 +6,7 @@ - Diagram Syntax 📊 + - [Diagram syntax intro](n00b-syntaxReference.md) - [Flowchart](flowchart.md) - [Sequence diagram](sequenceDiagram.md) - [Class Diagram](classDiagram.md) @@ -18,7 +19,6 @@ - Adding mermaid✒️ - - [Diagram syntax intro](n00b-syntaxReference.md) - [Tutorials](Tutorials.md) - [API-Usage](usage.md) - [Configuration handling in Mermaid API](Setup.md) diff --git a/docs/directives.md b/docs/directives.md index 322cee353..407d40ef5 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -5,10 +5,9 @@ ## Directives Directives gives a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration. -Directives are divided in two sets by priority. The first set, containing 'init' or 'initialize' directives take priority. While the other set, containing all other kinds of directives are parsed and factored into the rendering, only after 'init' and the desired graph-type are declared. - -#### Init +Directives are divided into two sets or orders, by priority in parsing. The first set, containing 'init' or 'initialize' directives are loaded ahead of any other directive. While the other set, containing all other kinds of directives are parsed and factored into the rendering, only after 'init' and the desired graph-type are declared. +### Init | Parameter | Description |Type | Required | Values| | --- | --- | --- | --- | --- | @@ -51,9 +50,9 @@ parsing the above generates the `%%init%%` object below, combining the two direc This will then be sent to `mermaid.initialize(...)` for rendering. -#### Other directives +### Other directives -In this category are any directives that follow the graph type declaration. Essentially, these directives will not be processed early in the flow like the init directive. Each individual graph type will handle these directives. As an example: +In this category are any directives that come after the graph type declaration. Essentially, these directives will only be processed after the init directive. Each individual graph type will handle these directives. As an example: ``` %%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%% @@ -65,16 +64,19 @@ Bob->>Alice: Hi Alice ## Chronology This will set the `logLevel` to `debug` and `theme` to `dark` for a sequence diagram. Then, during processing, the config for the sequence diagram is set by the `config` directive. This directive is handled in the `sequenceDb.js`. In this example, the fontFamily, fontSize, and fontWeight are all set for this sequence diagram. +### Wrapping + +## Wrap + +| Parameter | Description |Type | Required | Values| +| --- | --- | --- | --- | --- | +| wrap | a callable text-wrap function| Directive| Optional | %%{wrap}%%| + + #### Backwards Compatibility Init directives and any other non-multiline directives should be backwards compatible, because they will be treated as comments in prior versions of mermaid-js. Multiline directives, however, will pose an issue and will render an error. This is unavoidable. -### Wrapping -# Wrap - -| Parameter | Description |Type | Required | Values| -| --- | --- | --- | --- | --- | -| wrap | a callable text-wrap function| Directive| Optional | %%{wrap}%%| diff --git a/docs/liveEditorOptions.png b/docs/liveEditorOptions.png deleted file mode 100644 index a1cb24ace..000000000 Binary files a/docs/liveEditorOptions.png and /dev/null differ diff --git a/docs/n00b-syntaxReference.md b/docs/n00b-syntaxReference.md index d0b006ae6..e5976658c 100644 --- a/docs/n00b-syntaxReference.md +++ b/docs/n00b-syntaxReference.md @@ -5,9 +5,9 @@ Video Tutorials can be found at the bottom of the Overview Section. This section is a list of diagram types supported by mermaid. Below is a list of links to articles that explain the syntax of the diagrams or charts that can be called. -They also detail how diagrams can be defined, or described in the manner with which the diagram is to be rendered by the renderer. +They also detail how diagrams can be defined, or described in the manner with which the diagram is to be rendered by Mermaid. -### The benefits of text based diagramming are its speed and modifiability. mermaid allows for easy maintenance and modification of diagrams. This means your diagrams will always be up to date and closely follow your code and improve your documentation. +### The benefits of text based diagramming are its speed and modifiability. Mermaid allows for easy maintenance and modification of diagrams. This means your diagrams will always be up to date and closely follow your code and improve your documentation. ## mermaid tag These Diagram Definitions can be entered within a \
tag. @@ -20,7 +20,19 @@ like so : B-->D(fa:fa-spinner);
``` -## mermaid Live Editor -These definitions can also be entered into the [mermaid live editor](https://mermaid-js.github.io/mermaid-live-editor), to render them immediately. -This would then offer +## Mermaid Live Editor +You can proofread your definitions in real-time with the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor), additionally, you can also render and download them immediately using the Live Editor. + +This would then offer you the following choices to download the diagram: + +![Flowchart](./img/DownloadChoices.png) + +**Note:** Copying the markdown will allow you to link to your unique diagram from anywhere online. + +## Directives: +[Directives](./directives.md) gives a diagram author the capability to alter the appearance of a diagram before rendering, by changing some of the applied configurations and can alter the font style, color and other aesthetic aspects of the diagram. + +## Theme Creation: +Mermaid allows [Customized Themes](./theming.md) for websites and even individual diagrams.This is done using directives and can be very helpful, not only for styling but for simplifying more complex diagrams. + diff --git a/docs/theming.md b/docs/theming.md index f0dbf13c2..1b7cc87a5 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -98,7 +98,7 @@ The easiest way to make a custom theme is to start with the base theme, and just ``` -**Notes: +**Notes:** Leaving it empty will set all variable values to default. ## Color and Color Calculation: