Md2md
Why
Auto generater target markdowns with use of easy template and variable. Good to use with Gatsby or other markdown to html generater.
Recommended For
- Product Documentation Engineer;
- Font-end developers who needs markdown transformer
Features
- Target file auto generate when origin file change;
- Varible, custom fragments and templates are supported;
- Path of origin and target is configurable;
- Files or directories to ignore is configurable;
- Add custom transform rule is supported;
- Easy to use for Non-technical User
5min Quick Start
try Demo Repo directely
Main Concepts
Variable
Defined in Variables.json or on the top of markdown, can be used in markdownfile, fragments and templates.
// variabeFile (doc_from/en/Variables.json)"name":"md2md" // origin docFile (doc_from/en/test.md):---link: https://github.com/talentAN/md2md---### This is varname;### Visit varlink for more details; // turn to target(doc_to/en/test.md)---link: https://github.com/talentAN/md2md---### This is md2md;### Visit https://github.com/talentAN/md2md for more details;
Fragment
Defined in fragments directory. Fragment let you split the markdown into independent, reusable pieces, and think about each piece in isolation. you can use fragment in fragment.
// root variableFile (doc_from/en/Variables.json) "auth": "name":"talentAN" "email":"adam_an02@163.com" // fragment file (doc_from/en/fragments/repo_info.md)RepoName: varnamegithub: vargithubAuth: varauthnameEmail: varauthemail // child variableFile (doc_from/en/md2md/Variables.json) "name":"md2md" "github":"https://github.com/talentAN/md2md" // origin docFile (doc_from/en/md2md/index.md)fragments/repo_infomd ## belows are custom info## !@#$%^&*...... // turn to target (doc_to/en/md2md/index.md)RepoName: md2mdgithub: https://github.com/talentAN/md2mdAuth: talentANEmail: adam_an02@163com## belows are custom info## !@#$%^&*......
Template
Defined in templates directory. Template is used to generate markdown file from json file directely;
// templateFile (doc_from/en/templates/introduce.md)the name is : varname;the keyWords is : varkeyWordsnum of weeklyDownoad : varweeklyDownoad // origin jsonFile (doc_from/en/md2md/introduction.json) "useTemplate":true "path":"templates/introduce.md" "var": "name":"md2md" "keyWords":"markdown" "converter" "easy use" "weeklyDownoad":500 // turn to target (doc_to/en/md2md/introduction.md)the name is : md2md;the keyWords is : "markdown" "converter" "easy use"num of weeklyDownoad : 500
Catalog
├── root_dir│ ├── doc_from│ │ ├── en│ │ ├── zh-CN│ │ │── ...... │ ├── doc_to│ ├── m2m.config.js
- doc_from: where you edit your origin doc files in. it's First-level subdirectory must be language;
- doc_to: the final doc file you need will be here; the level of subdirectory will be same as doc_from. you don't need to edit this directory.
- m2m.config.js : config to set for markdown transfer. use the default is just fine ~
├── en│ ├── fragments│ │ ├── fragment1.md│ │ ├── fragment2.md│ │ ├── ...│ ├── templates│ │ ├── template1.md│ │ ├── template2.md│ │ ├── ...│ ├── Variables.json│ ├── Glossary.json│ ├── [doc directories]│ ├── ...│ ├── [doc files]│ ├── ...
API for F2E Developers
const setDirWatcher setFileWatcher clearWatcher markdownToString templateToString register = ; // watch directory configed in m2m.config.js.const watcher_dir = ; // watch special fileconst watcher_file = ; // clearWatcher; // get transfered markdownFile from markdownconst target_md = ; // get transfered markdownFile from json file use templateconst target_json = ; // register your own rule like var and fragment;/** * key is the mark you use as {{key}} to mark the position in markdown file * fn: (content, path_from)=> target * @param * @param * @return */
FAQ
Q: Why don't let all language use one fragments, one templates folder?
A: We've tried about that. But the gramma of each language might be different, which can lead to the postions of variables to be a total mess. Consider that, we think each language has its own fragments folder and template folder is better.
Forward
Change Log
20200629 v0.5.7
- refactor tabs => support show special tabs by different group
20200604 v0.5.6
- support move other files
20200604 v0.5.5
- Support both Linux and Windows file path
- fix error when watch file
20200601 v0.5.0
- rename Tips.json => Glosssary.json
20200529 v0.4.0
- support tip in markdown
- rename
- fragment => fragments
- template => templates
- variable.json => Variables.json
20200528 v0.3.4
- support config name_dir_from in process.env
// before require md2md, run:processenvname_dir_from = "your name of origin dir";
20200527 v0.3.4
- add bin goover and md2md
20200526 v0.3.1
- support register custom rule
- bugfix
- filter Variables.json
- invalid type when convert template
20200525 v0.2.11
- Add api templateToString
- Support parse variables in markdown file. You should use variables in key-value format.
// origin docFile (doc_from/en/test.md):---name: Tomage: 11---### This is varname his age is varage; // target docFile (doc_from/en/test.md)---name: Tomage: 11---### This is Tom his age is 11;