diff --git a/examples/docs/abstract.schema.md b/examples/docs/abstract.schema.md
index d43412ee4aa3a46a74becfb12ed74d1b91f75e34..2433c8b6c277e09873f496b44581fab4ce316af3 100644
--- a/examples/docs/abstract.schema.md
+++ b/examples/docs/abstract.schema.md
@@ -5,4 +5,8 @@ foo: bar
 ---
 
 # Abstract
+```
+https://example.com/schemas/abstract
+```
+This is an abstract schema. It has `definitions`, but does not declare any properties
 ---
\ No newline at end of file
diff --git a/examples/docs/definitions.schema.md b/examples/docs/definitions.schema.md
index 50018180f2e8be28a8737fc3111eefc1d6b2fd86..c942cb04c1349ec741f61735720120304b642125 100644
--- a/examples/docs/definitions.schema.md
+++ b/examples/docs/definitions.schema.md
@@ -5,4 +5,9 @@ foo: bar
 ---
 
 # Definitions
+```
+https://example.com/schemas/definitions
+```
+This is an example of using a `definitions` object within a schema.
+It is imported using `allOf` and `$ref`.
 ---
\ No newline at end of file
diff --git a/examples/docs/example.schema.md b/examples/docs/example.schema.md
index c25446a5e9d593271c6c21b035073ed8fc2e9790..19bb89ff0fc1fcb075747c4e552319b02c669bfc 100644
--- a/examples/docs/example.schema.md
+++ b/examples/docs/example.schema.md
@@ -5,4 +5,8 @@ foo: bar
 ---
 
 # Example
+```
+https://example.com/schemas/example
+```
+This is an example schema with examples. Too many examples? There can never be too many examples!
 ---
\ No newline at end of file
diff --git a/examples/docs/simple.schema.md b/examples/docs/simple.schema.md
index 61036aa10d87548e71579130028313d701dd5ae0..6c8eddb0db7e16840ea8c5127f88455cb6dff4ea 100644
--- a/examples/docs/simple.schema.md
+++ b/examples/docs/simple.schema.md
@@ -5,4 +5,8 @@ foo: bar
 ---
 
 # Simple
+```
+https://example.com/schemas/simple
+```
+This is a *very* simple example of a JSON schema. There is only one property.
 ---
\ No newline at end of file
diff --git a/examples/docs/subdir/subdir.schema.md b/examples/docs/subdir/subdir.schema.md
index 0f2cb03a0de707e6047b3ade1bfac17fe4ce73a1..865b6eb73f08423cfbd1ca520c14301bd4ed2165 100644
--- a/examples/docs/subdir/subdir.schema.md
+++ b/examples/docs/subdir/subdir.schema.md
@@ -5,4 +5,8 @@ foo: bar
 ---
 
 # Subdir
+```
+https://example.com/schemas/subdir/subdir
+```
+A schema in a sub directory
 ---
\ No newline at end of file
diff --git a/lib/markdownWriter.js b/lib/markdownWriter.js
index 5dc91d6571f59213407c759bffdecec7f08d3c07..c98c552647aa049d65c0545c4bfa72dfe84f856f 100644
--- a/lib/markdownWriter.js
+++ b/lib/markdownWriter.js
@@ -44,7 +44,7 @@ const generateMarkdown = function(filename, schema, schemaPath, outDir, dependen
   // one huge template, each block can be built individually
   const multi = [
     [ 'frontmatter.ejs', { meta: schema.metaElements } ],
-    [ 'header.ejs', { title: schema.title } ],
+    [ 'header.ejs', { schema: schema } ],
     //[ 'divider.ejs', null ],
     //[ 'topSchema.ejs', ctx ],
     [ 'divider.ejs', null ]
diff --git a/templates/md/header.ejs b/templates/md/header.ejs
index 837be32de40bf919bb55444259e0e71bfa96227c..a49eeed39baa1fb130f4ebc4d26aaf0125d90c15 100644
--- a/templates/md/header.ejs
+++ b/templates/md/header.ejs
@@ -4,4 +4,9 @@
  * 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
  */ %>
-# <%=title %>
\ No newline at end of file
+# <%=schema.title %>
+```
+<%= schema.$id %>
+```
+
+<%= schema.description %>
\ No newline at end of file