website: add readme and comments
Change-Id: I435b436fa080f352a11cf6938f16eb075fdfcfc4
diff --git a/Makefile b/Makefile
index b32a1ca..46d235f 100644
--- a/Makefile
+++ b/Makefile
@@ -56,8 +56,8 @@
serve: build
@static build -H '{"Cache-Control": "no-cache, must-revalidate"}'
-# 'entr' can be installed on Debian/Ubuntu using 'apt-get install
-# entr' and 'brew install entr' on OS X.
+# 'entr' can be installed on Debian/Ubuntu using 'apt-get install entr', and on
+# OS X using 'brew install entr'.
.PHONY: watch
watch: browser/ content/ public/ stylesheets/ templates/
@echo "Watching for changes in $^"
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f2ebf76
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# Vanadium website
+
+This repository contains the source code for generating the static assets for
+the Vanadium website.
+
+## Directory structure
+
+- `browser` - Client-side JS that executes when users visit the website
+- `build` - Output location for `make build`
+- `content` - Markdown content; gets converted to HTML by `haiku`
+- `helpers.js` - JS used by `haiku` when rendering Markdown files
+- `node_modules` - Disposable directory created by `npm install`
+- `package.json` - Tells `npm install` what to install
+- `public` - Static assets, copied directly into the `build` directory
+- `stylesheets` - LESS stylesheets, compiled into CSS for the website
+- `templates` - [Mustache] templates used by `haiku` for layouts and partials
+- `tools` - Tools involved in generating the site's static assets
+
+## Development
+
+### Prerequisites
+
+Install Vanadium per the installation instructions on the website. Also, install
+the Node.js profile using `jiri v23-profile install nodejs`.
+
+### Local development
+
+You can make and view changes locally by running a development server:
+
+ make serve
+
+This command will print out a URL to visit in your browser. It will take a few
+minutes to run the first time around, but subsequent invocations will be fast.
+
+By default, the running server will not reflect subsequent changes to the
+website content, since it's just serving the assets in the `build` directory.
+Running `make build` will cause the server to see the new content. Better yet,
+use the following command to automatically rebuild the assets whenever something
+changes:
+
+ make watch
+
+This command requires the `entr` program, which can be installed on
+Debian/Ubuntu using `apt-get install entr`, and on OS X using `brew install
+entr`.
+
+### Copy changes
+
+Add or modify [Markdown]-formatted files in the `content` directory.
+
+The `haiku` tool provides some extra flexibility on top of standard Markdown by
+processing Mustache template variables. For example:
+
+ = yaml =
+ title: My Creative Title
+ author: Alice
+ = yaml =
+
+ # {{ page.title }}
+
+ Author: {{ page.author }}
+
+A common editing workflow is to run `make watch`, edit Markdown files in a text
+editor, and refresh the browser to see changes. If you prefer a WYSIWYG editing
+experience, there are a number of options, e.g.:
+
+- [Atom](https://atom.io/)
+- [StackEdit](https://stackedit.io/)
+- [Dillinger](http://dillinger.io/)
+
+For new content, it's common to do initial drafting and editing in [Google
+Docs], and to switch to Markdown at publication time.
+
+### CSS and JS changes
+
+The `make build` task generates `public/css/bundle.css` and
+`public/js/bundle.js` from the files in `stylesheets` and `browser`
+respectively. To modify the website CSS or JS, edit those files, then rebuild
+the site (or use `make watch` to have your changes trigger rebuild).
+
+## Deployment
+
+The `make deploy` task deploys the website to GitHub Pages. Be sure to run this
+task from a clean master branch, and to run `jiri update` immediately before
+deploying to ensure that you aren't missing any upstream changes. We're working
+on setting up additional checks to avoid these pitfalls, along with an automatic
+deployment process.
+
+[mustache]: http://mustache.github.io/
+[markdown]: https://daringfireball.net/projects/markdown/
+[google docs]: https://docs.google.com/
diff --git a/stylesheets/index.less b/stylesheets/index.less
index 48c61f9..8062340 100644
--- a/stylesheets/index.less
+++ b/stylesheets/index.less
@@ -6,6 +6,13 @@
@import "code";
@import "icon";
+/**
+ * Note to contributors: The style rules below have been tuned and tested
+ * extensively across various device types and screen sizes. If you wish to make
+ * changes, please consult the primary authors to ensure that your changes will
+ * not break anything.
+ */
+
*,
:before,
:after {
diff --git a/templates/partials/sidebar.mustache b/templates/partials/sidebar.mustache
index 39c8ad1..8ad3a43 100644
--- a/templates/partials/sidebar.mustache
+++ b/templates/partials/sidebar.mustache
@@ -1,5 +1,9 @@
+{{!
+Note to contributors: The sidebar items and ordering were tested extensively for
+usability. Changes here should not be taken lightly.
+}}
<div class="sidebar"></div>
-<!-- TODO(sadovsky): Transmit data as JSON, not HTML. -->
+{{! TODO(sadovsky): Transmit data as JSON, not HTML. }}
<div class="sidebar-data">
<a href="/">Overview</a>
<a href="/installation/">Installation</a>
