Add documentation on the --cssFile option

[gainerorpainer]

Is your feature request related to a problem? Please describe.

When using the --cssFile option, I find it hard to get a quick sample running and working out. May be the issue with the kinda lackluster mermaid documentation on css in-of-itself. But it took me about an hour to figure out to change even the most basic aspect of the document with the -cssFile option. Finally, I figured that I have to add "!important" tags to my css lines.

Describe the solution you'd like

I guess that the biggest problem for me was to figure out that basically my whole custom css got overwritten by the default style, I guess due to the following line (?):

mermaid-cli/src/index.js

Line 159 in 1ea8f5b

head.appendChild(style)

It would be nice if you add the following to the documentation to spare the users the time it took me to figure this out:

The css style provided by the --cssFile option may be overwritten by the default css style of mermaid. If you find that your custom css style does not work , try to add !important to you css tags like so:

.label-container{
    fill: #ffffff !important;
    stroke: #000000 !important;
}

You could include some examples in your Readme, e.g.

To change the default background color use the body tag:

body {
    background: red !important;
}

Describe alternatives you've considered

I tried to find any references from the official mermaid docs but was either too stupid to find any or they don't exist. I guess other users may find it interesting to use the cli with a custom css files as interesting as me, but so far google did not guide me to satisfying documentation.

Also, it might be good to completely strip the document from any default css in case the --cssFile option is passed. Not sure about this.

Additional context

[ShaneMurphy2]

I also was unable to find any documentation other than the help text. Mermaid itself just links to this GitHub repo for the mermaid-cli section in its docs.

[aloisklink]

Thanks for reporting! I've got a PR open to add some basic docs in #367.

Just as a side-note, there's a themeCSS option in Mermaid that is explicitly designed to override mermaid's CSS.

themeCSS is only applied to #mermaid-<MERMAID_DIAGRAM_ID>, and since in CSS, more specific rules override more generic rules, that's the main reason why you need !important in the --cssFile for your generic .label {} rule to override the #mermaid-<MERMAID_DIAGRAM_ID> .label {} rule.

Unfortunately, it does mean you need to copy your CSS file into a new mermaidConfig.json file like the following, and use mmdc --configFile mermaidConfig.json ...:

{
  "themeCSS": "<YOUR_CSS_HERE>"
}

Maybe there should be a new option like --themeCSSFile to load a CSS file as a mermaid theme (it's been requested by mermaidjs/mermaid.cli#24 (comment) already).