{"id":29512199,"url":"https://github.com/mastersign/mdgraphextract","last_synced_at":"2026-05-15T18:04:35.384Z","repository":{"id":19843494,"uuid":"23105272","full_name":"mastersign/mdgraphextract","owner":"mastersign","description":"Extracts a graph from a Markdown file.","archived":false,"fork":false,"pushed_at":"2024-06-16T21:41:32.000Z","size":228,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-09T16:04:28.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mastersign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-19T09:57:27.000Z","updated_at":"2024-12-30T22:21:51.000Z","dependencies_parsed_at":"2023-01-13T20:37:36.803Z","dependency_job_id":null,"html_url":"https://github.com/mastersign/mdgraphextract","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/mastersign/mdgraphextract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdgraphextract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdgraphextract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdgraphextract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdgraphextract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mastersign","download_url":"https://codeload.github.com/mastersign/mdgraphextract/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdgraphextract/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265382339,"owners_count":23756340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-16T12:01:20.792Z","updated_at":"2026-05-15T18:04:35.343Z","avatar_url":"https://github.com/mastersign.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MdGraphExtract\n\n[![npm package][npm-img]][npm-url]\n[![dependency status][libraries-img]][libraries-url]\n[![build status][travis-img]][travis-url]\n\n\u003e extracting a graph in [DOT] format from a [Markdown] file\n\n_MdGraphExtract_ can be used as a [Gulp] plugin.\n\n## Modes\n\n_MdGraphExtract_ has two operational modes: Autograph mode and DotExtract mode.\n\n### Autograph Mode `auto`\n\nExtracts nodes and edges from headlines and internal links.\n\nExample [Markdown] document:\n\n~~~ Markdown\n# First Chapter\nText with an internal link to [Section 1.1] and [Section 1.2].\n\n## Section 1.1\nThis section references [Second Chapter][].\n\n## Section 1.2\nThis section stands for its own.\n\n# Second Chapter\nAnd here is a link to [the first chapter][First Chapter].\n~~~\n\nResulting [DOT] file:\n\n~~~ DOT\ndigraph G {\n    \"First Chapter\" [URL=\"#first-chapter\"];\n    \"First Chapter\" -\u003e \"Section 1.1\";\n    \"First Chapter\" -\u003e \"Section 1.2\";\n    \"Section 1.1\" [URL=\"#section-1.1\"];\n    \"Section 1.1\" -\u003e \"Second Chapter\";\n    \"Section 1.2\" [URL=\"#section-1.2\"];\n    \"Second Chapter\" [URL=\"#second-chapter\"];\n    \"Second Chapter\" -\u003e \"First Chapter\";\n}\n~~~\n\nRendered with `dot` from [GraphViz]:\n\n![](examples/autograph-example.png)\n\n### DotExtract Mode `dotex`\n\nExtracts [DOT] commands from HTML-comments under consideration of the last headline.\n\nExample [Markdown] document:\n\n~~~ Markdown\n\u003c!--\n@graph MyGraph: bgcolor=azure\n@graph-attributes rankdir=TB\n@node-attributes fontname=Helvetica\n@node-attributes shape=rect style=\"filled, rounded\" fillcolor=#A0D0FF\n@edge-attributes color=#2040C0\n@node-type important: fillcolor=#FFD0A0\n@edge-type weak: style=dashed\n--\u003e\n\n# First Chapter\n\u003c!-- @node --\u003e\n\u003c!-- @edge -\u003e Section 1.1 \u003cweak\u003e --\u003e\n\u003c!-- @edge -\u003e Section 1.2 \u003cweak\u003e --\u003e\nText paragraph is weakly linked with Section 1.1 and 1.2.\n\n## Section 1.1\n\u003c!-- @node \u003cimportant\u003e: label=\"Sect. (1.1)\" --\u003e\n\u003c!-- @edge -\u003e Second Chapter --\u003e\nThis section is linked to the Second Chapter.\n\n## Section 1.2\n\u003c!-- @node label=\"Sect. (1.2)\" --\u003e\nThis section stands for its own.\n\n\u003c!-- @node Second Chapter: label=\"Chapter 2\" --\u003e\n\u003c!-- @edge Second Chapter -\u003e First Chapter --\u003e\n# Second Chapter\nAnd the last chapter is linked with the first chapter.\n~~~\n\nResulting [DOT] file:\n\n~~~ DOT\ndigraph \"MyGraph\" {\n    bgcolor=azure;\n    rankdir=TB;\n    node [fontname=Helvetica];\n    node [fillcolor=\"#A0D0FF\" shape=rect style=\"filled, rounded\"];\n    edge [color=\"#2040C0\"];\n    \"First Chapter\" [URL=\"#first-chapter\"];\n    \"Section 1.1\" [fillcolor=\"#FFD0A0\" label=\"Sect. (1.1)\" URL=\"#section-1.1\"];\n    \"Section 1.2\" [label=\"Sect. (1.2)\" URL=\"#section-1.2\"];\n    \"Second Chapter\" [label=\"Chapter 2\"];\n    \"First Chapter\" -\u003e \"Section 1.1\" [style=dashed];\n    \"First Chapter\" -\u003e \"Section 1.2\" [style=dashed];\n    \"Section 1.1\" -\u003e \"Second Chapter\";\n    \"Second Chapter\" -\u003e \"First Chapter\";\n}\n~~~\n\nRendered with `dot` from [GraphViz]:\n\n![](examples/dotex-example.png)\n\nIt is possible to tag [DOT] commands with one or more group tags to build subsets of commands.\nDuring the extraction process one or more groups can be selected to build a graph\nwith the specified subset of [DOT] commands.\nCommands without a group tag are always selected.\n\nA [DOT] command is taged by adding a hash character followed by a group name\nwithout spaces after the command name.\n\nDuring the extraction, the command group(s) are specified with the option `group`.\n\nIf an edge is selected by the group(s), the two referenced nodes are\nselected too, despite thier group tags.\n\nExample Markdown document:\n\n~~~ Markdown\n# H1\n\u003c!-- @n --\u003e\nThe node of this chapter is not tagged.\n\n# H2\nThe node of this chapter is taged with group `A` and group `B`.\n\u003c!-- @n #A #B --\u003e\nThe edge to *H1* is taged with group `A`.\n\u003c!-- @e #A -\u003e H1 --\u003e\n\n# H3\nThe node of this chapter is taged with group `B`.\n\u003c!-- @n #B --\u003e\nThe edge from *H1* to *H3* is taged with group `B`.\n\u003c!-- @e #B H1 -\u003e H3 --\u003e\n~~~\n\nResulting [DOT] file without a specified group:\n\n~~~ DOT\ndigraph G {\n    \"H1\" [URL=\"#h1\"];\n}\n~~~\n\nResulting [DOT] file with group specified as `\"A\"`:\n\n~~~ DOT\ndigraph G {\n    \"H1\" [URL=\"#h1\"];\n    \"H2\" [URL=\"#h2\"];\n    \"H2\" -\u003e \"H1\";\n}\n~~~\n\nIn the context of one HTML comment, the group tags can be pre-defined\nfor all following commands with the command `tags` or `t`, respectively.\nEvery command will be treated as it would have its own explicit group tags\n_and_ the pre-defined group tags.\nThe pre-defined group tags can be resettet with a `tags` or `t` command\nwithout any group tags.\nThey are automatically resetted if the HTML comment block ends.\n\nExample Markdown document:\n\n~~~ Markdown\n\u003c!--\n@t #A\n@n X\n@n Y\n@e X -\u003e Y\n@t #B\n@n Z\n@e Y -\u003e Z\n--\u003e\n~~~\n\nResulting [DOT] file with group specified as `\"A\"`:\n\n~~~ DOT\ndigraph G {\n    \"X\";\n    \"Y\";\n    \"X\" -\u003e \"Y\";\n}\n~~~\n\nResulting [DOT] file with group specified as `\"B\"`:\n\n~~~ DOT\ndigraph G {\n    \"Y\";\n    \"Z\";\n    \"Y\" -\u003e \"Z\";\n}\n~~~\n\n## Interface\n\nYou can use _MdGraphExtract_ in any *Node.JS* project, but it has additional support for *Gulp*.\n\n### Usage with Gulp\n\n~~~ js\nvar gulp = require('gulp');\nvar spawn = require('gulp-spawn');\nvar mdgraphextract = require('mdgraphextract');\n\ngulp.task('autograph', function() {\n\t// grab all Markdown files in the docs folder\n\treturn gulp.src('docs/*.md')\n\t\t// pipe them to MdGraphExtract in Autograph mode, passing options\n\t\t.pipe(mdgraphextract({ mode: 'auto' }))\n\t\t// write the resulting *.gv files to the docs folder\n\t\t.pipe(gulp.dest('docs/'))\n\t\t// use `dot` from GraphViz to render the graphs into PNG files\n\t\t.pipe(spawn({\n\t\t\tcmd: 'dot',\n\t\t\targs: ['-Tpng'],\n\t\t\tfilename: function(base, ext) { return base + '.png'; }\n\t\t}))\n\t\t// write the PNG files to the docs folder\n\t\t.pipe(gulp.dest('docs/'));\n});\n~~~\n\n### Usage as a function\n\nAdditional to the main function, which processes *Vinyl* files and is usable in *Gulp* files, there is a simple asynchronous `extract()` function.\n\n`extract(data[, opt], cb)`\n\nMini-Example with the `extract()` function:\n\n~~~ js\nvar fs = require('fs');\nvar mdgraphextract = require('mdgraphextract');\n\nvar buffer = fs.readFileSync('test.md');\nmdgraphextract.extract(buffer, \n    { encoding: 'utf8', mode: 'dotex' },\n    function(result) {\n        fs.writeFileSync('test.gv', result, { encoding: 'utf8' });\n    });\n~~~\n\nThe `extract()` function can take a string, a buffer, or a stream as input. The second argument with the options is optional. The encoding is `utf8` by default. The graph extraction mode is `auto` by default.\n\n### Usage as a readable stream\n\nAt last _MdGraphExtract_ provides the pseudo-class `ExtractingStream`.\n\n`new ExtractingStream(input[, opt])`\n\nMini-Example with the `ExtractingStream` pseudo-class:\n\n~~~ js\nvar fs = require('fs');\nvar ExtractingStream = require('mdgraphextract').ExtractingStream;\n\nvar s = new ExtractingStream(fs.createReadStream('test.md', 'utf8'));\ns.pipe(fs.createWriteStream('test.gv', 'utf8'));\n~~~\n\nThe `ExtractingStream` pseudo-class is constructed with a `Readable` stream as input. The second argument with the options is optional.\n\n### Options\n\nThe following options are available:\n\n* The `mode` attribute controlles the operational mode of the graph extraction. It can have `\"auto\"` or `\"dotex\"` as value.\n* The `encoding` attribute specifying the input encoding, in case the input is binary.\n* The `group` attribute is recognized, if the `mode` is set to `\"dotex\"`, and specifies the command group(s) to consider. Either a string or an array of strings.\n* The `autographLevel` attribute is recognized, if the `mode` is set to `\"auto\"`, and specifies the headline level(s) to use as the link context.\n* The `autographLevelStrict` attribute is recognized, if the `mode` is set to `\"auto\"`, and specifies, if edges are included, which point outside the selected level(s).\n* The `autographIsolatedNodes` attribute is recognized, if the `mode` is set to `\"auto\"`, and specifies, if nodes are included, which are not used by edges.\n* The `autographImplicitNodes` attribute is recognized, if the `mode` is set to `\"auto\"`, and specifies, if edges are included, which point to not existing nodes.\n* The `noAutoRefs` attribute controlles the automatic generation of URL attributes for nodes from the auto-identifier of the related headline. If it set to `true`, no URL attributes will be auto-generated from the headlines.\n* The `refPrefix` can be set to a string, which will be prefixing any auto-generated URL attribute.\n\nThese are the default values for all options:\n\n~~~ js\n{\n    \"mode\": \"auto\",\n    \"encoding\": \"utf8\",\n    \"group\": null,\n    \"autographLevel\": null,\n    \"strictAutographLevel\": false,\n    \"autographIsolatedNodes\": false,\n    \"autographImplicitNodes\": false,\n    \"noAutoRefs\": false,\n    \"refPrefix\": \"\"\n}\n~~~\n\n## License\n\n_MdGraphExtract_ is published under the MIT license.\n\n[npm-url]: https://www.npmjs.com/package/mdgraphextract\n[npm-img]: https://img.shields.io/npm/v/mdgraphextract.svg\n[libraries-url]: https://libraries.io/npm/mdgraphextract\n[libraries-img]: https://img.shields.io/librariesio/github/mastersign/mdgraphextract.svg\n[travis-img]: https://img.shields.io/travis/mastersign/mdgraphextract/master.svg\n[travis-url]: https://travis-ci.org/mastersign/mdgraphextract\n[Gulp]: http://gulpjs.com\n[Markdown]: https://daringfireball.net/projects/markdown/\n[GraphViz]: http://www.graphviz.org\n[DOT]: https://graphviz.gitlab.io/_pages/doc/info/lang.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastersign%2Fmdgraphextract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastersign%2Fmdgraphextract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastersign%2Fmdgraphextract/lists"}