add DEVELOPMENT.md

3 files changed, 67 insertions, 34 deletions

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..fdb6cef
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,62 @@
+Workspace setup
+---------------
+
+* To reduce pain, set up [rbenv] to manage your Ruby versions.
+Install one that's known to work: `make ruby`
+    * Otherwise, make sure you have Ruby and [Bundler] set up.
+* Install dependencies: `make deps`
+* Make sure builds are working: `make build`
+
+[rbenv]: https://github.com/rbenv/rbenv
+[Bundler]: https://bundler.io/
+
+Development
+-----------
+
+* Build the example website and serve it at http://localhost:4000/wireguard-config/:
+`make serve`
+    * It will pick up changes and reload pages automatically.
+
+Upgrading dependencies
+----------------------
+
+Ruby dependencies:
+
+    bundle update
+
+Node.js dependencies:
+
+    make npm
+    npm update
+    make bundle
+
+Building static pages
+---------------------
+
+If you try to copy the _site directory and open index.html without running the
+web server, it won't work: all links will be messed up.
+Jekyll doesn't provide native support for generating a static website which can
+be browsed without running a web server.
+
+One workaround is to `wget` the website:
+
+    make serve LIVE_RELOAD=0    # Live reloading breaks wget
+    make wget
+
+The truly static version will be downloaded to the .wget/ directory.
+
+Node.js dependencies
+--------------------
+
+For IP address parsing and validation, [ipaddr.js] was used originally.
+It is pre-built for browser use, which is nice; however, it's [buggy].
+It was replaced by [ip-address], which is not browser-ready; instead,
+[Browserify] is used to turn it into a suitable .js file.
+
+This whole situation sucks, but I really want to keep this website static.
+TODO: find other options or wait until ipaddr.js fixes the bug.
+
+[ipaddr.js]: https://github.com/whitequark/ipaddr.js
+[buggy]: https://github.com/whitequark/ipaddr.js/issues/160
+[ip-address]: https://github.com/beaugunderson/ip-address
+[Browserify]: https://browserify.org/
diff --git a/README.md b/README.md
index 173a9a5..003dd8c 100644
--- a/README.md
+++ b/README.md
@@ -45,45 +45,15 @@ servers using your browser's debugging tools.
 Development
 -----------
 
-This is a static website, generated using [Jekyll].
-
-Make sure you have Ruby and [Bundler] set up.
-[GNU Make] is used for shortcuts.
-
-* Install dependencies by running `make deps`.
-* Build the website by running `make build`.
-* Launch a local web server by running `make serve`.
-Access the website at http://localhost:4000/wireguard-config/.
-
-[jekyll-theme] is used as a remote Jekyll theme.
+This is a static website, built using [Jekyll].
+[jekyll-theme] is used as the Jekyll theme.
 
 [Jekyll]: https://jekyllrb.com/
-[Bundler]: https://bundler.io/
-[GNU Make]: https://www.gnu.org/software/make/
 [jekyll-theme]: https://github.com/egor-tensin/jekyll-theme
 
-### Access via file://
-
-Jekyll doesn't provide native support for generating a static website which can
-be browsed without running a web server.
-One workaround is to `wget` the website (use `make wget`).
-The truly static version will be downloaded to the .wget/ directory.
-
-### Node.js dependencies
-
-For IP address parsing and validation, [ipaddr.js] was used originally.
-It is pre-built for browser use, which is nice; however, it's [buggy].
-It was replaced by [ip-address], which is not browser-ready; instead,
-[Browserify] is used to turn it into a suitable .js file
-(`make npm && make bundle`).
-
-This whole situation sucks, but I really want to keep this website static.
-TODO: find other options or wait until ipaddr.js fixes the bug.
+See [DEVELOPMENT.md] for details.
 
-[ipaddr.js]: https://github.com/whitequark/ipaddr.js
-[buggy]: https://github.com/whitequark/ipaddr.js/issues/160
-[ip-address]: https://github.com/beaugunderson/ip-address
-[Browserify]: https://browserify.org/
+[DEVELOPMENT.md]: DEVELOPMENT.md
 
 License
 -------
diff --git a/_config.yml b/_config.yml
index 74d1fb4..1cf20d5 100644
--- a/_config.yml
+++ b/_config.yml
@@ -6,6 +6,7 @@ show_drafts: true
 strict_front_matter: true
 
 exclude:
+  - DEVELOPMENT.md
   - Makefile
   - prelude.mk
   - README.md