Style Basics

Gradient uses IBM Plex Sans (sans serif) font in most cases for both internal and client-facing deliverables. In the handbook, please reserve mono and code font specifically for code snippets.

Content headings should be descriptive enough to suggest their corresponding content when they or corresponding fragment identifiers are seen out of context.

Content headings should be second-level headings and below. First-level headings are reserved for page titles.

Link fragment identifiers (e.g. #capitalization) are automatically generated from most headings. Keep that in mind when choosing your headings.

Handbook content currently uses both Title Case and Sentence case for titles and headlines. While sentence case can be a nice design option, title case can actually convey important information independent of punctuation, typographic emphasis, or additional descriptive text—it says this text is the name of something all by itself. That might seem obvious from the styling of a title or a heading, but it isn’t obvious in references from other contexts, such as links from other pages, of which there are many in the Handbook. Thus, title case should be preferred over sentence case for Handbook titles and headings. Note that the GitLab Blog uses sentence case, but that is a different context and the Blog is not as reference-heavy as the Handbook.

Brand names such as “Apple” and “Slack” are proper nouns, so they should usually be capitalized. If a brand name uses unusual capitalization, as in “eBay” and “IKEA” (yes, you specifically Kyle), then follow the brand’s convention.

For easy reading, easy typing, and consistency use kebab case—lowercase letters with hyphens between words—for all file and directory names unless you have a specific reason for doing otherwise (e.g., due to a programming convention for which underscores are preferred or because a file is primarily intended for download and you want it to have a certain name when downloaded).

See URL Guidelines for more information about best practices for URLs.

Links from the Handbook should conform to a few general guidelines:

• Linked text should describe the content to which the link leads. A page title or description is usually a good choice and preferable to something like “this” or “here.”
• Link URLs should not result in unnecessary redirection.
• Link URLs should not specify default file names or extensions unless excluding them would result in redirection. Overly specific link URLs are more likely to break in response to future changes.
• Same-site links should use root-relative URLs, not absolute URLs or document-relative URLs.
• Same-page URLs should just be fragment identifiers (e.g., #link-guidelines).

See Understanding Absolute and Relative URLs for more information about each type of URL.

In general, Handbook URLs should describe their content and be as clean and easy to remember as feasible. Unless there is a good reason for formatting URLs otherwise (e.g., language conventions or technical limitations), they should be entirely lower case, any two words should be separated by a single hyphen, and ampersands should be replaced by “and”, not an additional hyphen.

Files and directories should never be given names that differ from the names of other files or directories in the same location only by letter case. Case-sensitive file systems allow such naming, but our source code is shared with people using various different file systems, including case-insensitive file systems, upon which the mere existence such similarly named files in a repository can cause problems. For example, new macOS systems use case-insensitive APFS by default and on those systems Git can end up alternately showing two differently-capitalized files as modified when no changes have actually been made to either.

When you’re adding or editing links in the Handbook (or really, anywhere on the marketing site) please keep in mind that root-relative URLs are preferable for our same-site links.

Absolute URLs are the ones that look like this:

/handbook/

With absolute URLs, links always load the live version of the site—even when run from a development, testing, or staging context. They’re great for sharing URLs via Slack, issue and merge request comments, email, and social media, but not for same-site links.

Document-relative URLs are the ones that look like this:

../product/technical-writing/

With document-relative URLs links can break when either a linking document or a linked document is moved separately from the other document. These kinds of URLs can be great for maintaining relationships between documents in different contexts, but links that use this kind of URL are best managed by automated systems that won’t forget to update them.

Root-relative URLs, the kind we prefer for use in the Handbook, look like this:

/handbook/handbook-style-guide/

With root-relative URLs same-site links can work properly during local development and testing, during automated tests and staging, and on the live site. And unlike with links that use document-relative URLs, moving a document won’t break its same-site links to other pages that do not move with it.

Since we’re using a git repository—we want to keep it as clean, simple and quick as possible. This also means that our preferred method for adding images and videos in your articles is through cloud-embedding. Basically, this means that an image should already be somewhere on the web, and we link to it through a shortcode. While more information can be found in the Hugo Shortcodes Documentation, please see a minimal example below, where we link to an image that is uploaded through HubSpot.

• Provide the link in the src="" parameter.
• We can add width or height parameters to manipulate image size. Defaulting to width = "100%" is a great way to fill up the page.

{{< figure src="https://www.gradientmetrics.com/hubfs/Handbook/handbook-style-guide/Gradient%20Deck%20Template%20-%20Base.png" width= "100%" >}}

As mentioned, we don’t want any images to be uploaded to our repository to keep it fast and clean. This is why we upload images to our website-hosting platform called Hubspot.

1. Log in to HubSpot using your credentials
2. Go to Marketing -> Files and Templates -> Files -> Handbook or simply follow this link: Hubspot Handbook Files
3. Use the same folder structure as in the handbook - if a folder for your pages doesn’t exist yet, please create one.
4. Upload your image in the correct folder
5. Copy the link of the image and add it in the src="" part of the shortcode.