Docs

v.Latest
Introduction
Core Concepts
Querying Content
Editing
Customizing Tina
Going To Production
Media
Drafts
Guides
Further Reference
    Style Guide

    This document should be used as a guideline when writing documentation and blog posts on tinacms.io

    Brand

    • Capitalization: Tina, TinaCMS, TinaCloud
    • When discussing the project as a whole, Tina and TinaCMS can be used interchangeably.
    • Prefer Tina over TinaCMS when discussing specific packages or components and their relation to the project.
      • Example: "The sidebar is the primary interface in Tina."

    Tone

    • Aim for a friendly, personal tone
    • Documentation and tutorials should feel free to address the reader
      • Example: "If you want to see a glimpse of what you can do with a blocks-based content strategy, fork Tina Grande and give it a try."
    • Tutorial steps should use an inclusive POV ("we" over "you")
      • Example:"Let’s say, instead of a single name, we’re storing a list of names like this:"
    • While you don't need to follow it dogmatically, running your drafts through the Hemingway Editor can help identify overly complicated prose.

    Formatting

    • Inline and block code tags should be reserved exclusively for communicating code.
      • "Code" in this case can include source code, terminal commands, variable names, and package names.
      • The above is not meant to be an exhaustive list, but use your best judgement.
      • Avoid code tags when discussing interface elements (such as navigation menus and in-app actions). Opt for bold text instead.
      • Code blocks should be made copy-able unless they show more context then should be copied (i.e. diffs)
    • Important concepts should be formatted in bold (strong emphasis).
    • Other points of emphasis can be formatted in italics (normal emphasis), or bold (strong emphasis) as appropriate.
    • When an emphasized phrase appears near a highlighted concept, opt for italics over bold for the former.
    • Avoid emphasis fatigue! Too much emphasized text clustered together will lose its emphasis. Over-reliance on emphasis may indicate a lack of clarity in the writing.

    Headings

    • Each document should have a single top-level heading. On the tinacms.org website, this is handled by the title front matter field.
    • Headings should follow strict hierarchy. Don't nest an h3 directly inside an h1 without an h2 in between.
    • Don't nest headings more than three levels deep, inclusive of the top-level heading (h1 > h2 > h3). If you find the need to use a fourth-level heading, consider reorganizing the document or splitting it up.
    • Headings can include italics, but avoid bold text or code tags.
      • Use italics formatting for code-like items when present in headings
    • Make an effort to capitalize titles appropriately. Check out title.sh for help.
    • Avoid using code tags in links.
    • Links should stand out consistently from their surrounding text; avoid applying additional formatting. Links appearing within emphasized text may be formatted appropriately.
    • Link text should flow naturally in prose and relate semantically to the link target. Basically, just don't use "click here".
    Last Edited: September 11, 2024
    Table of Contents