static-rewrite

static-rewrite

Easily generate destination paths or static URLs by mapping user-friendly patterns to server-side build paths.

Install

Install with npm:

$ npm install --save static-rewrite

What does this do?

This module does something similar to URL rewriting, but for static paths at build-time. The goal is consistently and easily generate correct destination paths during development, regardless of the source paths.

Examples

Let's say we have a blog, and we want to:

• automatically write blog posts to the root of our site
• use the slugified title from front-matter as the folder name (for "pretty" permalinks)
• append /index.html to the path (also for "pretty" permalinks)

In other words, we want this source path:

src/content/posts/2017-02-14.md

To be written to a destination path that looks something like:

blog/how-to-create-effective-permalinks/index.html

You can either manually parse and reformat your destination paths, or use this library with simple rewrite rules.

Example rewrite rule

The following rule(s) will match any files in the posts directory, and rewrite the path using the given structure.

rewriter.rule(/posts\//, 'blog/:slugify(title)/index.html');
// add extra validation if necessary
rewriter.rule(/posts\//, 'blog/:slugify(title)/index.html', function(file) {
  return file.extname === '.md';
});

URL rewriting

URL rewriting is used for replacing semantic, user-friendly URLs with server-friendly URLs.

For example, when a user enters a URL like the following to go to a page on wikipedia:

https://en.wikipedia.org/wiki/Business

The URL might be rewritten by wikipedia to something like:

https://en.wikipedia.org/w/index.php?title=Business

Usage

Add this library to your JavaScript application with the following line of code:

var Rewriter = require('static-rewrite');

API

Rewriter

Create an instance of Rewriter with the given options.

Params

• options {Object}

Example

var rewriter = new Rewriter()
  .rule(/posts/, 'blog/:stem/index.html')
  .rule(/docs/, 'docs/:stem/index.html')

console.log(rewriter.rewrite({path: 'content/posts/first-post.md'}));
//=> 'blog/first-post/index.html'

console.log(rewriter.rewrite({path: 'content/posts/other-post.md'}));
//=> 'blog/other-post/index.html'

console.log(rewriter.rewrite({path: 'content/docs/api.md'}));
//=> 'docs/api/index.html'

.rule

Register a rewrite rule with a regex to use for matching paths, a structure to use for the replacement patter, and an optional validation fn to supplement the regex when matching.

Params

• regex {RegExp}
• structure {String}
• fn {Function}: Optionally pass a function to do further validation on the file (return false if the rule shouldn't be used) and/or to update the context to be used for resolving placeholders in the rule structure.
• returns {Object}: Returns the Rewriter instance for chaining.

Example

rewriter.rule(':folder/([^\\/]+)/(.*)', ':dirname/:foo/:stem.html');
rewriter.rule(/([^\\/]+)\/*\.hbs$/, ':dirname/:foo/:stem.html');
rewriter.rule(/\.hbs$/, ':dirname/:stem.html');
rewriter.rule(/\.md$/, 'blog/:stem/index.html', function(file) {
  return file.dirname !== 'foo/bar';
});

.rewrite

Run rewrite rules on the given file. If a rule matches the file, the file.path will be rewritten using locals, and values from the file and file.data.

Params

• file {Object}
• locals {Object}
• returns {String}: Returns the formatted path or the original file.path if no rewrite rules match the file.

.match

Calls RegExp.exec() on file.path, using the regex from the given rewrite rule. If the file matches, the match arguments are returned, otherwise null.

Params

• rule {Object}
• file {Object}
• returns {Boolean}

Example

var fileA = new File({path: 'blog/drafts/about.hbs'});
var fileB = new File({path: 'blog/content/about.hbs'});

var ruleA = new rewriter.Rule(/blog\//, ':stem/index.html');
var ruleB = new rewriter.Rule(/blog\//, ':stem/index.html', function(file) {
  return !/drafts/.test(file.path);
});

console.log(rewriter.match(ruleA, fileA)); //<= true
console.log(rewriter.match(ruleB, fileA)); //<= false

console.log(rewriter.match(ruleA, fileB)); //<= true
console.log(rewriter.match(ruleB, fileB)); //<= true

Rule

Create a new Rule with the given pattern, structure and optional function for validating or adding data to the context

Params

• pattern {String}
• structure {String}
• fn {Function}

Example

var rule = new Rule(/posts/, 'blog/:stem/index.html');
var rule = new Rule(/posts/, 'blog/:stem/index.html', function(file) {
  return file.extname !== '.foo';
});
var rule = new Rule(/posts/, 'blog/:stem/index.html', function(file, params) {
  file.data = Object.assign({}, file.data, params);
});

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. MIT

This file was generated by verb-generate-readme, v0.4.2, on February 18, 2017.