@@ -22,8 +22,9 @@ source](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon).
23## Docs guidelines
23## Docs guidelines
25−For documentation pull requests, acquire [pandoc](http://pandoc.org) and
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)
26−format your edited files with the following flags:
27+and make sure to format your edited files with the following flags:
28 $ pandoc --standalone \
29 $ pandoc --standalone \
29 --from=markdown+yaml_metadata_block \
30 --from=markdown+yaml_metadata_block \
@@ -31,8 +32,15 @@ format your edited files with the following flags:
31 -o output.md \
32 -o output.md \
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.
40+**Note:** If you have an old version of Pandoc, it may convert the
34−**Note:** Pandoc will convert the terminating `---` in YAML metadata to
41+terminating `---` in YAML metadata to `...`, which is grounds for termination.
35−`...`, which is grounds for termination. Run the following one-liner to
42+Run the following one-liner to atone.
38 $ sed '1,/^$/ s/^\.\.\./---/g' input.md > output.md
44 $ sed '1,/^$/ s/^\.\.\./---/g' input.md > output.md
46+Newer versions of pandoc (1.19.2.1, for example) don't have this issue.