Core

The unified library itself is a small module. It’s a rather small API. Plugins do everything else: minify HTML, lint markdown, check indefinite articles (“a”, “an”), and more.

Three syntaxes are connected to unified, each coming with a syntax tree definition, and a parser and stringifier: mdast with remark for Markdown, nlcst with retext for prose, and hast with rehype for HTML.

unified defers part of its logic to vfile, which is a virtual file format representing documents being processed, and unist, a schema for syntax trees.

Syntaxes

Virtual files

vfile stores metadata about documents being processed (often, but not always, from the file system). Mainly, it houses a path to files, and their contents. Additionally, it tracks messages associated with files and where they occurred. This powers code linting, shown below with remark-cli, remark-validate-links, and remark-preset-lint-consistent.

remark -u preset-lint-consistent -u validate-links example.md
example.md
        1:3  warning  Incorrect list-item indent: add 2 spaces
  1:11-1:18  warning  Emphasis should use `*` as a marker
   3:1-3:10  warning  Found reference to undefined definition

⚠ 3 warnings

Read more about vfile in its readme.

Syntax tree

unist discloses documents as syntax trees. Syntax trees come in two flavours: Concrete (CST) and Abstract (AST). The first has all information needed to restore the original document completely, the latter does not. ASTs can recreate an exact syntactic representation. For example, CSTs house info on style such as tabs or spaces, but ASTs do not. This makes ASTs often easier to work with.

For example, say we have the following HTML element:

<a href="https://github.com/unifiedjs/unified" class="highlight">
  Fork on GitHub
</a>

Yields (in hast, an abstract syntax tree):

{
  "type": "element",
  "tagName": "a",
  "properties": {
    "href": "https://github.com/unifiedjs/unified",
    "className": ["highlight"]
  },
  "children": [
    {"type": "text", "value": "\n  Fork on GitHub\n"}
  ]
}

These trees also come with positional information (not shown above), so every node knows where it originates from.

Read more about unist in its readme.

Built with unified

awesome-lint
readme.md
  ✖    1:1  Missing Awesome badge after the main heading      awesome-badge
  ✖   12:1  Marker style should be -                          unordered-list-marker-style
  ✖  199:3  Remove trailing slash (https://sindresorhus.com)  trailing-slash

3 errors

how-to-markdown

    How To Markdown
    Markdown is awesome!
    ────────────────────
    » HELLO WORLD                    
    » HEADINGS
    » EMPHASIS
    » LISTS
    » LINKS
    » IMAGES
    » BLOCKQUOTES
    » CODE

documentation build ex.js -f md api.md && head -n 10 api.md
# documentation

Generate JavaScript documentation as a list of parsed JSDoc
comments, given a root file as a path.

**Parameters**

-   `indexes` **Array<string> or string** files to process
-   `options` **Object** options
    -   `options.external` **Array<string>** a string regex / glob match pattern

prettyhtml ./**/*.html
index.html written

Guides

var unified = require('unified')
var vfile = require('to-vfile')
var report = require('vfile-reporter')
var markdown = require('remark-parse')
var toc = require('remark-toc')
var remark2retext = require('remark-retext')
var english = require('retext-english')
var indefiniteArticle = require('retext-indefinite-article')
var remark2rehype = require('remark-rehype')
var doc = require('rehype-document')
var html = require('rehype-stringify')

var visit = require('unist-util-visit')
var is = require('unist-util-is')

module.exports = attacher

function attacher() {
  return transformer

  function transformer(tree, file) {
    visit(tree, 'ParagraphNode', visitor)

    function visitor(node) {
      var children = node.children