Add documentation for conrefs

1 files changed, 55 insertions, 0 deletions

diff --git a/docs/conrefs.md b/docs/conrefs.md
new file mode 100644
index 0000000..7844e9c
--- /dev/null
+++ b/docs/conrefs.md
@@ -0,0 +1,55 @@
+# Content References
+
+Content referencing (conref) is a convenient mechanism for reuse of content from other files or books.
+
+### Importing local files
+
+Importing an other file's content is really easy using the `include` tag:
+
+```
+{% include "./test.md" %}
+```
+
+### Importing file from another book
+
+GitBook can also resolve the include path by using git:
+
+```
+{% include "git+https://github.com/GitbookIO/documentation.git/README.md#0.0.1" %}
+```
+
+The format of git url is:
+
+```
+git+https://user@hostname/project/blah.git/file#commit-ish
+```
+
+The real git url part should finish with `.git`, the filename to import is extracted after the `.git` till the fragment of the url.
+
+The `commit-ish` can be any tag, sha, or branch which can be supplied as an argument to `git checkout`. The default is `master`.
+
+### Inheritance
+
+Template inheritance is a way to make it easy to reuse templates. When writing a template, you can define "blocks" that child templates can override. The inheritance chain can be as long as you like.
+
+`block` defines a section on the template and identifies it with a name. Base templates can specify blocks and child templates can override them with new content.
+
+```
+{% extends "./mypage.md" %}
+
+{% block pageContent %}
+# This is my page content
+{% endblock %}
+```
+
+In the file `mypage.md`, you should specify the blocks that can be extent:
+
+```
+{% block pageContent %}
+This is the default content
+{% endblock %}
+
+# License
+
+{% import "./LICENSE" %}
+```