OpenAI Website Documentation

Reference and guidelines for creating and managing content.

Introduction

The OpenAI website runs on the Ghost platform. Template files are managed in the openai.com GitHub repo.

To add or edit content, visit the admin interace at openai.com/ghost. If you don't have credentials, please ask a member of the Communications team.

To file a bug report or request a feature, please create an issue in GitHub.


Writing

Writing in Markdown in Ghost.

Content in Ghost must be formatted as Markdown[1]. Suggested writing workflows include:

  1. Write and make edits directly in the Ghost editor
  2. Write in your text editor of choice (recommended when making large-scale formatting changes) and copy-and-paste into Ghost. You'll still need to use the Ghost editor to upload images.
  3. Write in Google Docs, and then run a script to convert it to Markdown to copy-and-paste into Ghost. Upload images via the Ghost editor.

Markdown resources

Style guide

  • Use Title Case for the title of the post
  • Use Sentence case for subheadings
  • Use one space, not two, after a period
  • Use oxford commas (sodium, potassium, and lithium), except when using an ampersand (&) when listing names of people (John, Paul, Ringo & George)
  • Use en dashes (–) for ranges of values (June–July 1967)
  • Use em dashes (—) without surrounding spaces—like this
  • Use double quotation marks (“ ”); only use single quotations (‘ ’) when nested inside a quotation
  • Use punctuation inside quotation marks, "like this," for example.
  • Be concise, specific, and use action verbs and when labeling buttons (Read Paper or Apply for Scholars 2019)

Assets

Images

Upload images into Ghost via drag-and-drop or the "Upload Image(s)" button into the Ghost editor's Markdown block.

Uploading an image in Ghost.
  • Before you upload, name images descriptively (robot-hand.jpg instead of IMG12345.jpg)
  • Ghost automatically populates the image path as absolute; remove the root URL so it starts as relative as /content/images/…
  • Use images with intent (for example, use the source image rather than a screenshot of the image) and at aesthetically-pleasing aspect ratios, such as 1:1, 4:5, 3:4, 2:3, 5:8, 9:16, 10:18, 1:2

Non-images (Amazon S3)

Upload videos, PDFs, and other assets that you can't upload via Ghost to OpenAI's openai-assets Amazon S3 bucket. Create a folder named using the page URL of the post. For example, upload paper.pdf for a blog titled "My Post" with the slug my-post to:

Amazon S3/openai-assets/my-post/paper.pdf

In your post, link to the corresponding CloudFront URL[2], which is optimized for delivery speed. For the previous example this would be:

https://d4mucfpksywv.cloudfront.net/my-post/paper.pdf

Page settings

Access the page settings panel in Ghost via the "Settings" icon in the top right of each post.

Featured Image

Used as the default social image, as well as the default image for the post header when using a Template that support an image.

Page URL

Choose a page URL (slug) that's human-readable, short, and memorable. For example, for a post titled "OpenAI Robotics Symposium 2019," a good slug is symposium-2019, viewable at openai.com/blog/symposium-2019/.

Tags

Aside from normal tags, you can apply hidden tags (prefixed with #) to further customize your post.

Tag Description
#header-twitter-image Use Twitter image as image in template header instead of Featured Image
#header-og-image Use Facebook image as image in template header instead of Featured Image
#header-custom-media Use .js-custom-media element in the body as media (image, video) in template header instead of Featured Image
#header-large-excerpt Larger excerpt in header
#header-hide-excerpt Hide excerpt in header if it exists
#header-custom-excerpt Use .js-excerpt element in content as excerpt
#header-large-title
#header-small-title
Overrides default title size per template, where necessary
#header-show-authors Show authors in header (hidden by default)
#footer-hide-authors Hide authors in footer (shown by default for posts)
#footer-random-authors Randomize list of authors
#release Mark post as a release
#release-video Mark release post with video as cover
#release-light Mark release post with light-colored gradient background
#release-no-background Mark release post as one without a gradient background
#no-sticky-nav Disable sticky nav bar at the top of the page
#card-image Show image for this post in the blog index

Excerpt

Optionally add an excerpt, which appears below the title (300 character limit, no links allowed). To add a custom excerpt use the #header-custom-excerpt tag.

Authors

Add each of the post authors (or use OpenAI for general posts). If an author is not a staff user, ask a Ghost administrator to invite them.

Code Injection

Use the Page Header {{ghost_head}} to inject post-specific styles (wrapped in <style> tags or an external <link>) and the Page Footer {{ghost_foot}} to inject post-specific scripts (wrapped in <script> tags).

Template

The template specifies the header type. Use in conjunction with tags to further customize.

Template Description
Default Standard template
Banner Full-width banner image in header
Center Centered header
Image (0 3) 3-column-width image in header, left-aligned
Image (0 6) 6-column-width image in header, left-aligned
Image (0 8) 8-column-width image in header, left-aligned
Image (3 6) 6-column-width image in header, center-aligned
Image (3 9) 9-column-width image in header, right-aligned
Image (6 6) 6-column-width image in header, right-aligned
Release Used for #release posts; header utilizes a cover image and optional gradient background

Basic formatting

In addition to standard Markdown components, you can use HTML tags and CSS classes from the OpenAI CSS framework for convenient formatting without adding custom styles. There is also support for syntax highlighting and math.

Note: this is just an overview of basic formatting. To see all available classes, see the OpenAI CSS framework.

Captions

Image alt text

This is a caption. Try to keep it short.
![Image alt text](/content/images/2019/03/openai-about.jpg)
<div class="caption">This is a caption. Try to keep it short.</div>

Buttons

Default Padded Left icon Right icon
<section class="btns">
    <a href="#" class="btn">Default</a>
    <a href="#" class="btn btn-padded">Padded</a>
    <a href="#" class="btn btn-padded icon-code">Left icon</a>
    <a href="#" class="btn btn-padded icon-external right">Right icon</a>
</section>

A post footer includes the list of authors, included by default. If you'd like to specify additional items such as acknowledgments and credits, include a .post-footer element at the very end of the content.

<footer class="post-footer js-post-footer">

<!-- footer item -->
<div><hr><div class="row">
<div class="col">Acknowledgments</div>
<div class="col">John, Paul, Ringo & George
</div>
</div></div>

<!-- another footer item -->
<div><hr><div class="row">
<div class="col">Design</div>
<div class="col">Sonny & Cher</div>
</div></div>

</footer>

With footnotes

If you have footnotes in your Markdown, you'll need to include a .post-footer element with a special footer item that contains unclosed tags.

<footer class="post-footer js-post-footer">

<!-- footer item -->
<div><hr><div class="row">
<div class="col">Acknowledgments</div>
<div class="col">Peter, Paul & Mary</div>
</div></div>

<!-- special footer item for footnotes -->
<div data-order="-1"><hr><div class="row">
<div class="col">Footnotes</div>
<div class="col">

Syntax highlighting

There is support for syntax highlighting within code blocks via Prism. Available languages are: python, latex, bash, c and related, html and related, css, and javascript.

Math

There is support for TeX-style math via KaTeX. Delimit inline equations with $ $ and display equations with $$ $$. Wrap content in a .no-math class to disable math.

An inline equation: $x=\frac{1+y}{1+2z^2}$. A display equation:

$$x=\frac{1+y}{1+2z^2}$$

An inline equation: $x=\frac{1+y}{1+2z^2}$. A display equation:

$$x=\frac{1+y}{1+2z^2}$$

Updating content

About page

The timeline on openai.com/about is managed in the Ghost editor. To add an event, visit the page in Ghost, find the <ul class="timeline"> section and add HTML markup for a list item:

<li data-date="June 2019">This is my new event.</li>

Progress page

The list of papers shown on openai.com/progress is managed via papers.yml in the openai.com repo. To add a paper, you can edit it directly in GitHub and select "Create a new branch for this commit and start a pull request."

Jobs page

Content

The content on openai.com/jobs is managed in the Ghost editor. To edit copywriting, visit the page in Ghost titled "Join OpenAI", where you can make edits directly.

Teams

The canonical list of teams, descriptions, and link to recent work is managed in teams.yml in the openai.com repo. To edit or add a team, you can ask @justin or edit teams.yml directly in GitHub and select "Create a new branch for this commit and start a pull request." Team descriptions should be kept under 300 characters.

Open Positions

Open Positions are linked to the Team field that is set in Lever, unless manually overridden (for example, if you want to indicate that a Member of Technical Staff position actually includes several teams). To override the Lever Team, add an additional Lists item named Teams and list each team name (exactly as it appears in teams.yml) in separate bullets. Only teams with open positions will appear on the website.

Manually overriding teams in Lever.