diff --git a/examples/docs/README.md b/examples/docs/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..8ca78abfaf3c853cdd48f17feb521c1813a9a3c3
--- /dev/null
+++ b/examples/docs/README.md
@@ -0,0 +1,14 @@
+
+
+ # Readme
+
+
+
+## /
+
+* [Definitions](./definitions.schema.md) – `https://example.com/schemas/definitions`
+* [Simple](./simple.schema.md) – `https://example.com/schemas/simple`
+
+## /subdir/
+
+* [Subdir](./subdir/subdir.schema.md) – `https://example.com/schemas/subdir/subdir`
diff --git a/examples/docs/simple.schema.md b/examples/docs/simple.schema.md
new file mode 100644
index 0000000000000000000000000000000000000000..653fd56e641144cea296888691b97e8a1646ee0a
--- /dev/null
+++ b/examples/docs/simple.schema.md
@@ -0,0 +1,23 @@
+
+
+
+  
+# Simple
+
+  
+*  **Type:** object
+
+
+
+
+## Properties
+
+
+###  id  
+*  **Type:** string  
+*  **Format:** uri
+  
+ A unique identifier given to every addressable thing.
+
+
+
diff --git a/examples/docs/subdir/subdir.schema.md b/examples/docs/subdir/subdir.schema.md
new file mode 100644
index 0000000000000000000000000000000000000000..5cb8c1cdef68ec7fbc37591ac6c398bb111d689d
--- /dev/null
+++ b/examples/docs/subdir/subdir.schema.md
@@ -0,0 +1,25 @@
+
+
+
+  
+# Subdir
+
+  
+*  **Type:** object
+  
+A schema in a sub directory
+
+
+
+
+
+
+##  content
+### Properties
+
+###  id  
+*  **Type:** string  
+*  **Format:** uri
+  
+ A unique identifier given to every addressable thing.
+
diff --git a/examples/schemas/simple.schema.json b/examples/schemas/simple.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..0ae521642390f2cdd41554592d71aacb3980f510
--- /dev/null
+++ b/examples/schemas/simple.schema.json
@@ -0,0 +1,24 @@
+{
+    "meta:license": [
+        "Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
+        "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
+        "you may not use this file except in compliance with the License. You may obtain a copy",
+        "of the License at http://www.apache.org/licenses/LICENSE-2.0"
+    ],
+    "$schema": "http://json-schema.org/draft-06/schema#",
+    "$id": "https://example.com/schemas/simple",
+    "title": "Simple",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "#/definitions/id"
+        }
+    ],
+    "properties": {
+      "id": {
+          "type": "string",
+          "format": "uri",
+          "description": "A unique identifier given to every addressable thing."
+      }
+  }
+}
\ No newline at end of file
diff --git a/examples/schemas/subdir/subdir.schema.json b/examples/schemas/subdir/subdir.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..de5d89d62b2e1927b6b57f19659e9de0c5eafcad
--- /dev/null
+++ b/examples/schemas/subdir/subdir.schema.json
@@ -0,0 +1,27 @@
+{
+  "meta:license": [
+    "Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
+    "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
+    "you may not use this file except in compliance with the License. You may obtain a copy",
+    "of the License at http://www.apache.org/licenses/LICENSE-2.0"
+  ],
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$id": "https://example.com/schemas/subdir/subdir",
+  "title": "Subdir",
+  "type": "object",
+  "description": "A schema in a sub directory",
+  "definitions": {
+    "content": {
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri",
+          "description": "A unique identifier given to every addressable thing."
+        }
+      }
+    }
+  },
+  "allOf": [
+    {"$ref": "#/definitions/id"}
+  ]
+}
\ No newline at end of file
diff --git a/lib/markdownWriter.js b/lib/markdownWriter.js
new file mode 100644
index 0000000000000000000000000000000000000000..151b8934e88316bfb8bb79e83fcbffedb09a7509
--- /dev/null
+++ b/lib/markdownWriter.js
@@ -0,0 +1,34 @@
+/**
+ * Copyright 2017 Adobe Systems Incorporated. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+const writeFile = require('./writeFiles');
+var Promise=require('bluebird');
+var path = require('path');
+var _ = require('lodash');
+var ejs = require('ejs');
+const pejs = Promise.promisifyAll(ejs);
+var validUrl = require('valid-url');
+
+const generateMarkdown = function(filename, schema, schemaPath, outDir, dependencyMap) {
+  var ctx = {
+    schema: schema,
+    _: _,
+    validUrl: validUrl,
+    dependencyMap:dependencyMap
+  };
+
+  return pejs.renderFileAsync(path.join(__dirname, '../templates/md/topSchema.ejs'), ctx, { debug: false }).then(str => {
+    //console.log('Writing markdown (promise)');
+    const mdfile = path.basename(filename).slice(0, -5)+ '.md';
+    return writeFile(path.join(path.join(outDir), path.dirname(filename.substr(schemaPath.length))), mdfile, str);
+  }).then(out => {
+    //console.log('markdown written (promise)', out);
+    return out;
+  });
+};
+
+module.exports = generateMarkdown;
diff --git a/lib/readmeWriter.js b/lib/readmeWriter.js
new file mode 100644
index 0000000000000000000000000000000000000000..8079b193c79c65b9727e75eee953e091f187b334
--- /dev/null
+++ b/lib/readmeWriter.js
@@ -0,0 +1,65 @@
+/**
+ * Copyright 2017 Adobe Systems Incorporated. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+const writeFile = require('./writeFiles');
+var Promise=require('bluebird');
+var _ = require('lodash');
+var ejs = require('ejs');
+var path = require('path');
+const pejs = Promise.promisifyAll(ejs);
+var validUrl = require('valid-url');
+
+function relativePath(full, base) {
+  if (full.indexOf(base)===0) {
+    return full.substr(base.length).replace(/\.schema\.json$/, '');
+  } else {
+    return full;
+  }
+}
+
+function directory(full, base) {
+  return relativePath(full, base).replace(/[^\/]+$/, '');
+}
+
+/**
+ * Generates a README.md file from the `schemas` passed in at directory `out`
+ * @param {array[string]} paths - path of generated markdown files
+ * @param {map} schemas - map of resolved schemas
+ * @param {string} out - output directory
+ * @param {string} base - schema base directory
+ */
+const generateReadme = function(paths, schemas, out, base) {
+  const coreinfo = _.values(schemas).map(schema => {
+    return {
+      id: schema.jsonSchema.$id,
+      title: schema.jsonSchema.title,
+      full: schema.filePath,
+      relative: relativePath(schema.filePath, base),
+      dir: directory(schema.filePath, base),
+    };
+  });
+  const ctx = {
+    paths: paths,
+    _: _,
+    validUrl: validUrl,
+    schemas: schemas,
+    core: coreinfo,
+    groups: _.groupBy(coreinfo, key => { return key.dir; })
+  };
+  console.log(ctx);
+
+  return pejs.renderFileAsync(path.join(__dirname, '../templates/md/readme.ejs'), ctx, { debug: false }).then(str => {
+    console.log('Writing README');
+    return writeFile(out, 'README.md', str);
+  }).then(out => {
+    //console.log('markdown written (promise)', out);
+    return out;
+  });
+};
+
+module.exports = generateReadme;
+
diff --git a/lib/schemaWriter.js b/lib/schemaWriter.js
new file mode 100644
index 0000000000000000000000000000000000000000..e768f68b4669311f3cf67ada3fcbb19c53727697
--- /dev/null
+++ b/lib/schemaWriter.js
@@ -0,0 +1,16 @@
+/**
+ * Copyright 2017 Adobe Systems Incorporated. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+const writeFile = require('./writeFiles');
+var path = require('path');
+
+const generateNewSchemaFiles = function(filename, schema, schemaPath, outDir) {
+  return writeFile(path.join(path.join(outDir), path.dirname(filename.substr(schemaPath.length))), path.basename(filename), JSON.stringify(schema, null, 4));
+
+};
+
+module.exports = generateNewSchemaFiles;
diff --git a/templates/md/readme.ejs b/templates/md/readme.ejs
new file mode 100644
index 0000000000000000000000000000000000000000..7fc4096fc80652425faaee790126c889b47c61d9
--- /dev/null
+++ b/templates/md/readme.ejs
@@ -0,0 +1,14 @@
+<% /**
+ * Copyright 2017 Adobe Systems Incorporated. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */ %>
+
+ # Readme
+
+<% for(group in groups) {%>
+
+## <%= group %>
+<% for(let i=0; i<groups[group].length; i++) { %>
+* [<%= groups[group][i].title %>](.<%= groups[group][i].relative %>.schema.md) – `<%= groups[group][i].id %>`<% }} %>