+Because we generate the site statically, you'll need to re-run `cms7` each
+time you change something. If your editor likes compile commands that can run
+from any directory, you can also use `cms7 -c /path/to/config.yml`.
+
+
+## Contributing
+
+- Whenever possible, one commit per feature.
+- If feature/pull-request branches have only one developer, please regularly
+ rebase them onto master until they are merged in.
+- Don't merge branches with meaningless commit messages; always squash them
+ instead.
+- Wait for discussion of big changes. Your branches will still be here
+ tomorrow.
+
+Helpful tip for those merging PRs: you can browse the tree a merge would
+result in by navigating to
+`https://github.com/freenode/web-7.0/tree/pull/XYZ/merge`, where `XYZ` is the
+pull request number.
+
+You can also go to `https://freenode.github.io/web-7.0/BRANCHNAME/` to see a
+build of any particular branch. This also works for *internal* pull requests
+(they are named `pull-X`).
+
+## Architecture / Orientation
+
+The site is generated from
+[Markdown](https://daringfireball.net/projects/markdown/) sources and
+[Jinja2](http://jinja.pocoo.org/) templates, found in `content/` and
+`templates/` respectively. The Travis build deploys to GitHub Pages
+automatically on every push.
+
+Various modules convert the sources to a useful output structure. Eventually
+cms7 will document this process, but for now:
+
+- `content/pages/` contains plain pages which are rendered in `out/` using
+ `page.html`.
+- `content/news/` contains blog/news posts which are rendered in `out/news/`
+ using `article.html`.
+- `content/faq/` contains FAQ categories: each directory `content/faq/X/`
+ has the entries for category `X`. These are rendered in `out/faq/answers/`
+ with `faq.html`.
+
+ Indexes of these entries are rendered in `out/faq/` with `faq_index.html`,
+ according to a list in `config/faq.yml`.
+
+
+### Markdown metadata
+
+cms7 uses the markdown metadata extension, and recognises some special keys: