Add documentation for the diaspora:// URI scheme

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>

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

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