githubify

At Venzee, we use this utility to help us write create documentation stored in our GitHub repositories. It enables us to use Markdown libraries currently not supported by GitHub.

At time of writing, the library supports offers conversion of Mermaid to SVG files, which GitHub can render.

Installation

npm i -D @venzee/githubify

Commandline Usage

githubify src dist

• src: the source directory to scan
• dist: the output directory

API

import githubify from '@venzee/githubify'

githubify( src, dist, callback );

• src: the source directory to scan
• dist: the output directory
• callback: NodeJs style callback
  • err: raised if an error occcurs while processing
  • outputPaths: The paths of the files generated by the function

Behaviour

Mermaid

Example 1: SimpleDiagram

src/SimpleDiagram.md

 ```mermaid
  graph TD;
    A-->B;
 ```

dist/SimpleDiagram

githubify will generate an image, replacing the Mermaid code block with a link to that image. By default, githubify will use a UUID for the file.

![alt media/SimpleDiagram/59c6b5e204db4ad6a637dd8791d9c8e2.svg](media/SimpleDiagram/59c6b5e204db4ad6a637dd8791d9c8e2.svg)

Folder structure after parsing SimpleDiagram

├── dist
│   ├── SimpleDiagram.md
│   └── media
│       └── SimpleDiagram
│           └── 59c6b5e204db4ad6a637dd8791d9c8e2.svg
└── src
    └── SimpleDiagram.md

Example 2: NamedDiagram

src/NamedDiagram

 # LastHeaderBeforeDiagramBecomesFilename

 ```mermaid
  graph TD;
    A-->B;
 ```

dist/NamedDiagram

![alt media/NamedDiagram/LastHeaderBeforeDiagramBecomesFilename.svg](media/NamedDiagram/LastHeaderBeforeDiagramBecomesFilename.svg)

Example 3: ManyEmbeddedDiagrams

src/ManyEmbeddedDiagrams

 # Many Embedded Diagrams

 Of course, you can comnine many diagrams with any type of text. Just keep
 in mind that the last title before the digram will be removed in the generated
 output and used as the title of the diagram below.

 # 1stDiagram

 ```mermaid
  graph TD;
    A-->B;
 ```

 Once defined, you can refer to the same diagram again by name, even in the source:

 ![alt A Markdown Image link to the diagram defined above](media/ManyEmbeddedDiagrams/1stDiagram.svg)

 And of course, you can declare anonymous diagrams embedded as well:

 ```mermaid
  graph TD;
    B-->A;
 ```

 For identical diagrams, _githubify_ will generate only 1 image. The diagram below
 is a copy of the diagram above:

 ```mermaid
  graph TD;
    B-->A;
 ```

 And if one of the duplicate instances was named, `githubify` will use that diagram's name.
 The below is an exact copy of _1stDiagram_ above:

 ```mermaid
  graph TD;
    A-->B;
 ```

 Lastly, if you have multiple identical diagrams with different names, multiple
 images will be rendered:

# SameAs1stDiagramButDifferentTitle

 ```mermaid
  graph TD;
    A-->B;
 ```

dist/ManyEmbeddedDiagrams

 # Many Embedded Diagrams

 Of course, you can comnine many diagrams with any type of text. Just keep
 in mind that the last title before the digram will be removed in the generated
 output and used as the title of the diagram below.

 ![alt media/ManyEmbeddedDiagrams/1stDiagram.svg](media/ManyEmbeddedDiagrams/1stDiagram.svg)

 Once defined, you can refer to the same diagram again by name, even in the source:

 ![alt A Markdown Image link to the diagram defined above](media/ManyEmbeddedDiagrams/1stDiagram.svg)

 And of course, you can declare anonymous diagrams embedded as well:

 ![alt media/ManyEmbeddedDiagrams/e94d56a7f2964e11acbb367a1f5d412d.svg](media/ManyEmbeddedDiagrams/e94d56a7f2964e11acbb367a1f5d412d.svg)

 For identical diagrams, _githubify_ will generate only 1 image. The diagram below
 is a copy of the diagram above:

 ![alt media/ManyEmbeddedDiagrams/e94d56a7f2964e11acbb367a1f5d412d.svg](media/ManyEmbeddedDiagrams/e94d56a7f2964e11acbb367a1f5d412d.svg)

 And if one of the duplicate instances was named, it will use that diagram's name.
 The below is an exact copy of _1stDiagram_ above:

 ![alt media/ManyEmbeddedDiagrams/1stDiagram.svg](media/ManyEmbeddedDiagrams/1stDiagram.svg)

 Lastly, if you have multiple identical diagrams with different names, multiple
 images will be rendered:

 ![alt media/ManyEmbeddedDiagrams/SameAs1stDiagramButDifferentTitle.svg](media/ManyEmbeddedDiagrams/SameAs1stDiagramButDifferentTitle.svg)

Folder structure after parsing ManyEmbeddedDiagrams

├── dist
│   ├── ManyEmbeddedDiagrams.md
│   └── media
│       └── ManyEmbeddedDiagrams
│           ├── 1stDiagram.svg
│           ├── e94d56a7f2964e11acbb367a1f5d412d.svg
│           └── SameAs1stDiagramButDifferentTitle.svg
└── src
    └── ManyEmbeddedDiagrams.md