# @venzee/githubify

> Convert Markdown files to Github compatible ones. Currently supports Mermaid-Diagram-to-SVG conversion

Latest version **1.2.0** (published 2019-12-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @venzee/githubify
pnpm add @venzee/githubify
yarn add @venzee/githubify
bun add @venzee/githubify
```

Provides the command `githubify`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2019-12-18 |
| First published | 2018-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 50.5 KB |
| Known vulnerabilities | 0 (+9 in 2 direct dependencies) |
| Install scripts | no |
| Author | Venzee, Inc. |
| Maintainers | gartox, menshawi, noisygerman |
| Keywords | diagram, markdown, flowchart, sequence diagram, gantt, class diagram, git graph, github markdown, mermaid, mermaidjs |

## Links

- npm: https://www.npmjs.com/package/@venzee/githubify
- Repository: https://github.com/venzee/dev-documentation
- Homepage: https://github.com/venzee/githubify#readme
- Issues: https://github.com/venzee/githubify/issues
- npm.io page: https://npm.io/package/@venzee/githubify

## Dependencies (10)

- [glob](https://npm.io/package/glob.md) ^7.1.6
- [uuid](https://npm.io/package/uuid.md) ^3.3.3
- [async](https://npm.io/package/async.md) ^3.1.0
- [yargs](https://npm.io/package/yargs.md) ^14.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [mermaid](https://npm.io/package/mermaid.md) ^8.4.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^8.1.0
- [mermaid.cli](https://npm.io/package/mermaid.cli.md) ^0.5.1
- [node-run-cmd](https://npm.io/package/node-run-cmd.md) ^1.0.1
- [object-streaming-tools](https://npm.io/package/object-streaming-tools.md) ^1.3.2

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2019-12-18
- 1.1.2 — 2019-11-15
- 1.1.1 — 2018-03-15
- 1.1.0 — 2018-03-14
- 1.0.1 — 2018-03-02
- 1.0.0 — 2018-03-02

## README

# githubify

At [Venzee](https://www.venzee.com]), 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](https://mermaidjs.github.io/) to SVG files, which GitHub can render.

## Installation

```bash
npm i -D @venzee/githubify
```

## Commandline Usage

```bash
githubify src dist
```

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

## API

```javascript
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](https://mermaidjs.github.io/)

#### Example 1: SimpleDiagram

#### src/SimpleDiagram.md

````markdown
 ```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.

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

#### Folder structure after parsing SimpleDiagram

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

#### Example 2: NamedDiagram

#### src/NamedDiagram

````markdown

 # LastHeaderBeforeDiagramBecomesFilename

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

#### dist/NamedDiagram

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

#### Example 3: ManyEmbeddedDiagrams

#### src/ManyEmbeddedDiagrams

````markdown
 # 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

````markdown
 # 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

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

---
_Source: https://npm.io/package/@venzee/githubify · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._