1 files changed, 45 insertions, 0 deletions
diff --git a/autoload/tools/doc.asciidoc b/autoload/tools/doc.asciidoc
new file mode 100644
index 0000000..bb2e262
--- /dev/null
+++ b/autoload/tools/doc.asciidoc
@@ -0,0 +1,45 @@
+= Kakoune's online documentation
+
+This is Kakoune's online documentation system.
+
+To see what documentation topics are available, type `:doc` and look at the
+completion menu.  To view a particular topic, type its name or select it
+from the completion menu.  Then hit Enter.
+
+Documentation will be displayed in the client named in the `docsclient` option.
+
+== Using the documentation browser
+
+Documentation buffers are like any other buffer, so you can scroll through
+them as normal, search within a topic with `/`, etc.  However, they can also
+contain links: <<doc#demonstration-target,like this>>.  Links can be followed
+by moving the cursor onto them and pressing Enter.  If a link takes you to
+a different documentation topic, you can return to the original by using the
+`:buffer` command.
+
+== Writing documentation
+
+Documentation must be in AsciiDoc format, with the extension `.asciidoc`.
+It must be stored somewhere within <<doc#sources,the documentation search
+path>>.  Kakoune's built-in documentation renderer does not necessarily
+support every feature, so don't go overboard with formatting.
+
+To create a link to another documentation topic, the URL should be the topic's
+name, just like `:doc` uses.  Because topics are identified only by their
+basename, you should take care that your topic's name does not conflict with
+any of the names used either by other plugins or by Kakoune's standard library.
+
+== Sources
+
+The `:doc` command searches within the following locations for
+documents in the AsciiDoc format (`*.asciidoc`):
+
+* The user plugin directory, `"%val{config}/autoload"`
+* The system documentation directory, `"%val{runtime}/doc"`
+* The system plugin directory, `"%val{runtime}/rc"`
+
+It searches recursively, and follows symlinks.
+
+== Demonstration target
+
+Well done! You can <<doc#using-the-documentation-browser,go back now>>!