Ideas for a book style guide
Some notes on structural style and formatting:
- wrap lines at 80-ish width, excepting:
- URLs that begin before 80 chars but overflow it
- Anything within a code block
- any headers (unlikely that headers should be this long, but we should specify)
- Newlines are '\n'
- all markdown in one folder
- when relative-linking between pages, link to the markdown file, not html. The build process will transform these into correct hyperlinks
- example:
blah blah blah, see [Getting started](./ch02-01-getting-started.md).
- example:
- all image assets in one sub-folder, linked from one or more markdown files
- markdown files are named like this:
ch{CHAPTER}-{SECTION}-{NAME}.md
. Note:- since all markdown is in one folder, the sorting of the files is the same as how the book reads front to back
- For multi-word names of chapters and sections, we prefer
-
hypen separation, not_
underscores
Manually formatting the width of markdown is toilsome, and reducing toil is one of our goals (#138 (closed) ), so we must develop/find tools to automatically format markdown.