From 40ad6546bc8839dad65b35ddf5814f504e25506a Mon Sep 17 00:00:00 2001
From: Benjamin Neff <benjamin@coding4coffee.ch>
Date: Mon, 4 Sep 2017 03:51:04 +0200
Subject: [PATCH] Add documentation for the diaspora:// URI scheme

---
 docs/_includes/federation_tree.html |  3 ++-
 docs/federation/diaspora_scheme.md  | 32 +++++++++++++++++++++++++++++
 docs/federation/types.md            |  4 +++-
 3 files changed, 37 insertions(+), 2 deletions(-)
 create mode 100644 docs/federation/diaspora_scheme.md

diff --git a/docs/_includes/federation_tree.html b/docs/_includes/federation_tree.html
index 989a659..88bfa62 100644
--- a/docs/_includes/federation_tree.html
+++ b/docs/_includes/federation_tree.html
@@ -1,9 +1,10 @@
 <ul class="{{ include.ulclasses | default: "nav nav-pills nav-stacked" }}">
   <li class="{% include active_class.html url="/federation/types.html" %}"><a href="{{ site.baseurl }}/federation/types.html">Value Types</a></li>
   <li class="{% include active_class.html url="/federation/magicsig.html" %}"><a href="{{ site.baseurl }}/federation/magicsig.html">Magic Signatures</a></li>
+  <li class="{% include active_class.html url="/federation/xml_serialization.html" %}"><a href="{{ site.baseurl }}/federation/xml_serialization.html">XML Serialization</a></li>
   <li class="{% include active_class.html url="/federation/encryption.html" %}"><a href="{{ site.baseurl }}/federation/encryption.html">Encryption</a></li>
   <li class="{% include active_class.html url="/federation/routes.html" %}"><a href="{{ site.baseurl }}/federation/routes.html">Routes</a></li>
   <li class="{% include active_class.html url="/federation/fetching.html" %}"><a href="{{ site.baseurl }}/federation/fetching.html">Fetching</a></li>
-  <li class="{% include active_class.html url="/federation/xml_serialization.html" %}"><a href="{{ site.baseurl }}/federation/xml_serialization.html">XML Serialization</a></li>
+  <li class="{% include active_class.html url="/federation/diaspora_scheme.html" %}"><a href="{{ site.baseurl }}/federation/diaspora_scheme.html">diaspora:// URI scheme</a></li>
   <li class="{% include active_class.html url="/federation/relayable.html" %}"><a href="{{ site.baseurl }}/federation/relayable.html">Relayable</a></li>
 </ul>
diff --git a/docs/federation/diaspora_scheme.md b/docs/federation/diaspora_scheme.md
new file mode 100644
index 0000000..86a945c
--- /dev/null
+++ b/docs/federation/diaspora_scheme.md
@@ -0,0 +1,32 @@
+---
+title: diaspora:// URI scheme
+---
+
+## Server and software independent links
+
+A `diaspora://` URL is used if a user wants to link to another post. It doesn't
+contain a server hostname so it is independent of the senders server. And it
+isn't software specific, it is thought to be compatible with every software
+that is compatible with the protocol, so the receiving software can display
+it as software specific URL. 
+
+The format is similar to the route used for [fetching][fetching], so if the
+receiving server doesn't know the linked entity yet, it can just be fetched.
+
+### Format
+
+`diaspora://:type/:guid`
+
+#### Parameters
+
+| Name   | Description                                    |
+| ------ | ---------------------------------------------- |
+| `type` | The type of the linked entity in `snake_case`. |
+| `guid` | The [GUID][guid] of the linked entity.         |
+
+#### Example
+
+`diaspora://post/17faf230675101350d995254001bd39e`
+
+[fetching]: {{ site.baseurl }}/federation/fetching.html
+[guid]: {{ site.baseurl }}/federation/types.html#guid
diff --git a/docs/federation/types.md b/docs/federation/types.md
index 4d1dcd5..eba527d 100644
--- a/docs/federation/types.md
+++ b/docs/federation/types.md
@@ -55,7 +55,9 @@ Example: `12.3456`
 
 Text formatted with markdown using the [CommonMark spec][commonmark].
 
-Example: `Some *Text* with **markdown**.`
+It can also contain [diaspora:// URLs][diaspora_scheme].
+
+Example: `Some *Text* with **markdown** and a [link](diaspora://post/298962a0b8dc0133e40d406c8f31e210).`
 
 ## URL