📌 Start here! Contributing guidelines
Front matter
Content
- Editing content
- File names
- Sentence case
- Spacing
- Headings
- Links
- Emoji
- Usernames
- Slack channels
- Tables
- Images
- Videos
- Details disclosure
- Footnotes
Redirects
Nav
- Exclude pages
- Icons
Homepage banner
Banners
- Adding a new banner
- Usage
Consistency
Styling
Maintainers

📌 Start here! Contributing guidelines

Before contributing to any repo, you should read the contributing guidelines. It provides a step-by-step guide on how to add, change and remove content. And here are some troubleshooting tips.

If you are unsure of what type of content should go on The Hub, refer to the Communicating at GitHub section.

Front matter

Something you'll see referenced here a lot is front matter—this refers to the several lines of code at the top of most Markdown files. Front matter is wrapped in two lines containing three dashes (---) and the contents within are referred to as key-value pairs (key: value).

For example, here's some front matter from this page:

---
layout: page
title: Docs
description: "Supporting documentation, guidelines, and examples for The Hub's design and development."
banner: banner-talking-heads-outrun.png
nav_exclude: true
toc: true
---

While there is additional front matter you can include, the following are the most common.

layout typically will always be page. Should Hubbers request specific layout changes, we'll work with @mdo to determine or create a layout that satisfies this need and update the front matter to reflect it.
title is your page's title and first heading. Don't repeat your title inside the page content (e.g., 2020 Reflections & Rewards).
description is your lede or intro paragraph. It should give a little more detail about the page. (e.g., The information and resources you need to know for the 2020 Reflections & Rewards cycle).
octicon (optional) is for top-level sections where you want a custom icon instead of a generic folder icon. A subset of 24px Octicons are available for use here. If you can't find one, ping @mdo.
banner (optional) is for adding an image across the top of the page, like on our homepage. These should only be used on index pages within top level sections. Contributors can choose from a gallery of available banners in the docs page. Copy the name of the banner with file extension and add it to the front matter (i.e., banner: banner-codelines-red.png).
nav_exclude (optional) is to prevent pages from being included automatically in our lefthand navigation.
toc (optional) is for adding a table of contents at the top of your page that deep-links to headings throughout the page.

Content

Beyond proofreading all copy for spelling and grammar, be sure to read through and abide by the following content guidelines on The Hub.

Editing content

Content edits must happen via pull request. Ensure pull requests are submitted against the main branch with unique branch names. Do not push directly to main.

Read our contributing guidelines for additional information.

File names

File and folder names should always be lowercase.
Don't repeat directory names in file names (e.g., guides/expenses.md instead of guides/expenses-guide.md).
Use dashes, not underscores, as necessary.

Sentence case

All copy must be in sentence case (capitalize only the first letter of the first word in the title, as you would when writing a sentence). When reviewing, approving, or adding content, please ensure that all titles and headings are written in sentence case for consistency across The Hub.

For example: GitHub account upgrades, not GitHub Account Upgrades.

When referring to any GitHub orgs in the copy, the first letter should be capitalized as it refers to the name of the team, group, or org. For example, the Product team instead of the product team. For orgs commonly referred to as acronyms (like IT), all letters should be capitalized.

Spacing

Empty lines and trailing whitespace is strictly enforced in The Hub for code quality and consistency. As a general rule, always include one empty line before and after headings, paragraphs, and lists. Here's an example of properly spaced Markdown content:

### Example heading

Here are some additional resources for Hubbers:

- List item here
- Another list item here
- And one last one to close it out

This is an example paragraph after the list shown above.

Similarly, do not commit trailing whitespace. Trailing whitespace is spaces that are at the end of a line of text. These are unecessary as HTML pages do not render them, so there's no reason to include them.

Trailing spaces screenshot

You may encounter failing tests if you have multiple empty lines or trailing whitespace in your Markdown file.

Headings

All headings must include an empty line before and after them for readability.

Emoji

Emoji is available via the remark-gemoji plugin. Type your emoji like you normally would in GitHub and it'll be rendered inline.

:tada: is 🎉
:+1: is 👍

Alternatively, you can use the emoji picker in macOS (hit Ctrl+Cmd+Space to bring up the menu). From here, select an emoji and it'll be pasted in and look like the Apple emoji.

🎉
👍

Usernames

GitHub usernames are automatically linked thanks to the remark-github plugin. These links point to a Hubber's GitHub.com profile.

Slack channels

While Slack channels are not automatically linked, their syntax is straightforward enough. Here's an example of a link to #thehub-team Slack channel where our maintainer team hangs out.

#thehub-team

[#thehub-team](https://github.slack.com/messages/thehub-team)

For an example, try editing this page.

Tables

Example Markdown-generated table:

Option	Description
data	path to data files to supply the data that will be passed into templates.
engine	engine to be used for processing templates. Handlebars is the default.
ext	extension to be used for dest files.

| Option | Description                                                               |
| ------ | ------------------------------------------------------------------------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default.    |
| ext    | extension to be used for dest files.                                      |

And modifying that to use right-aligned columns:

Option	Description
data	path to data files to supply the data that will be passed into templates.
engine	engine to be used for processing templates. Handlebars is the default.
ext	extension to be used for dest files.

| Option |                                                               Description |
| -----: | ------------------------------------------------------------------------: |
|   data | path to data files to supply the data that will be passed into templates. |
| engine |    engine to be used for processing templates. Handlebars is the default. |
|    ext |                                      extension to be used for dest files. |

Images

The easiest way to add images when adding/editing pages through dotcom's UI is to simply drag the image into the markdown editor. This will upload the image to our user content storage and add the image to the page.

When you do so, be sure to change the description (alt) text to describe the image for screen reader users. For advice on writing good alt text, take a look at this news article about Global Accessibility Awareness Day. There's also this great document on the hub about how to work with accessibility in mind.

If you would like the image to be hosted alongside The Hub, add the images to a media/ directory alongside the file containing the image. For example, if you are wanting to add an image to docs/support/account-security/handling-bouncing-email.md, first create a media/ directory at docs/support/account-security/ (if it doesn't already exist) and add you image there. Then use a relative url to reference the image in the markdown:

![My cool image](./media/my-cool-image.png)

Dark/Light Mode Specific Images

If available (and necessary) it is helpful to have unique images for Light and Dark mode viewers. An image with a white background can be harsh for someone using Dark mode. To support this, The Hub has two special css classes that can be used to only show content in either mode.

gh-light-mode-only will only show when viewing The Hub in Light mode.
gh-dark-mode-only will only show when viewing The Hub in Dark mode.

Since these classes only take affect when viewing on The Hub, the markdown source will contain both the Light and Dark images. In addition, since we are using css classes, we need to use the HTML markup for our images (<img alt="" src="" />) rather than the Markdown format (![alt](src)). Here's an example:

<img
  class="gh-light-mode-only"
  alt="My cool image"
  src="./media/my-cool-image-light.png"
/>
<img
  class="gh-dark-mode-only"
  alt="My cool image"
  src="./media/my-cool-image-dark.png"
/>

Videos

To embed a video on a page on The Hub, you need to use the right syntax:

If this is the link to your video https://user-images.githubusercontent.com/7498102/115261084-9deea980-a133-11eb-8dc3-b0e91be7b4da.mov Insert the following on its own line, with spaces before and after, changing src to be your video url:

<video width="100%" class="mx-auto my-5" controls>
  <source
    src="https://user-images.githubusercontent.com/7498102/115261084-9deea980-a133-11eb-8dc3-b0e91be7b4da.mov"
  />
</video>

Details disclosure

When using the <details> element (or any HTML elements for that matter), be sure to add a blank line surrounding any Markdown that needs to be rendered inside. Otherwise, it will be considered HTML and not rendered properly.

This is the summary

And this is the markdown content that would be hidden by default, and then revealed on click.

<details>
<summary>This is the summary</summary>

And this is the **markdown** content that would be hidden by default, and then revealed on click.

</details>

Footnotes

Use Markdown-native footnotes for adding references at the bottom of a page.

Here's a simple footnote,¹ and here's a longer one.²

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

Redirects

Moving page content around in The Hub? Make sure you add a redirect to the front matter so any existing links to that page can be automatically redirected to the new URL.

---
layout: page
title: Example page
redirect_from:
  - /original/path/to/page/
---

Nav

Pages and sub-directories are automatically listed alphabetically in the lefthand navigation. Whenever you create a new file within our allowlist of top level directories, the file will automatically be added to the navigation.

Exclude pages

Pages can be excluded from the navigation with nav_exlude: true in the page's front matter.

Icons

To set the icon on the top level nav links in the sidebar, add octicon: {name} to the page in the nav.yml file. Any Octicon can be used. If a custom icon is needed (i.e. Slack), please reach out in #thehub-team.

The Hub homepage is the face of our intranet and the launchpad for accessing all things GitHub. As prime real-estate, the homepage banner is meant to reiterate our focus on inclusion and making The Hub the home for all Hubbers. For example, a cause we are championing, a holiday we are recognizing, organizations we’re supporting, our current marketing campaign, or a GitHub or open source project.

Changing the homepage banner is done manually by the Internal Communications Team. Ideally, the homepage banner should be changed on a monthly basis but there is no standard expiration date. A best practice for determining when the banner should be updated is based on how relevant the message of the current banner is.

If you have an idea for a banner and artwork, please use this template to submit it to the Hub team for review.

Banners

Any net-new banners need to be 2000 pixels wide by 725 pixels tall (or equivalent aspect ration). Please give the banner a discriptive name. See below for examples, but general naming convention is banner-[your-banner-topic].

Open a PR to add the new image to the public/assets/images/banners/ directory. This can be done as part of an existing PR with content changes.

Usage

Copy the name of the file for the banner you want to use. In the front matter of your page, add or modify the banner: key with your banner name. For example: banner: banner-placeholder.png.

Consistency

The site should be referred to as The Hub
Identify GitHub employees as "Hubbers" Correct any instances of "GitHubbers" (a term used in the past).
If a "More info" section is at the bottom of each page it should be cross-referenced with as much as we can across repos, Team and GitHubber.tv. Usually a ## header.
References to HQ should be changed to San Francisco - all employees should feel equal.
Use a casual, friendly tone in all text. Use developer speak/humor when relevant.
In general lists where order/priority isn't obvious, use alphabetical order.
Refer to the Brand Guide for general grammar rules (e.g., sentence case, etc.)

Styling

The Hub uses Primer for a consistent GitHub look. Head over to their documentation to see what styles are available.

Maintainers

The designated maintainers of The Hub are @mdo and the @github/internal-comms team. However, any submissions or approvals for the Engineering Guide section are maintained by @reiddraper and @janester. As we migrate more content to include additional sections, section maintainers will be assigned to each.

This is the first footnote. ↩
Here's one with multiple paragraphs and code.

Indent paragraphs to include them in the footnote.

{ my code }

Add as many paragraphs as you like. ↩

On this page

📌 Start here! Contributing guidelines

Front matter

Content

Editing content

File names

Sentence case

Spacing

Headings

Links

Emoji

Usernames

Slack channels

Tables

Images

Dark/Light Mode Specific Images

Videos

Details disclosure

Footnotes

Redirects

Nav

Exclude pages

Icons

Homepage banner

Banners

Adding a new banner

Usage

Consistency

Styling

Maintainers

Footnotes