Merge pull request #25 from contentful-labs/feature/23-add-meta-data

feat: Add file meta documentation
contentful · Sep 7, 2016 · 3d8a461 · 3d8a461
2 parents 5a4b692 + d2645ab
commit 3d8a461
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -8,6 +8,10 @@ A Metalsmith' plugin to generate files using content from [Contentful](http://ww
 
 This plugin for [metalsmith](http://www.metalsmith.io) allows you to build a static site using the data stored at [Contentful](http://www.contentful.com). It is built on top of the [Contentful JavaScript Client](https://github.com/contentful/contentful.js).
 
+## Example
+
+To get an idea on how this works, you can check out an [example blog site](https://github.com/contentful-labs/contentful-metalsmith-example) which is completely generated using contentful-metalsmith.
+
 ## Getting started
 
 ### Install

diff --git a/docs/file-meta.md b/docs/file-meta.md
@@ -0,0 +1,49 @@
+# File meta
+
+Contentful-metalsmith enriches the data available in templating with useful metadata.
+
+## `_fileName`
+
+**Which files:** all
+
+Every by contentful-metalsmith rendered file includes this meta information.
+This can be convenient when linking to child pages.
+
+```html
+<!doctype html>
+<html lang="en">
+<head></head>
+<body>
+  <ul>
+    <!-- available data fetched from contentful -->
+    {{#each data.entries }}
+      <li>
+        <h2>{{fields.title}}</h2>
+        <p>{{fields.description}}</p>
+        <!-- convenience property _fileName for easy linking -->
+        <p><a href="{{_fileName}}">Read more</a></p>
+      </li>
+    {{/each}}
+    </ul>
+    {{contents}}
+</body>
+</html>
+```
+
+## _parentFileName
+
+**Which files:** entry pages of a collection
+
+When rendering a collection page for a given content type and also rendering every entry of this content type the child page for each entry will include this parent file information.
+For further information check the [entry_template option](https://github.com/contentful-labs/contentful-metalsmith/blob/master/docs/source-file-settings.md#entry_template-optional).
+
+```html
+<!doctype html>
+<html lang="en">
+<head></head>
+<body>
+  <main class="l-container">
+    <a href="/{{ _parentFileName }}">Go back</a>
+  </main>
+</body>
+</html>
diff --git a/docs/source-file-settings.md b/docs/source-file-settings.md
@@ -292,4 +292,8 @@ contentful:
 layout: posts.html
 ---
 POSTS-CONTENT-DIFFERENT-SPACE
-```
+```
+
+## File meta available in template
+
+Contentful-metalsmith adds some [handy meta information](./file-meta.md) to the data available in data to make the generation of sites even easier.