From 12c63ff007919c553958a47bf1de972c5734ba20 Mon Sep 17 00:00:00 2001 From: ashishj Date: Thu, 31 Mar 2022 19:37:36 +0200 Subject: [PATCH] Finalizing GitGraph with directives, theming & docs --- cypress/platform/gitgraph.html | 46 ++--- docs/gitgraph.md | 263 ++++++++++++++++++++++++- src/diagrams/git/gitGraphAst.js | 8 + src/diagrams/git/gitGraphRenderer.js | 8 +- src/diagrams/git/parser/gitGraph.jison | 50 ++++- src/diagrams/git/styles.js | 2 +- src/mermaidAPI.js | 2 +- src/themes/theme-default.js | 2 +- 8 files changed, 345 insertions(+), 36 deletions(-) diff --git a/cypress/platform/gitgraph.html b/cypress/platform/gitgraph.html index 8453c97b8..89689d86e 100644 --- a/cypress/platform/gitgraph.html +++ b/cypress/platform/gitgraph.html @@ -26,8 +26,9 @@

info below

-
- gitGraph: +
+ %%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%% + gitGraph commit "Ashish" branch newbranch checkout newbranch @@ -43,33 +44,32 @@
- gitGraph: - commit + gitGraph + commit type:HIGHLIGHT branch hotfix checkout hotfix - commit + commit type:HIGHLIGHT branch develop checkout develop - commit id:"ash" tag:"abc" + commit id:"ash" tag:"abc" type:HIGHLIGHT branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix - commit type:NORMAL + commit type:HIGHLIGHT checkout develop commit type:REVERSE checkout featureB - commit + commit type:HIGHLIGHT checkout main merge hotfix checkout featureB - commit + commit type:HIGHLIGHT checkout develop branch featureA - commit + commit type:HIGHLIGHT checkout develop - merge hotfix checkout featureA commit checkout featureB @@ -78,7 +78,7 @@ merge featureA branch release checkout release - commit + commit type:HIGHLIGHT checkout main commit checkout release @@ -101,18 +101,18 @@ // console.error('Mermaid error: ', err); }; mermaid.initialize({ - theme: 'base', - themeVariables: { - primaryColor: '#9400D3', - darkMode: true, - // background: '#222', - textColor: 'white', - primaryTextColor: '#f4f4f4', + theme: 'dark', + // themeVariables: { + // primaryColor: '#9400D3', + // darkMode: true, + // background: '#222', + // // textColor: 'white', + // // primaryTextColor: '#f4f4f4', - // nodeBkg: '#ff0000', - // mainBkg: '#0000ff', - // tertiaryColor: '#ffffcc', - }, + // // // nodeBkg: '#ff0000', + // // // mainBkg: '#0000ff', + // // // tertiaryColor: '#ffffcc', + // }, // theme: 'forest', // theme: 'neutral', // theme: 'dark', diff --git a/docs/gitgraph.md b/docs/gitgraph.md index 5ffb0a6d0..fabdf52bc 100644 --- a/docs/gitgraph.md +++ b/docs/gitgraph.md @@ -81,8 +81,11 @@ Let us see how these different commit type look with the help of the following d ```mermaid-example gitGraph commit id: "Normal" + commit commit id: "Reverse" type: REVERSE + commit commit id: "Hightlight" type: HIGHLIGHT + commit ``` In this example, we have specified different types to each commit. Also, see how we have clubbed both `id` and `type` together at the time of declaring our commits. @@ -96,12 +99,16 @@ Let us see how this works with the help of the following diagram: ```mermaid-example gitGraph + commit commit id: "Normal" tag: "v1.0.0" + commit commit id: "Reverse" type: REVERSE tag: "RC_1" + commit commit id: "Hightlight" type: HIGHLIGHT tag: "8.8.4" + commit ``` -In this example, we have given custom tags to the commits. Also, see how we have combined all thress attributes in a single commit declaration. You can mix-match these attributes as you like. +In this example, we have given custom tags to the commits. Also, see how we have combined all these attributes in a single commit declaration. You can mix-match these attributes as you like. ### Create a new branch In Mermaid, in-order to create a new branch, you make use of the `branch` keyword. You also need to provide a name of the new branch. The name has to be unique and cannot be that of an existing branch. Usage example: `branch develop` @@ -174,3 +181,257 @@ Then we created the `develop` branch, and all three commits afterwards are put o After this we made use of the `checkout` keyword to set the current branch as `main`, and all commit that follow are registered against the current branch, i.e. `main`. After this we merge the `develop` branch onto the current branch `main`, resulting in a merge commit. Since the current branch at this point is still `main`, the last two commits are registered against that. + + +## Themes +Mermaid supports a bunch of pre-defined themes which you can use to find the right one for you. PS: you can actually override an existing theme's variable to get your own custom theme going. Learn more about themeing your diagram [here](./theming.md). + +Following are the different pre-defined theme options: +- `base` +- `forest` +- `dark` +- `default` +- `neutral` + +**NOTE**: To change theme you can either use the `initialize` call or *directives*. Learn more about [directives](./directives.md) +Let's put them to use, add see how our sample diagram looks like in different themes: + +### Base Theme + +```mermaid-example +%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% + gitGraph + commit + branch hotfix + checkout hotfix + commit + branch develop + checkout develop + commit id:"ash" tag:"abc" + branch featureB + checkout featureB + commit type:HIGHLIGHT + checkout main + checkout hotfix + commit type:NORMAL + checkout develop + commit type:REVERSE + checkout featureB + commit + checkout main + merge hotfix + checkout featureB + commit + checkout develop + branch featureA + commit + checkout develop + merge hotfix + checkout featureA + commit + checkout featureB + commit + checkout develop + merge featureA + branch release + checkout release + commit + checkout main + commit + checkout release + merge main + checkout develop + merge release + ``` + + ### Forest Theme + +```mermaid-example +%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%% + gitGraph + commit + branch hotfix + checkout hotfix + commit + branch develop + checkout develop + commit id:"ash" tag:"abc" + branch featureB + checkout featureB + commit type:HIGHLIGHT + checkout main + checkout hotfix + commit type:NORMAL + checkout develop + commit type:REVERSE + checkout featureB + commit + checkout main + merge hotfix + checkout featureB + commit + checkout develop + branch featureA + commit + checkout develop + merge hotfix + checkout featureA + commit + checkout featureB + commit + checkout develop + merge featureA + branch release + checkout release + commit + checkout main + commit + checkout release + merge main + checkout develop + merge release + ``` +### Default Theme + +```mermaid-example +%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%% + gitGraph + commit type:HIGHLIGHT + branch hotfix + checkout hotfix + commit + branch develop + checkout develop + commit id:"ash" tag:"abc" + branch featureB + checkout featureB + commit type:HIGHLIGHT + checkout main + checkout hotfix + commit type:NORMAL + checkout develop + commit type:REVERSE + checkout featureB + commit + checkout main + merge hotfix + checkout featureB + commit + checkout develop + branch featureA + commit + checkout develop + merge hotfix + checkout featureA + commit + checkout featureB + commit + checkout develop + merge featureA + branch release + checkout release + commit + checkout main + commit + checkout release + merge main + checkout develop + merge release + ``` +### Dark Theme + +```mermaid-example +%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%% + gitGraph + commit + branch hotfix + checkout hotfix + commit + branch develop + checkout develop + commit id:"ash" tag:"abc" + branch featureB + checkout featureB + commit type:HIGHLIGHT + checkout main + checkout hotfix + commit type:NORMAL + checkout develop + commit type:REVERSE + checkout featureB + commit + checkout main + merge hotfix + checkout featureB + commit + checkout develop + branch featureA + commit + checkout develop + merge hotfix + checkout featureA + commit + checkout featureB + commit + checkout develop + merge featureA + branch release + checkout release + commit + checkout main + commit + checkout release + merge main + checkout develop + merge release + ``` + + ### Neutral Theme + +```mermaid-example +%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%% + gitGraph + commit + branch hotfix + checkout hotfix + commit + branch develop + checkout develop + commit id:"ash" tag:"abc" + branch featureB + checkout featureB + commit type:HIGHLIGHT + checkout main + checkout hotfix + commit type:NORMAL + checkout develop + commit type:REVERSE + checkout featureB + commit + checkout main + merge hotfix + checkout featureB + commit + checkout develop + branch featureA + commit + checkout develop + merge hotfix + checkout featureA + commit + checkout featureB + commit + checkout develop + merge featureA + branch release + checkout release + commit + checkout main + commit + checkout release + merge main + checkout develop + merge release + ``` + + ## Customize using Theme Variables diff --git a/src/diagrams/git/gitGraphAst.js b/src/diagrams/git/gitGraphAst.js index 221685a55..fbaa37be4 100644 --- a/src/diagrams/git/gitGraphAst.js +++ b/src/diagrams/git/gitGraphAst.js @@ -1,5 +1,7 @@ import { log } from '../../logger'; import { random } from '../../utils'; +import mermaidAPI from '../../mermaidAPI'; +import * as configApi from '../../config'; let commits = {}; let head = null; let branches = { main: head }; @@ -11,6 +13,10 @@ function getId() { return random({ length: 7 }); } +export const parseDirective = function (statement, context, type) { + mermaidAPI.parseDirective(this, statement, context, type); +}; + // /** // * @param currentCommit // * @param otherCommit @@ -354,6 +360,8 @@ export const commitType = { }; export default { + parseDirective, + getConfig: () => configApi.getConfig().gitGraph, setDirection, setOptions, getOptions, diff --git a/src/diagrams/git/gitGraphRenderer.js b/src/diagrams/git/gitGraphRenderer.js index 61c3cf782..bf9a29158 100644 --- a/src/diagrams/git/gitGraphRenderer.js +++ b/src/diagrams/git/gitGraphRenderer.js @@ -7,9 +7,11 @@ import gitGraphParser from './parser/gitGraph'; import { log } from '../../logger'; /* eslint-disable */ import { getConfig } from '../../config'; +//import * as configApi from '../../config'; let allCommitsDict = {}; let branchNum; +//let conf = configApi.getConfig(); const commitType = db.commitType; let branchPos = {}; @@ -416,8 +418,8 @@ const drawBranches = (svg, branches) => { */ export const draw = function (txt, id, ver) { clear(); - const config = getConfig().gitGraph; - + const conf = getConfig(); + const config = conf.gitGraph; // try { const parser = gitGraphParser.parser; parser.yy = db; @@ -471,7 +473,7 @@ export const draw = function (txt, id, ver) { const width = svgBounds.width + padding * 2; const height = svgBounds.height + padding * 2; - configureSvgSize(diagram, height, width, config.useMaxWidth); + configureSvgSize(diagram, height, width, conf.useMaxWidth); const vBox = `${svgBounds.x - padding} ${svgBounds.y - padding} ${width} ${height}`; // logger.debug(`viewBox ${vBox}`); diagram.attr('viewBox', vBox); diff --git a/src/diagrams/git/parser/gitGraph.jison b/src/diagrams/git/parser/gitGraph.jison index 0b63dd2ba..d67712d12 100644 --- a/src/diagrams/git/parser/gitGraph.jison +++ b/src/diagrams/git/parser/gitGraph.jison @@ -9,10 +9,19 @@ %x string %x options +%x open_directive +%x type_directive +%x arg_directive +%x close_directive %options case-insensitive -%% +%% +\%\%\{ { this.begin('open_directive'); return 'open_directive'; } +((?:(?!\}\%\%)[^:.])*) { this.begin('type_directive'); return 'type_directive'; } +":" { this.popState(); this.begin('arg_directive'); return ':'; } +\}\%\% { this.popState(); this.popState(); return 'close_directive'; } +((?:(?!\}\%\%).|\n)*) return 'arg_directive'; (\r?\n)+ /*{console.log('New line');return 'NL';}*/ return 'NL'; \s+ /* skip all whitespace */ \#[^\n]* /* skip comments */ @@ -24,7 +33,7 @@ "msg:" return 'COMMIT_MSG'; "NORMAL" return 'NORMAL'; "REVERSE" return 'REVERSE'; -"HIGHLIGHT" return 'HIGHLIGHT'; +"HIGHLIGHT" return 'HIGHLIGHT'; "tag:" return 'COMMIT_TAG'; "branch" return 'BRANCH'; "merge" return 'MERGE'; @@ -52,7 +61,9 @@ %% /* language grammar */ start - : GG document EOF{ return $3; } + : eol start + | directive start + | GG document EOF{ return $3; } | GG ':' document EOF{ return $3; } | GG DIR ':' document EOF {yy.setDirection($2); return $4;} ; @@ -72,7 +83,7 @@ body | body line {$1.push($2); $$=$1;} ; line - : statement {$$ =$1} + : statement eol {$$ =$1} | NL ; @@ -107,7 +118,7 @@ commitStatement | COMMIT COMMIT_TYPE commitType COMMIT_MSG STR {yy.commit($5,'',$3,'')} | COMMIT COMMIT_ID STR COMMIT_MSG STR {yy.commit($5,$3,yy.commitType.NORMAL,'')} | COMMIT COMMIT_MSG STR COMMIT_ID STR {yy.commit($3,$5,yy.commitType.NORMAL,'')} - + | COMMIT COMMIT_MSG STR COMMIT_TYPE commitType COMMIT_TAG STR {yy.commit($3,'',$5,$7)} | COMMIT COMMIT_MSG STR COMMIT_TAG STR COMMIT_TYPE commitType {yy.commit($3,'',$7,$5)} | COMMIT COMMIT_TYPE commitType COMMIT_MSG STR COMMIT_TAG STR {yy.commit($5,'',$3,$7)} @@ -177,7 +188,34 @@ commitType : NORMAL { $$=yy.commitType.NORMAL;} | REVERSE { $$=yy.commitType.REVERSE;} | HIGHLIGHT { $$=yy.commitType.HIGHLIGHT;} - ; + ; + +directive + : openDirective typeDirective closeDirective + | openDirective typeDirective ':' argDirective closeDirective + ; + +openDirective + : open_directive { yy.parseDirective('%%{', 'open_directive'); } + ; + +typeDirective + : type_directive { yy.parseDirective($1, 'type_directive'); } + ; + +argDirective + : arg_directive { $1 = $1.trim().replace(/'/g, '"'); yy.parseDirective($1, 'arg_directive'); } + ; + +closeDirective + : close_directive { yy.parseDirective('}%%', 'close_directive', 'gitGraph'); } + ; + +eol + : NL + | ';' + | EOF + ; // reset_arg // : 'HEAD' reset_parents{$$ = $1+ ":" + $2 } // | ID reset_parents{$$ = $1+ ":" + yy.count; yy.count = 0} diff --git a/src/diagrams/git/styles.js b/src/diagrams/git/styles.js index 7ca18279f..203af8c7d 100644 --- a/src/diagrams/git/styles.js +++ b/src/diagrams/git/styles.js @@ -23,7 +23,7 @@ const getStyles = (options) => .branch { stroke-width: 1; - stroke: black; + stroke: ${options.lineColor}; stroke-dasharray: 2; } .commit-label { font-size: 10px; fill: ${options.commitLabelColor};} diff --git a/src/mermaidAPI.js b/src/mermaidAPI.js index c155ed7b7..2ea8e8105 100644 --- a/src/mermaidAPI.js +++ b/src/mermaidAPI.js @@ -423,7 +423,7 @@ const render = function (id, _txt, cb, container) { try { switch (graphType) { case 'git': - cnf.flowchart.arrowMarkerAbsolute = cnf.arrowMarkerAbsolute; + // cnf.flowchart.arrowMarkerAbsolute = cnf.arrowMarkerAbsolute; //gitGraphRenderer.setConf(cnf.git); gitGraphRenderer.draw(txt, id, false); break; diff --git a/src/themes/theme-default.js b/src/themes/theme-default.js index 9e0d8228a..4e3a1bd03 100644 --- a/src/themes/theme-default.js +++ b/src/themes/theme-default.js @@ -228,7 +228,7 @@ class Theme { this.git6 = darken(this.git6, 25); this.git7 = darken(this.git7, 25); } - this.gitInv0 = invert(this.git0); + this.gitInv0 = darken(invert(this.git0), 25); this.gitInv1 = invert(this.git1); this.gitInv2 = invert(this.git2); this.gitInv3 = invert(this.git3);