A style guide is a set of guidelines maintained by an editor on the way that material should be formatted for publication.
This collection aims to adhere to a consistent style. Unfortunately, it is composed of working notes so I make not apologies for violating the following style guide.
On the structure of notes
Filenames
A unique and descriptive but brief name shall be given to each file. This also serves as the title for a note/page. The title is not included in the frontmatter.
Frontmatter
Notes in this directory should be provided with metadata for it date of creation (ctime) and its date of last modification (mtime); this if primarily for the purpose of giving the pages available on docs a date of publication and also to remind me how out of date the information within might be. Also included in the frontmatter is any requisite tags.
Headings
Most pages will have an initial body of text that serves as an outline of the concept described within. All subsequent paragraphs should be children of a relevant heading. This is to maintain consistency and navigability in the table of contents pane.
The final section will include links…
To other relevant notes, to further reading (usually detailed literature), or to some other thing of interest.
Footnotes
Typically this will be references or points of clarification that needn’t complicate an already lengthy section of text.
On the formatting of text
Where practical, formats incompatible with standard markdown such as sub- or super-scripts should be avoided for rendering and functionality, much to the authors dismay.
- Exponents included in text shall be represented with E notation.
- If equations are included they shall be in the LaTeX format.
On the formatting of graphics
Images or flowcharts (generated with mermaid) will be embedded in their corresponding section of text. All embedded graphics shall be in the .png format or .svg format except for true images that require a different format (such as microscopy slides or clinical pictures including radiology or gross pathology).
On referencing
Where references are given they should be in Vancouver style and included in a footnote. The “further reading” section of many notes includes other reading material and does not need to be referenced in Vancouver style. It should, however, generally follow the format: Author. Title. Publisher. Date. Availability.