diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ff34d24fd0..4934163b55 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,5 +14,5 @@ Make sure you - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md) - [ ] :computer: have added necessary unit/e2e tests. -- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/development.md#3-update-documentation) is used for all new features. +- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/contribution/code.md#update-documentation) is used for all new features. - [ ] :bookmark: targeted `develop` branch diff --git a/docs/community/development.md b/docs/community/development.md deleted file mode 100644 index c9d8dab979..0000000000 --- a/docs/community/development.md +++ /dev/null @@ -1,96 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/development.md](../../packages/mermaid/src/docs/community/development.md). - -# Contributing to Mermaid - -> The following documentation describes how to work with Mermaid in your host environment. -> There's also a [Docker installation guide](../community/docker-development.md) -> if you prefer to work in a Docker environment. - -So you want to help? That's great! - -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) - -Here are a few things to get you started on the right path. - -## Get the Source Code - -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. - -Then you **clone** a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with. - -[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories). - -[Here is a GitHub document that gives an overview of the process.](https://docs.github.com/en/get-started/quickstart/fork-a-repo) - -## Technical Requirements - -> The following documentation describes how to work with Mermaid in your host environment. -> There's also a [Docker installation guide](../community/docker-development.md) -> if you prefer to work in a Docker environment. - -These are the tools we use for working with the code and documentation: - -- [volta](https://volta.sh/) to manage node versions. -- [Node.js](https://nodejs.org/en/). `volta install node` -- [pnpm](https://pnpm.io/) package manager. `volta install pnpm` -- [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages) - -Follow the setup steps below to install them and start the development. - -## Setup and Launch - -### Switch to project - -Once you have cloned the repository onto your development machine, change into the `mermaid` project folder (the top level directory of the mermaid project repository) - -```bash -cd mermaid -``` - -### Install packages - -Run `npx pnpm install`. You will need `npx` for this because volta doesn't support it yet. - -```bash -npx pnpm install # npx is required for first install -``` - -### Launch - -```bash -npx pnpm run dev -``` - -Now you are ready to make your changes! Edit whichever files in `src` as required. - -Open in your browser, after starting the dev server. -There is a list of demos that can be used to see and test your changes. - -If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy. - -That will be served at . -After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!) - -## Verify Everything is Working - -You can run the `test` script to verify that pnpm is working _and_ that the repository has been cloned correctly: - -```bash -pnpm test -``` - -The `test` script and others are in the top-level `package.json` file. - -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/community/docker-development.md b/docs/community/docker-development.md deleted file mode 100644 index 9df0c8d59c..0000000000 --- a/docs/community/docker-development.md +++ /dev/null @@ -1,109 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/docker-development.md](../../packages/mermaid/src/docs/community/docker-development.md). - -# Contributing to Mermaid via Docker - -> The following documentation describes how to work with Mermaid in a Docker environment. -> There's also a [host installation guide](../community/development.md) -> if you prefer to work without a Docker environment. - -So you want to help? That's great! - -![Image of happy people jumping with excitement](https://media.giphy.com/media/BlVnrxJgTGsUw/giphy.gif) - -Here are a few things to get you started on the right path. - -## Get the Source Code - -In GitHub, you first **fork** a repository when you are going to make changes and submit pull requests. - -Then you **clone** a copy to your local development machine (e.g. where you code) to make a copy with all the files to work with. - -[Fork mermaid](https://github.com/mermaid-js/mermaid/fork) to start contributing to the main project and its documentation, or [search for other repositories](https://github.com/orgs/mermaid-js/repositories). - -[Here is a GitHub document that gives an overview of the process.](https://docs.github.com/en/get-started/quickstart/fork-a-repo) - -## Technical Requirements - -> The following documentation describes how to work with Mermaid in a Docker environment. -> There's also a [host installation guide](../community/development.md) -> if you prefer to work without a Docker environment. - -[Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need. - -Optionally, to run GUI (Cypress) within Docker you will also need an X11 server installed. -You might already have it installed, so check this by running: - -```bash -echo $DISPLAY -``` - -If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one. - -## Setup and Launch - -### Switch to project - -Once you have cloned the repository onto your development machine, change into the `mermaid` project folder (the top level directory of the mermaid project repository) - -```bash -cd mermaid -``` - -### Make `./run` executable - -For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands. - -Ensure `./run` script is executable: - -```bash -chmod +x run -``` - -> **💡 Tip** -> To get detailed help simply type `./run` or `./run help`. -> -> It also has short _Development quick start guide_ embedded. - -### Install packages - -```bash -./run pnpm install # Install packages -``` - -### Launch - -```bash -./run dev -``` - -Now you are ready to make your changes! Edit whichever files in `src` as required. - -Open in your browser, after starting the dev server. -There is a list of demos that can be used to see and test your changes. - -If you need a specific diagram, you can duplicate the `example.html` file in `/demos/dev` and add your own mermaid code to your copy. - -That will be served at . -After making code changes, the dev server will rebuild the mermaid library. You will need to reload the browser page yourself to see the changes. (PRs for auto reload are welcome!) - -## Verify Everything is Working - -```bash -./run pnpm test -``` - -The `test` script and others are in the top-level `package.json` file. - -All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.) - -## Last Words - -Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there. - -[Join our Slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - -![Image of superhero wishing you good luck](https://media.giphy.com/media/l49JHz7kJvl6MCj3G/giphy.gif) diff --git a/docs/config/advanced.md b/docs/config/advanced.md deleted file mode 100644 index 28c0ca7245..0000000000 --- a/docs/config/advanced.md +++ /dev/null @@ -1,30 +0,0 @@ -> **Warning** -> -> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. -> -> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/advanced.md](../../packages/mermaid/src/docs/config/advanced.md). - -# Advanced mermaid (Coming soon..) - -## splitting mermaid code from html - -A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so: - -```html -... - - - -``` - -The actual mermaid file could for example look like this: - -```javascript -mermaid content ... -``` - -## mermaid configuration options - -```markdown -(coming soon) -``` diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts index a1e7b05f83..ca5e49a1b5 100644 --- a/packages/mermaid/src/docs/.vitepress/config.ts +++ b/packages/mermaid/src/docs/.vitepress/config.ts @@ -98,7 +98,7 @@ function nav() { { text: 'Changelog', link: 'https://github.com/mermaid-js/mermaid/releases', - } + }, ], }, { diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md index f055e13198..8bce7c2e9e 100644 --- a/packages/mermaid/src/docs/community/contributing.md +++ b/packages/mermaid/src/docs/community/contributing.md @@ -1,10 +1,7 @@ - --- - # Old Contributing Guide Please read in detail about how to contribute documentation and code on the [Mermaid documentation site.](https://mermaid-js.github.io/mermaid/#/development) - --- # Mermaid contribution cheat-sheet diff --git a/packages/mermaid/src/docs/community/documentation.md b/packages/mermaid/src/docs/community/documentation.md index 3b57976359..bd5acad120 100644 --- a/packages/mermaid/src/docs/community/documentation.md +++ b/packages/mermaid/src/docs/community/documentation.md @@ -14,7 +14,6 @@ It is located in the [`packages/mermaid/src/docs`](https://github.com/mermaid-js The contents of [mermaid.js.org](https://mermaid.js.org/) are based on the docs from the `master` branch. Updates committed to the `master` branch are reflected in the [Mermaid Docs](https://mermaid.js.org/) once published. - ```mermaid flowchart LR classDef default fill:#fff,color:black,stroke:black @@ -33,6 +32,7 @@ Start development server for the documentation site ```bash pnpm --filter mermaid run docs:dev ``` + or ``` diff --git a/packages/mermaid/src/docs/community/intro.md b/packages/mermaid/src/docs/community/intro.md index 3783e678b5..7ff1ced1e5 100644 --- a/packages/mermaid/src/docs/community/intro.md +++ b/packages/mermaid/src/docs/community/intro.md @@ -41,7 +41,6 @@ Detailed information about contributing can be found in the [contribution guide] - You could work on a new feature! [These](https://github.com/knsv/mermaid/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Area%3A+Development%22+label%3A%22Help+wanted%21%22+label%3A%22Type%3A+Enhancement%22+label%3A%22Status%3A+Approved%22) are some ideas! - [Join our slack community if you want closer contact!](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) - ## Last Words Don't get daunted if it is hard in the beginning. We have a great community with only encouraging words. So, if you get stuck, ask for help and hints in the Slack forum. If you want to show off something good, show it off there.