@@ -22,8 +22,9 @@ source](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon).
2222
2323## Docs guidelines
2424
25−For documentation pull requests, acquire [pandoc](http://pandoc.org) and
26−format your edited files with the following flags:
25+For documentation pull requests, if you are making a brand new page, you'll want
26+it to conform to our general documentation standards. Acquire [pandoc](http://pandoc.org)
27+and make sure to format your edited files with the following flags:
2728
2829 $ pandoc --standalone \
2930 --from=markdown+yaml_metadata_block \
@@ -31,8 +32,15 @@ format your edited files with the following flags:
3132 -o output.md \
3233 input.md
3334
34−**Note:** Pandoc will convert the terminating `---` in YAML metadata to
35−`...`, which is grounds for termination. Run the following one-liner to
36−atone.
35+If you are editing an existing page, reformatting the entire page with pandoc
36+will make the diff hard to read. Instead, just make sure that your edits generally
37+conform to the style of the existing docs around it. For example, you'll notice
38+that the paragraphs mostly wrap at column 80.
39+
40+**Note:** If you have an old version of Pandoc, it may convert the
41+terminating `---` in YAML metadata to `...`, which is grounds for termination.
42+Run the following one-liner to atone.
3743
3844 $ sed '1,/^$/ s/^\.\.\./---/g' input.md > output.md
45+
46+Newer versions of pandoc (1.19.2.1, for example) don't have this issue.