Skip to content

Latest commit

 

History

History
313 lines (235 loc) · 7.97 KB

README.md

File metadata and controls

313 lines (235 loc) · 7.97 KB
Raw

Md2md Weekly downloads Yearly downloads

Why

Auto generater target markdowns with use of easy template and variable. Good to use with Gatsby or other markdown to html generater. Demo

Recommended For

  • Product Documentation Engineer;
  • Front-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 {{var.name}};
### Visit {{var.link}} 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: {{var.name}}
github: {{var.github}}
Auth: {{var.auth.name}}
Email: {{var.auth.email}}

// 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_info.md}}

## belows are custom info
## !@#$%^&*()......

// turn to target (doc_to/en/md2md/index.md)
RepoName: md2md
github: https://github.com/talentAN/md2md
Auth: talentAN
Email: adam_an02@163.com
]
## 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 : {{var.name}};
the keyWords is : {{var.keyWords}}
num of weeklyDownoad : {{var.weeklyDownoad}}

// 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

Tab

Defined in normal markdown file, turn to special HTML element later;

// tabFile1 (doc_from/en/tabs/tab1.md)
---
label: centOS
order: 0
group: system
--- 
label: tab处理后展示的文字
order: tab展示顺序
group: tab分组，　如果没有分组会展示当前文件同级目录下所有tab，　如果有分组，只展示当前文件同级目录下相同分组的tab

{{tab}}

// tabFile1 (doc_from/en/tabs/tab2.md)
---
label: ubuntu
order: 1
group: system
--- 

{{tab}}

// turn to target (doc_to/en/tabs/tab1.md)
label: tab处理后展示的文字
order: tab展示顺序
group: tab分组，　如果没有分组会展示当前文件同级目录下所有tab，　如果有分组，只展示当前文件同级目录下相同分组的tab

<div class="tab-wrapper"><a href="/doc_to/en/tabs/tab1.md" class='active'>centOS</a><a href="/doc_to/en/test-tab/ubuntu.md" >ubuntu</a></div>

// turn to target (doc_to/en/tabs/tab2.md)
<div class="tab-wrapper"><a href="/doc_to/en/tabs/tab1.md">centOS</a><a href="/doc_to/en/test-tab/ubuntu.md" class='active' >ubuntu</a></div>

Glossary

Defined in normal markdown file, turn to special HTML element later;

// tabFile1 (doc_from/en/test-glossary.md)
this is normal markdownfile. {{milvus::glossary.milvus.introduce}}

// turn to target (doc_to/en/test-glossary.md)
this is normal markdownfile. <span class="tip" data-tip="Milvus is easy-to-use, highly reliable, scalable, robust, and blazing fast.">milvus</span>

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,
} = require("md2md");

// watch directory configed in m2m.config.js.
const watcher_dir = setDirWatcher();

// watch special file
const watcher_file = setFileWatcher(absolute_path);

// clearWatcher
clearWatcher(watcher_file);

// get transfered markdownFile from markdown
const target_md = markdownToString(path_from);

// get transfered markdownFile from json file use template
const target_json = templateToString(path_from);

// register your own rule like var and fragment
register(key, fn);
/**
 * key is the mark you use as {{key}} to mark the position in markdown file
 * fn: (content, path_from)=> target
 * @param {String} content: the content converted by default rules
 * @param {String}  path_from: the absolute path of original file, offen used to get variables and fragments
 * @return {string} target: the final content converted by custom rules
 */

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:
process.env.name_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: Tom
age: 11
---
### This is {{var.name}}, his age is {{var.age}};

// target docFile (doc_from/en/test.md)
---
name: Tom
age: 11
---
### This is Tom, his age is 11;