shithub: docs.9front.org

ref: c956cb1f154abeaa82e4b187e3ef19a0d3cc7f14
dir: /index.md/

View raw version
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
------------

The document source repository is currently hosted and available
for browsing
[here](https://git.sr.ht/~kvik/docs.9front.org).
Get it locally for reading:

	git/clone https://git.sr.ht/~kvik/docs.9front.org

For reading and writing:

	git/clone ssh://git@git.sr.ht/~kvik/docs.9front.org

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 supported by [sr.ht](https://sr.ht), or by sending a mail
to the 9front@9front.org mailing list, or privately to your favorite
editor.

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 extensions `.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 
[docs.a-b.xyz](http://docs.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
[docs.a-b.xyz](http://docs.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](http://9front.org) zone.