Git for Writers

Style Guide

There are certain written, structural (XHTML), and design styles to follow for contributing to Git for Writers.

Basic Markup

Like any good XHTML page, most of the markup for Git for Writers consists of headings, paragraphs, and lists.

Headings

The names of pages are placed in <h2> tags; there should only be one <h2> heading per page.

The major divisions of a page should be written in <h3> tags. There can be multiple <h3> tags per page.

The major divisions of a page can be broken into smaller sub-divisions, marked using <h4> tags. There can be multiple <h4> subdivisions within a major division.

Paragraphs

Most running paragraph text appears in the basic <p> tag.

Quotations of long stretches of text can appear in the <blockquote> tag, but the quoted material must also be marked by either paragraph tags or, in the case of a quotation of a list, using the list tags (see the Lists section of this document):

<p>
  According to the 
  <a href="http://git-scm.com">Git homepage</a>,
</p>
<blockquote>
  <p>
    Git is a free & open source, distributed version 
    control system designed to handle everything from 
    small to very large projects with speed and 
    efficiency.
  </p>
</blockquote>

That will render something like this:

Lists

For steps in a process or anything where order matters, use the ordered list, <ol>:

<ol>
  <li>Download Git</li>
  <li>Install Git</li>
  <li>Love Git</li>
</ol>

For lists of things whose order does not matter, use the unordered list, <ul>:

<ul>
  <li>We love Git</li>
  <li>Yes we do</li>
  <li>We love Git, how about you?</li>
</ul>

Basic Phrase Markup

You can make short bits of text bold (<strong>), add a little emphasis (<em>), or refer to the title of a work, Git for Writers (<cite>).

Git-related Markup

Because Git is a command-line tool, most interaction with it occurs through text, in a terminal. There are three different tags to use for marking up Git input, output, and interactions:

1. kbd: Use the <kbd> element for anything someone would type. For example, <kbd>git status</kbd> appears as git status.
2. samp: Use the <samp> element for single-line responses from Git. For example, <samp># On branch master</samp> appears as # On branch master.
3. pre: Use the <pre> element for multi-line interactions with Git. Output that appears in red (in many environments) can be marked using <span class="warn">, and output that appears in green can be marked as <span class="good">. Git sometimes outputs angle brackets, so be sure to escape those (< for <, > for >):

<pre>
$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD &lt;file&gt;..." to unstage)
#
#	<span class="good">modified:   css/screen.css</span>
#
# Changed but not updated:
#   (use "git add &lt;file&gt;..." to update what will be committed)
#   (use "git checkout -- &lt;file&gt;..." to discard changes in working directory)
#
#	<span class="warn">modified:   style-guide.htm</span>
#
</pre>

$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	modified:   css/screen.css
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   style-guide.htm
#