var conf = {
  ...
  plugins: {
    ...
    links: { /* plugin configuration */ }
  }
  ...
}
```

The configuration may look like this

```javascript
{
  validate: {
    // whether to fail if errors are detected
    failOnError: true || false, 

    // a pattern for external files that are to be ignored during link checking
    ignoreTargetPattern: /.*external.*/ || null,
    
    // a pattern for documents to not check for dead links
    ignoreDocumentPattern: /.*summary\.html/
  },
  process: {
    // which headings to process to generate ids for
    headings: [ 'h1', 'h2', 'h3' ],

    // which documents (by meta tag) to include during link generation
    include: [ 'links' ] || 'layouted'

    // which documents (by meta tag) to exclude during link generation
    exclude: [ 'no-link-check' ]
  },
  
  // which log level to use to display output to the user
  logLevel: 'default' || 'performance' || 'debug' || 'none'
}
```


## Usage Details

This gives some details on the functionality provided by the plugin.

### Link Expansion

Lets say you have the document `posts/some-document.md` with `ref:` prefixed links to other documents:

```markdown
---
title: 'Some Document'
---

[Link to other doc](ref:other-document.html)
[Link to introduction](ref:/index.html#section1-introduction)
```

The plugin will make sure that

*   `ref:` prefixed links are expanded to actual document references independant of where `posts/some-document.md` ends up after includes
*   `ref:` links are recorded and checked for validity after built

The resulting html code will look like this:

```html
<a href="other-document.html">Link to other doc</a>
<a href="../index.html#section1-introduction">Link to introduction</a>
```

### Link Expansion in Images

It is possible to expand paths to image urls as well:

```html
<img src="ref:asset:/assets/images/some-image.jpg" />
```

Instead of using `ref:` simply use `ref:asset:` as a prefix to do so. Assuming the document is located under `posts/recent/` the resulting HTML looks like this:

```html
<img src="../../assets/images/some-image.jpg" />
```

### In-page Anchor Generation

Lets say the document `index.html` (linked from `some-document.md`) contains the following code:

```html
---
title: 'Index'
---

<section id="section1">
  <h1>Introduction</h1>
  <p>
    Bla blub.
    <section id="sub1">
      <h2>You did not know this!!$$$</h2>
      <p>
        Special trick.
      </p>
    </section>
  </p>
</section>
```

This plugin will generate in-page anchors for each heading based on its nesting in `<section/>` elements. 

The rules for generation are:

*   concatenate parent section ids and the heading text using dashes
*   slugify the resulting string by
    * removing all non-word characters
    * replacing spaces with dashes
    * lowercasing the result

The resulting HTML code looks like this:

```html
<section id="section1">
  <h1 id="section1-introduction">Introduction</h1>
  <p>
    Bla blub.
    <section id="sub1">
      <h2 id="section1-sub1-you-did-not-know-this">You did not know this!!$$$</h2>
      <p>
        Special trick.
      </p>
    </section>
  </p>
</section>
```

Checkout the [tests](https://github.com/camunda/docpad-plugin-links/tree/master/test/src) for all supported use cases.

### Dead Link Checking

The plugin collects all `ref:` annotated links and validates them against documents and in-page anchors.

If there is a missmatch between referenced and actual defined anchors the plugin will report that as a *dead link*:

```
Dead link in  /posts/mypost.html : /other-post.html ( /other-post.html )
```


## Build the Plugin

```
# install dependencies
npm install
node_modules/.bin/cake test-setup

# create modules
node_modules/.bin/cake dev

# test
node_modules/.bin/cake test
```


## License

[MIT](http://creativecommons.org/licenses/MIT/)