Merge pull request #5 from iamstarkov/docs/cli

Readme-driven development.

README.md

@@ -7,56 +7,62 @@
 
 > [Mdast][mdast] plugin for [Textr][textr] — modular tool to [make your typography better][typewriter-habits].
 
-This plugin will help you to transform only _text_ nodes from your markdown using any functions that get text, transform it and return result of processing. For example, check out [typographic-*][tfs] functions. All of those functions are being composed using [Textr][textr].
+Process your markdown with [Textr][textr] plugins, **skipping code**.
+
+* [Install](#install)
+* [Usage](#usage)
+* [API](#api)
+* [CLI](#cli)
 
 [typewriter-habits]: http://practicaltypography.com/typewriter-habits.html
-[tfs]: https://github.com/denysdovhan/mdast-typographer/blob/master/package.json#L53-L65
 [textr]: https://github.com/shuvalov-anton/textr
 
 ## Install
 
-Install **mdast-textr** using [npm][npm]:
-
-    npm install --save mdast-typographer
-
-[npm]: https://docs.npmjs.com/cli/install
+    npm install --save mdast-textr
 
 ## Usage
 
-You can use it as a plugin for [mdast][mdast]:
-
 ```js
 import mdast from 'mdast';
 import mdastTextr from 'mdast-textr';
-import base from 'typographic-base';
-
-mdast
-  .use(mdastTextr, {
-    plugins: [ base ],
-    options: { locale: 'en-us' }
-  })
-  .process(`Hello -> "world"`); // Hello → “world”
+
+// textr plugin — just function to replace triple dots to ellipses
+const ellipses = input => input.replace(/\.{3}/gim, '…');
+
+const text = `
+## spread operator...
+
+    function(...args) { return args; }
+`.trim();
+
+mdast.use(mdastTextr, { plugins: [ ellipses ] }).process(text);/*
+## spread operator…
+
+    function(...args) { return args; } */
 ```
 
 ## API
 
-### [mdast][mdast].[use][use](mdastTextr[, mdastOptions])
-
-Transforms only text nodes defined in `options.plugins`.
+### mdast.use(mdastTextr[, mdastOptions])
 
 #### mdastOptions
 
 Type: `Object`  
 Default: `{}`
 
-Optionst that will be passed to plugin. Specified by [mdast documentation][mdast-use].
+Contain `plugins` and `options` which are Textr’s options. Check out [Textr usage section][textr-usage].
+
+[textr-usage]: https://github.com/shuvalov-anton/textr#usage
 
 ##### mdastOptions.plugins
 
 Type: `Array`  
 Default: `[]`
 
-Array of functions that will be executed. Besides, you can pass strings of package's names and they will be required.
+Array of [Textr][textr] plugins. They are available on npm, labelled with [textr][textr-plugins] keyword. Also you can easily create new one. Don’t be scared.
+
+[textr-plugins]: https://www.npmjs.com/browse/keyword/textr
 
 ##### mdastOptions.options
 
@@ -65,24 +71,31 @@ Default: `{}`
 
 Any option was set in `options` will be passed into [Textr][textr] as it's options.
 
-For example, you may want to set your [ISO 639][iso] locale code. It's important for right correction, basically for proper primary and secondary quotes.
+For example, you may want to set your [ISO 639][iso] [locale code][locale]. It's important for right correction, basically for proper primary and secondary quotes.
 
 ## CLI
 
-You can easy use this plugin from CLI like so:
+`mdast-textr` as mdast plugin has no CLI itself, so you are gonna use mdast CLI instead. So check the [mdast-cli docs][mdast-cli] first. `mdast` and `mdast-textr` both have to be installed. Also you have to define `textr` plugins as Array of Strings, but you are lucky and `mdast-textr` will require them for you!
+
+[mdast-cli]: https://github.com/wooorm/mdast/#cli
+[t-base]: https://github.com/iamstarkov/typographic-base
+
+### inline
+
+    mdast --use "textr=plugins:['typographic-base']" README.md --output README.md
+
+### config
 
-    mdast --use 'textr=plugins:["typographic-base"]' example.md
+    mdast README.md --output README.md
 
-Also, you have ability to define options using [`.mdastrc` or `package.json`][mdastrc]. An example `.mdastrc` could look like this:
+With this `.mdastrc` config defined:
 
 ```json
 {
   "plugins": {
     "textr": {
-      "plugins": ["typographic-base"],
-      "options": {
-        "locale": "en-us"
-      }
+      "plugins": [ "typographic-base"],
+      "options": { "locale": "en-us" }
     }
   }
 }
@@ -94,6 +107,7 @@ MIT © [Denys Dovhan](http://denysdovhan.com)
 
 [mdast]: http://mdast.js.org/
 [use]: https://github.com/wooorm/mdast#mdastuseplugin-options
+[locale]: https://github.com/shuvalov-anton/textr#locale-option-consistence
 [iso]: http://www.wikiwand.com/en/List_of_ISO_639-1_codes
 
 [mdastrc]: https://github.com/wooorm/mdast/blob/master/doc/mdastrc.5.md

package.json

@@ -52,8 +52,8 @@
     "mocha": "*",
     "npm-run-all": "*",
     "rimraf": "*",
-    "typographic-base": "^1.0.1",
-    "typographic-ellipses": "^1.0.11"
+    "typographic-ellipses": "^1.0.11",
+    "typographic-quotes": "^1.2.1"
   },
   "dependencies": {
     "textr": "^0.3.0",

test.js

@@ -1,46 +1,27 @@
 import { equal } from 'assert';
 import mdast from 'mdast';
 import mdastTextr from './index';
-import base from 'typographic-base';
 
-const t = (text, mdastOptions) =>
-  mdast()
-    .use(mdastTextr, mdastOptions)
-    .process(text)
-    .trim();
+// textr plugin — just function to replace triple dots to ellipses
+const ellipses = input => input.replace(/\.{3}/gim, '…');
 
-describe('mdast-textr', () => {
+const text = `
+## spread operator...
 
-  it('should return original text', () =>
-    equal(t(`Hello, "world"...`), `Hello, "world"...`)
-  );
+    function(...args) { return args; }
+`;
 
-  it('should return transformed text', () =>
-    equal(
-      t(`Hello, "world"...`, {
-        plugins: [ base ]
-      }),
-      `Hello, “world”…`
-    )
-  );
+it('should mdastTextr in node', () =>
+  equal(
+    mdast.use(mdastTextr, { plugins: [ ellipses ] }).process(text),
+`## spread operator…
 
-  it('should require strings', () =>
-    equal(
-      t(`Hello, "world"...`, {
-        plugins: [ 'typographic-ellipses' ]
-      }),
-      `Hello, "world"…`
-    )
-  );
+    function(...args) { return args; }
+`));
 
-  it('should load options', () =>
-    equal(
-      t(`"quotes"`, {
-        plugins: [ base ],
-        options: { locale: 'uk' }
-      }),
-      `«quotes»`
-    )
-  );
-
-});
+it('should mdastTextr in CLI (with options)', () =>
+  equal(mdast.use(mdastTextr, {
+    plugins: [ 'typographic-ellipses', 'typographic-quotes' ],
+    options: { locale: 'ru' }
+  }).process('yo "there" ...\n'), 'yo «there» …\n')
+);