expanding README. Handle edge case of input index files

phlogisticfugu · Aug 6, 2015 · fbc579a · fbc579a
1 parent a9b9240
commit fbc579a
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,59 @@ gulp-indexify
 
 Master: [![Build Status](https://secure.travis-ci.org/phlogisticfugu/gulp-indexify.png?branch=master)](https://travis-ci.org/phlogisticfugu/gulp-indexify)
 
-Rename static HTML files from about.html to about/index.html so that when served
-up via a webserver, your URLs can look like http://site.com/about/ instead of http://site.com/about.html
-This permits cleaner URL semantics, and reduces dependency on server-side implementation.
+*gulp-indexify* makes [Clean URLs](https://en.wikipedia.org/wiki/Semantic_URL) by leveraging standard directory indexes.
+
+convert any of:
+- `http://site.com/about.html`
+- `http://site.com/about.php`
+- `http://site.com/about.aspx`
+
+into:
+> `http://site.com/about/``
+
+by actually creating
+- `http://site.com/about/index.html`
+
+and relying upon the standard directory index of most web servers.  This makes
+ it simpler to change server-side technologies in the future and is better for
+ SEO.
+
+example usage:
+```javascript
+var gulp = require('gulp');
+var indexify = require('gulp-indexify');
+
+gulp
+.task('indexify', function() {
+  return gulp.src(['src/**/*.html'])
+  .pipe(indexify())
+  .pipe(gulp.dest('dest'))
+  ;
+})
+```
+
+Options
+-------
+
+Options can be passed to *gulp-indexify*:
+```javascript
+// ... code snippet from example
+  return gulp.src(['src/**/*.html'])
+  .pipe(indexify({
+    fileExtension: '.php',
+    rewriteRelativeUrls: true
+  }))
+  .pipe(gulp.dest('dest'))
+  ;
+// ... code snippet from example
+```
+
+- __fileExtension__ - accepts a string or array representing the file
+ extension(s) searched for when renaming files.  All other files without
+ matching file extensions are ignored.  When the value is an array, it must be
+ an array of strings.  Note that the dot must be included.  Default: `.html`
+
+- __rewriteRelativeUrls__ - Since we are moving the HTML pages down a level in
+ the path, relative URLs in the HTML will need to be rewritten.  When this
+ option is set to true that rewriting is done by `gulp-indexify`.  Default: `true`
 
diff --git a/index.js b/index.js
@@ -46,6 +46,13 @@ module.exports = function(options) {
       return callback(null, file);
     }
 
+    if ('index' === parsedPathObj.name) {
+      /*
+       * Skip/pass-through files which are already index files
+       */
+      return callback(null, file);
+    }
+
     file.path = path.join(
       parsedPathObj.dirname,
       parsedPathObj.name,

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gulp-indexify",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Robustly convert static html files into a form served without file extensions",
   "main": "index.js",
   "scripts": {

diff --git a/test/fixtures/index.html b/test/fixtures/index.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Home</title>
+
+  <link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" rel="stylesheet">
+
+  <link rel="stylesheet" href="css/style.css">
+</head>
+<body>
+  <h1>Hello World</h1>
+
+  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+  <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
+</body>
+</html>
diff --git a/test/test.spec.js b/test/test.spec.js
@@ -65,6 +65,24 @@ describe('gulp-indexify', function() {
       .on('end',done)
       ;
     });
+
+    it('should not rename index.html', function(done) {
+      gulp.src([
+        path.join(fixturesDir, 'index.html'),
+        path.join(fixturesDir, 'about.html')
+      ])
+      .pipe(indexify({}))
+      .pipe(assert.nth(1, function(file) {
+        path.dirname(file.path).should.endWith('fixtures');
+        path.basename(file.path).should.equal('index.html');
+      }))
+      .pipe(assert.nth(2, function(file) {
+        path.dirname(file.path).should.endWith('about');
+        path.basename(file.path).should.equal('index.html');
+      }))
+      .on('end',done)
+      ;
+    });
   });
 
   describe('fileExtension option', function() {