Style Guide & Pattern Library

This is the living style guide for OddSite and associated OddBird branding materials.

It is still in development, using OddBird's Accoutrement and Herman open source toolkits to automate as much living documentation as possible.

Writing Content

When creating content it is important to stay consistent. Review a sample blog post, and keep in mind the following guidelines:

Blockquotes

  • Content in a <blockquote> does not need quotation marks or italics. The CSS does the styling.
  • Blockquotes should be used when quoting another source. Blockquotes require 4 spaces.
    This is a blockquote with citation. Vestibulum tortor quam, feugiat vitae,
    ultricies eget, tempor sit amet, ante.

    --Person Name
  • If you want to highlight something and make it look similar to a blockquote, but do not have a source, you can use the following:
.. callmacro:: content-macros.j2#pullquote

  This is the best piece of content. It isn't quoting an external source,
  but the post is making an AWESOME point and I want to make it shine!

Branding

  • Always capitalize the “O” and “B” in OddBird and OddSite.

Commas

  • Guess we are going with the Oxford comma. writing, design, and development Note the comma before the coordinator in the sample.

Dashes

  • En Dash – Used to show ranges of things (e.g. January–March)
  • Em Dash — Instead of using em-dashes for asides as suggested by the The Chicago Manual of Style, using space en-dash space makes the block of text more readable. (e.g. this thing – and also that thing – etc) Read more here
  • Citations still need 2-3 dashes (-) to trigger the attribution class

Headlines

  • Use Title Case: Capitalize the first letter of every word except articles, prepositions, and conjunctions.
  • Do not use punctuation at the end of your title unless it contains more than one sentence or is a question.

Images

  • When using an image within the post content, provide an alt description for screen readers and search engines. Alt text should describe what is in the image.
  • We have some utility classes for images and figures and will be adding more soon. Currently, you can use the following:
    • size-quarter
    • size-half
    • size-full
    • img-border adds a hairline, helpful when using a screenshot with a white background.
    • img-shadow adds a slight drop shadow to images

Note: If declaring a size, it remains this size regardless of screen size.

The following utility classes will push or expand an image (or item) outside of its parent container:

  • extend-left - extends slightly outside of its container to the left
  • extend-right - extends slightly outside of its container to the right
  • extend-small - extends a small amount past its container on both sides
  • extend-large - extends a large amount past its container on both sides
  • extend-full - extends from left to right edges of screen

If using one of the above extend-* utility classes, alignment is built in. If not, the :align: directive accepts left, right or center and outputs as a class.

Below are a few examples when adding alignment, alt text, classes and links to images in RST:

.. image:: /static/images/blog/miko.jpg
   :align: right
   :alt: Miko smiling while playing outside
   :class: size-quarter img-border
   :target: https://supportada.org/?campaign=python

.. image:: /static/images/blog/imagename.jpg
   :alt: page with grid lines over artwork
   :class: extend-right

Intro

  • WIP - We will be featuring an introductory paragraph in each post. Stay tuned for details.

Line Length

  • Use links. To our posts and to external sources. Linking is good.
  • Links should open in the same window/tab unless there is a task being completed on that page that would lose a persons progress like filling out a form.

Summary

  • Each post should have a summary. This is shown on the archive pages (home and birds if recent, blog archive, tag archive) and when sharing on content to social sites.
  • The summary should not be repeated as the intro in the post.
  • It is created near the top of the document and format is as follows:
summary: |
  This is your short summary. You can include a excerpt that will appear
  on the archive pages and as the default social media summary.

Tags

  • Any post that contains a code sample should use the Code tag.
  • Use the plural version of a word if available. For example, Videos even if one video is referenced in the post.
  • Reference the tag list before deciding on which tags to use in order to avoid variations of the same topic.
  • Tags are Title Case.
  • Tags with multiple words should have spaces instead of dashes unless the phrase is hyphenated. Multi-word tags need to be declared as a string:
tag: ['Open Design', OddSite]
  • Tags are used to show related content. Think about what topics were covered in this post that would help the reader find a related article.
  • Adding tags when you are finished writing might result in cleaner and more accurate tags.
  • Posts that talk about sponsorship should include the Community tag.

Whitespace

  • No whitespace at the end of lines. In Sublime Text, we strongly recommend the following settings:
"rulers": [79],
"default_line_ending": "unix",
"ensure_newline_at_eof_on_save": true,
"translate_tabs_to_spaces": true,
"trim_trailing_white_space_on_save": true