npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@zilliz/mdtomd

v1.2.3

Published

## Why

Downloads

145

Readme

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;
  • 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 {{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":"[email protected]"
    }
}

// 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: [email protected]
]
## 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
icon: tab-cpu
---

{{tab}}

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

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

Image Path Solution

write:

image

will transfer to: image

Assets/images/about-1.jpg is where you store your image. And this plugin will help to find path.relative(doc_path,image_path) and replace the target.


## Catalog

```bash
├── 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;