FormattingStyleGuide.md

Formatting & Style Guide

Scope and purpose

This document provides formatting and style conventions for publishing documents in GitHub in Markdown format. Some advice on document conversion and how to meet more sophisticated publishing needs is offered.

General

• Use GitHub Flavored Markdown.
• If the workflow prescribes the document to go into BitBucket repository first, then you may find BitBucket Markdown Syntax Guide useful.

Title & headings

• Use # (h1) for document title.
• Use ## (h2) for top-level headings.
• Number the headings manually. There's no heading numbering support in Markdown.

Table of contents

• Provide table of contents for longer documents.
• Use links in the table of contents. Use GitHub heading anchors. For example,

  [Table of contents](StyleManual.md#table-of-contents) 

links to this section.

Linking

• Use [relative linking)(https://github.com/blog/1395-relative-links-in-markup-files) to link to image files and other documents in the same repository.

Code

• Use backticks to mark inline code, URLs a.o. constant values.
• Use GitHub Markdown code fencing to format blocks of code.

Tables

• Use GitHub Flavored Markdown features.

Conversion

• Use programmer's editor (e.g. Sublime Text), or just Notepad to convert documents from Word, Confluence, PDF a.o. formats to Markdown.
• Specialised converter software (e.g. Pandoc) can be used, but will rarely justify the learning effort.

For more sophisticated publishing

• For more sophisticated presentation needs, consider using Hugo, Jekyll or some other website generation tool that accepts Markdown.

References

GitHub Mastering Markdown

BitBucket Markdown Syntax Guide