https://github.com/camunda/docpad-plugin-links
Advanced linking plugin for DocPad
https://github.com/camunda/docpad-plugin-links
Last synced: 9 months ago
JSON representation
Advanced linking plugin for DocPad
- Host: GitHub
- URL: https://github.com/camunda/docpad-plugin-links
- Owner: camunda
- License: mit
- Created: 2013-09-26T15:34:34.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2013-12-16T15:52:43.000Z (about 12 years ago)
- Last Synced: 2025-04-06T02:51:12.247Z (9 months ago)
- Language: CoffeeScript
- Size: 135 KB
- Stars: 3
- Watchers: 9
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Links plugin for DocPad
[](https://travis-ci.org/camunda/docpad-plugin-links)
[](http://badge.fury.io/js/docpad-plugin-links)
A markup agnostic [DocPad](http://docpad.org) plug-in for smooth linking in large project documentations.
## Overview
The plug-in hooks into DocPad's page generation process and replaces `ref:` prefixes with relative references to the specified file.
At the same time it stores the references and validates them against existing files in a project.
### Page `/index.html`
```html
Check out this section on the other page.
Or try a broken link.
```
### Page `/b/index.html.md`
```markdown
## my heading
This page may **safely** be linked to.
```
### Console Output
```
~: docpad generate
...
[docpad-plugin-links] processing documents
[docpad-plugin-links] completed in 11708 ms
[docpad-plugin-links] validating links
...
[docpad-plugin-links] dead links detected!
> /index.html : /broken.html ( /broken.html )
[docpad-plugin-links] link validation summary
> total: 3
> found: 2
> ignored: 0
> dead: 1
Error: Found dead links (see log)
...
```
The plugin may optionally fail if invalid document references are used or in-page links are defined twice.
## Use the Plugin
```
npm install --save docpad-plugin-links
```
## Features
* Generate in-page heading links based on heading text and `` nesting
* Expand `ref:/some/link` and `ref:asset:/assets/img.png` in `` and `![]()
` to actual link targets
* Collect and report dead links
## Resources
* [Issue Tracker](https://github.com/camunda/docpad-plugin-links/issues)
## Configuration
The plugin may be configured via a plugin configuration entry in the `docpad.conf.js` file:
```javascript
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
Link to other doc
Link to introduction
```
### Link Expansion in Images
It is possible to expand paths to image urls as well:
```html
![]()
```
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
```
### In-page Anchor Generation
Lets say the document `index.html` (linked from `some-document.md`) contains the following code:
```html
---
title: 'Index'
---
Introduction
Bla blub.
You did not know this!!$$$
Special trick.
```
This plugin will generate in-page anchors for each heading based on its nesting in `` 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
Introduction
Bla blub.
You did not know this!!$$$
Special trick.
```
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/)