ref: 30fc73fac837164adc95aea6aa85e17bfba3ea86
author: kvik <kvik@a-b.xyz>
date: Tue Jul 28 17:16:16 EDT 2020
Add the first page
--- /dev/null
+++ b/index.md
@@ -1,0 +1,72 @@
+9FRONT DOCUMENTATION PROJECT
+============================
+
+**ACHTUNG!** This is a prototype. Expect everything to change and
+demand change yourself.
+
+This is a repository of documents and notes relating to plan9/front
+theory or use.
+
+Contributing
+------------
+
+Everyone is invited to get write access by asking (kvik) on IRC, grid,
+or kvik@a-b.xyz. Otherwise you may submit patches by usual contribution
+mechanisms on [sr.ht](https://sr.ht), through the 9front@9front.org
+mailing list, or privately to one of the editors.
+
+The contributed documents are mostly expected to be markdown
+files, denoted by a `.md` file extension.
+
+The formatting syntax used by the markdown processor
+[discount](https://github.com/Orc/discount)
+used by the backend is documented in the manual page
+[markdown(6)](http://a-b.xyz/6e/c837).
+
+In addition to markdown files, raw text files and HTML documents may be
+entered into the repository, using the file extension '.txt' and
+'.shtml', respectively. These files will copied verbatim into the
+rendered document tree.
+
+**Note** Only one of `a.md`, `a.txt`, or `a.shtml` may exist in the
+repository at the same time. This failing will prevent rendering of
+the entire tree. This may or may not be fixed in the future.
+
+Reading
+-------
+
+The source content available in the repository, as well as
+HTML pages generated from the markdown sources, are presented
+for reading using 9p and HTTP interfaces at
+[doc.a-b.xyz](http://doc.a-b.xyz).
+
+The updates to the docs repository are periodically pulled by the
+backend, which renders and publishes the updated documents.
+
+TODO: Describe how the backend works in more detail? This would
+be useful to allow people to preview their work locally.
+
+### 9p
+
+The document tree may be mounted from Plan 9 as follows:
+
+ 9fs tcp!doc.a-b.xyz!909 /n/doc
+
+### HTTP
+
+The document tree may be viewed with a web browser at
+[doc.a-b.xyz](http://doc.a-b.xyz)
+
+Index
+-----
+
+Until some form of indexing and autolinking is implemented please
+link to your pages from one of the top-level documents.
+
+Warning
+-------
+
+Again, this is a prototype presented to the community for evaluation,
+development, and bikeshedding. If it does well it would probably be
+best to rehome the git repository to a 9front-based host and move or
+set up redirects from a 9front.org zone.