FOG Documentation Style Guide

FOG’s Documentation is written in Markdown. You can find its source at toolkit/components/glean/docs.

Line breaks

We will use semantic linefeeds:

  • Break anywhere before 80-100 characters

  • Break after any punctuation when it makes sense

  • Break before or after any markdown when it makes sense

Tip: To keep lines narrow, use markdown’s reference link feature whenever it makes sense (or all the time. Up to you.).

Linking to other documentation

Linking to other external documentation is easy. Linking to other pieces of documentation in the source docs requires a link to the source file in the sphinx tree.

Links can be relative e.g. to link to the [preferences] docs:

[preferences](preferences.md)

Or they can be absolute e.g. to link to the Telemetry docs:

[Telemetry](/toolkit/components/telemetry/index.rst)

Sphinx will automagically transform that to an appropriately-base-url’d url with a .html suffix.