• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

JeNeSuisPasDave/MarkdownTools: Markdown processing tools, including mdmerge

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

JeNeSuisPasDave/MarkdownTools

开源软件地址(OpenSource Url):

https://github.com/JeNeSuisPasDave/MarkdownTools

开源编程语言(OpenSource Language):

CSS 98.8%

开源软件介绍(OpenSource Introduction):

MarkdownTools

MarkdownTools is a collection of command line utilities for processing Markdown text files. At the moment the collection includes only one utility: mdmerge. Over time additional utilities will be added to support Markdown workflows.

Current stable version is 1.0. See the Installation section below for guidance.

mdmerge

mdmerge is a command line utility that produces a single Markdown document by merging a set of Markdown documents. The merge can be accomplished by expanding include specifications found in the input files, by concatenating a list of files found in an index file, or both.

Synergy with Marked

Brett Terpstra's Marked 2 application is a GUI product that runs on OS X; it watches Markdown text files and displays the formatted output; it has extensive support for multi-file Markdown documents. Marked is my tool of choice for viewing formatted Markdown. I use it whenever I'm creating or reviewing Markdown content on my OS X machine. The invaluable multi-file document support in Marked is what drove me to create mdmerge.

mdmerge brings that same multi-file Markdown document processing to the command line. It is useful in any automated scripting environment where Markdown is processed. For example, I use it in automated build scripts (e.g., using gmake or Grunt) to produce documentation for the software I'm building. It is cross-platform; you can pre-process the Markdown files on any common OS that has a recent version of Python.

Markdown and include file syntax support

mdmerge has been tested with documents containing these Markdown syntax variants:

mdmerge accepts include declarations in these styles

Includes can be nested; that is, a file can include another file that itself include other files, and so on. Index (or book) files are only processed as such when they are the primary input; they cannot be nested -- but the files listed in the index file are treated as normal input files (expanding include specifications found within).

some examples

This example shows an include specification of another markdown file:

This next bit is an included Markdown file. If it also has embedded include specifications, they will be processed as well; these kinds of includes are nested.

<<[section-a.md]

End of example.

This example shows an include specification for source code:

This next bit is included source code. It is not examined for nested include specifications.

<<(example.c)

End of example.

This example shows a normal MultiMarkdown transclusion and a source code transclusion:

This demonstrates MultiMarkdown transclusions:

{{section-a.mmd}}

```C
{{example.c}}
```

End of example.

And of course there are raw file includes (<<{raw.html}) and index files. Read the documentation linked in the previous section or look at docs/specifications.mmd in the master branch.

Installation

Installation packages are available on PyPI. For Python 3 (3.3 or later) install the MarkdownTools; for Python 2 (2.6 or later) install the MarkdownTools2 package.

Install the package using pip, like this (in a Python 3 environment):

$ pip install MarkdownTools

or (in a Python 2 environment):

$ pip install MarkdownTools2

If you are upgrading an existing version, use pip install --upgrade.

You may need to use sudo if you are installing into the system's native Python environment.

Usage

The command line looks like this:

mdmerge [options] [-o outputfile] inputfile [inputFile ...]
mdmerge [options] [-o outputfile] -

Command arguments

options : One or more of --book, --export-target, -h, --help, --ignore-transclusions, --just-raw --leanpub, --version.

--book : Treat STDIN as an index file (a "book" file).

--export-target [html|latex|lyx|opml|rtf|odf] : Indicates the ultimate output target of the markdown processor, but primarily impacts wildcard substitution in Marked inclusion.

-h : Help information

--help : Same as -h.

--ignore-transclusions : Leave any MultiMarkdown transclusion specifications alone; do not include the specified file. Useful if you want to mix Marked/LeanPub includes and MultiMarkdown includes, but have MultiMarkdown handline the transclusions.

--just-raw : Ignore all include specifications except for raw includes; useful for processing the output of the Markdown processor to pick up the raw file include specifications that should have passed through untouched.

--leanpub : Indicates that any input file named book.txt should be treated as a LeanPub index file.

--version : Gives the version information about the utility.

-o outputfile : The filepath in which to store the merged text. If not specified, then STDOUT is used.

--outfile outputfile : same as -o.

- : The input comes from STDIN.

inputfile : A list of space separated input files that can be merged together. If multiple files are given, they are treated as if they were specified in a LeanPub index file.

Development

MarkdownTools are written in Python. The project repository contains python2/* branches that target Python 2 (2.6 and later) and python3/* branches that target Python 3 (3.3 and later). There are unit tests on each branch that can be executed using the runtests command script.

The master branch does not contain any source or tests; it contains the README file and a few other files that describe aspects of the project.

Testing

To run the tests:

$ ./runtests.sh

For Python 2 environments you will need to install the mock package (e.g., pip install mock).

Contributing

Similar to the contribution guidance from https://github.com/github/markup:

  1. Fork it.
  2. Create a branch (git checkout -b my_MarkdownTools)
  3. Commit your changes (git commit -am "Added Snarkdown")
  4. Push to the branch (git push origin my_MarkdownTools)
  5. Open a Pull Request
  6. Enjoy a refreshing beverage and wait

Contributors should read the developer documentation, available in the docs directory of the master branch. To produce a nice pretty HTML version of those docs, install the doc tools (see the docs-support directory) and run the make-docs script in the docs directroy.

License and Copyright

MarkdownTools is licensed with the Mozilla Public License Version 2.0.

Copyright 2014 Dave Hein




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
jtratner/vim-flavored-markdown发布时间:2022-08-18
下一篇:
dariubs/rtlmd: rtl markdown editor发布时间:2022-08-18
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap