3.8 KiB
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 if you prefer to work without a Docker environment.
So you want to help? That's great!
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 to start contributing to the main project and its documentation, or search for other repositories.
Here is a GitHub document that gives an overview of the process.
Technical Requirements
The following documentation describes how to work with Mermaid in a Docker environment. There's also a host installation guide if you prefer to work without a Docker environment.
Install Docker. 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:
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)
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:
chmod +x run
To get detailed help simply type `./run` or `./run help`.
It also has short _Development quick start guide_ embedded.
Install packages
./run pnpm install # Install packages
Launch
./run dev
Now you are ready to make your changes! Edit whichever files in src as required.
Open http://localhost:9000 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 http://localhost:9000/dev/your-file-name.html. 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
./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!
