title | layout | category | id |
---|---|---|---|
Style Guide |
page |
instructions |
style_guide |
This document needs a lot of help, and will emerge in a fuller form over time.
Push is nothing but a collection of plain-text files. To keep everything uniform and readable, set up your editor to the following conventions (Google around for help with your specific editor):
- Use UTF-8 (Unicode) encoding without the byte-order mark (BOM)
- Use Unix-style line endings (LF), not Windows-style (CR)
- Indent using two spaces, not tab characters (many editors can be configured to insert two spaces automatically when you press the Tab key)
- Hard-wrap long lines of text to under 100 characters
All of Push’s content pages, as well as its blog posts and article submissions, are written in Markdown. Cross-reference the source of this page to see how the Markdown styles are achieved.
There are four levels of headings available on Push:
Paragraphs are just blocks of text with a line of white space above and below.
Use lists with abandon. There are two kinds availble to use, unordered (bulleted) and ordered (numbered).
-
Start each item with an asterisk,
*
, just like you would in plain-text email. -
You can bold the opening phrase for emphasis.
-
List items can contain multiple paragraphs; just separate each item with a line of white space.
And then the paragraph stays with the list item.
-
Ordered lists are useful for steps/enumeration. Use them when you have a set of things you want to refer to by number elsewhere in your text.
-
Ordered lists begin with a number and period. You can write out the actual numbers, or just keep using
1.
over and over, which keeps things simple if you need to add an item in the middle of a list.
Citation will be handled through hyperlinks and footnotes. However, footnotes are only for citation, not for asides or other ancillary material.
Citation in Push articles will be handled as footnotes, according to the Chicago Manual of Style.1 In the running text, you’ll write a unique marker for each source, following terminal punctuation, e.g.,
According to the *Chicago Manual of Style*,[^cms]
Then, at the very bottom of your article, build a list of your footnotes:
[^cms]: *Chicago Manual of Style*, 16th ed. (Chicago: University of Chicago Press, 2010), 14.19-14.23.
When it makes sense to hyperlink to Web-available materials (for example, to documentation, language references, or live versions of a project you’re writing about), use hyperlinks.
Hyperlinks will be the primary means of citation on the Push blog. Use footnotes only for
non-web-available materials. To avoid conflicts between blog posts on the same page, prefix each
footnote marker with your initials, e.g., [^kas_cms]
.
Block quotes begin with
>
; indent two spaces and mark each new line of the block quote with a new>
, for easy source reading. Then, on an empty new line, List the source if the block quote is an epigraph.Karl Stolley, Push Style Guide
For block quotes with cited material, you’ll use the same formatting as above, but rather than a source, you’ll use the Markdown/Maruku footnote syntax, as with inline citation.
Push will be publishing articles and blog posts containing lots of source code.
You’ll open, as in the examples below, with a {% raw %}{% highlight %}
{% endraw %} statement that
contains the name of the language in your source example. Push/Jekyll uses
Pygments to handle syntax highlighting, and there are
quite a few languages supported.
The first line of each example should also contain the name of the language in a comment in the language’s comment syntax. Optionally, use a hyphen separated by spaces to add the specific file name you’re referring to.
For example, to render HTML, one would write this in the Markdown (note that you do not need to escape HTML into entities, which makes copying and pasting a breeze):
{% raw %} {% highlight html %} {% endhighlight %} {% endraw %}
And see this output:
{% highlight html %}
{% endhighlight %}Here’s a CSS example, and its output; note the linenos
argument to output line numbers:
{% raw %} {% highlight css linenos %} /* CSS - screen.css */ footer { font-family: Times; border-top: 1px solid #fff; } {% endhighlight %} {% endraw %}
{% highlight css linenos %} /* CSS - screen.css */ footer { font-family: Times; border-top: 1px solid #fff; } {% endhighlight %}
And finally, one for Ruby:
{% raw %} {% highlight ruby %} # Ruby - journals_controller.rb @journal = Journal.new {% endhighlight %} {% endraw %}
{% highlight ruby %}
@journal = Journal.new {% endhighlight %}
Footnotes
-
Chicago Manual of Style, 16th ed. (Chicago: University of Chicago Press, 2010), 14.19-14.23. ↩