@@ -0,0 +1,135 @@
1+---
2+next: true
3+sort: 5
4+title: Tree
5+---
6+
7+# Tree
8+
9+Tree is a simple publishing platform for files that live on your Urbit. You're probably reading this file using Tree right now. The main driving use-case for Tree has been for us to host our own documentation and the surrounding discussion. Tree remains a pretty simple and flexible tool for getting content online. We think it's pretty great.
10+
11+In spirit Tree is sort of like a combination of Jekyll and Finder: a simple static publishing tool and the basic UI for browsing the filesystem. We take it one step further and make it possible to write modules (tiny little apps), like Talk and Dojo, that can be run directly inside of Tree.
12+
13+In the browser Tree is a [React](https://facebook.github.io/react/) / [Flux](https://facebook.github.io/react/blog/2014/05/06/flux.html) app that uses a slightly modifed version of [Bootstrap](http://getbootstrap.com/). On your Urbit Tree is a set of renderers that translate data in `%clay`, our filesystem, into JSON / JSX that can be read by the client.
14+
15+Your Urbit comes with a pre-built copy of the tree (as a single `.js` file). If you're interested in helping to develop tree or learning about how it works, it has its own GitHub repo [here](https://github.com/urbit/tree). We have our own fork of Bootstrap, which lives [here](https://github.com/urbit/bootstrap).
16+
17+You don't need to know anything about the tree implementation to use it, so we'll start with that and get further into the technical details as we get down the page.
18+
19+## Publishing files
20+
21+Assuming you have an Urbit desk mounted (if not see the [Filesystem Handbook](/walkthroughs/clay)), try opeing up `/web/static.md` in an editor and `http://localhost:8080/static` side by side.
22+
23+It should be pretty obvious what's going on here. Drop a markdown file anywhere in `/web` and we'll do the rest.
24+
25+### Simple blog
26+
27+From unix
28+
29+### Going further
30+
31+The best example of more complicated usage of Tree is covered by the Urbit docs themselves. See anything while perusing the docs that you'd like to use yourself? The docs are all on GitHub [here](https://github.com/urbit/docs).
32+
33+## YAML
34+
35+We use [YAML](http://yaml.org/)-style frontmatter to do odds and ends like override the title. A YAML block looks something like this:
36+
37+```
38+---
39+next: true
40+sort: 5
41+title: Tree
42+---
43+```
44+
45+and appears at the top of a file. YAML values can't contain newlines but can contain spaces. Here are the fields we support:
46+
47+### `title`
48+
49+String. Example: `title: Tree manual`.
50+
51+This sets the title in the nav or in lists as distinct from the filename.
52+
53+### `next`
54+
55+Boolean. Example: `next: true`
56+
57+Adds a 'next' link at the bottom of the page that links to the next item as decided by the sort order.
58+
59+### `sort`
60+
61+Integer. Example: `sort: 7`
62+
63+User-defined sort. Indicates the sort order as distinct from alphabetical sort. These numbers should not be overlapping.
64+
65+### `hide`
66+
67+Boolean. Example: `hide: true`
68+
69+Whether or not to hide the item from the tree.
70+
71+### `date`
72+
73+Urbit date. Example: `~2016.2.22`
74+
75+Used for sorting posts by date.
76+
77+## Using components
78+
79+Tree is built using React with a small library of components that you can add to your pages using [JSX](https://facebook.github.io/jsx/) tags.
80+
81+If you don't know anything about JSX that's okay: basically we just give you a few custom HTML tags that you can use to create components on the page.
82+
83+For those familiar with React / Flux each JSX tag corresponds to a component in [the source](https://github.com/urbit/tree/tree/master/js/components).
84+
85+### <list>
86+
87+Example: `<list dataPath="/posts" titlesOnly="true"></list>`
88+
89+Creates a list of children at a path. Defaults to the current path.
90+
91+Optional properties:
92+
93+- `dataPath`: Path to load kids from.
94+- `titlesOnly`: Only show the 'title' which is either the filename or the first h1.
95+- `sortBy`: Can be `date` if items have a `date` YAML.
96+- `className`: Class to be assigned to the container.
97+
98+### <kids>
99+
100+Example: `<kids dataPath="/posts"></kids>`
101+
102+Includes all the children at the specified path separated by `<hr>` tags.
103+
104+Optional properties:
105+
106+- `dataPath`: Path to load kids from.
107+- `className`: Class to be assigned to the container.
108+
109+### <toc>
110+
111+Example: `<toc noHeader="true"></toc>`
112+
113+Creates a table of contents from the `h1` - `h6` tags on the page.
114+
115+Optional properties:
116+
117+- `match`: Tag name to match. If you wanted to only match `h2` tags it could be `match="h2"`
118+- `noHeader`: By default we add a 'Table of Contents' header to the top. Remove it with `noHeader="true"`.
119+
120+## Module basics
121+
122+A module is a
123+
124+## Implementation
125+
126+
127+
128+### Async component
129+
130+### manx JSON format
131+
132+## `urb.js`
133+
134+
135+