Style Guide & Pattern Library
This is the living style guide for OddSite and associated OddBird branding materials.
When creating content it is important to stay consistent. Review a sample blog post, and keep in mind the following guidelines:
- 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!
- Always capitalize the “O”, “B”, and “S” in OddBird and OddSite.
- Guess we are going with the Oxford comma.
writing, design, and developmentNote the comma before the coordinator in the sample.
- En Dash – Used to show ranges of things (e.g.
- Em Dash — Instead of using em-dashes for asides as suggested by the The
Chicago Manual of Style, using
spacemakes 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
- 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.
- 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:
img-borderadds a hairline, helpful when using a screenshot with a white background.
img-shadowadds a slight drop shadow to images.
content-imgdeclares a location for the image, which allows you to more easily target only certain images in content area.
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
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
- WIP - We will be featuring an introductory paragraph in each post. Stay tuned for details.
- For line length, we follow the PEP 8 - Style Guide for Python Code which wraps lines after 79 characters.
- 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.
- 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.
- Any post that contains a code sample should use the
- Use the plural version of a word if available.
Videoseven 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
- No whitespace at the end of lines. In Sublime Text, we strongly recommend the following settings:
"rulers": , "default_line_ending": "unix", "ensure_newline_at_eof_on_save": true, "translate_tabs_to_spaces": true, "trim_trailing_white_space_on_save": true