Add notes about running the documentation site

[joshuataylor]

Notes about how to install pandoc and scdoc.

[Consolatis]

Thanks for the PR. Small review below:

Suggest marking step 2 as optional and adding another optional step along the line of

• Preview deploy/index.html in a browser

[johanmalm]

Should we make it clear that you don’t actually have to build the site to contribute (i.e. pandoc is only required if you want to view the generated html before committing).

The site will auto build on push.

For big changes it will make sense to view it first, but I wouldn’t want anyone put off from contributing by thinking they’ve got to install pandoc (which is big on some distorts),

[Consolatis]

Agree, just modifying something in src/, creating a commit and sending the PR is enough to improve the website.
Everything else is just to verify locally that the results are as intended before sending the PR.

[johanmalm]

Two suggestions for improvement (I can implement if nobody else feels like it - so just writing here for discussion):

• Take an optional argument to only build one file. This would save building all src/*.md + man pages just to check that modified markdown page(s) look okay.
• Return early (with a helpful message) in the two build-site functions if pandoc and scdoc are not available.

Can use a function like this:

is_installed () {
  type "$1" >/dev/null 2>&1
}

type is better than which. Can't remember why though 😄

[Consolatis]

Sounds good to me. There is also command -v "$1" but I don't remember the benefits of command vs type either. I think which had the issue of not detecting shell aliases but I don't quite remember if that was the only difference right now.

We could also mention that it should now be fine to just use the Github interface for the actual edit / commit, that way its not even required to clone the repo locally.