OpenAI Website Documentation

Reference and guidelines for creating and managing content.

  1. Introduction
  2. Best practices
  3. Page settings
  4. Formatting
  5. Updating 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 or Design team.

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

Back to top


Best practices

Writing

Content in Ghost should be formatted as Markdown[1]. In the Ghost editor, select a Markdown block within the dropdown that appears when clicking the "+" button in the content area. Options for writing 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.

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 (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.

  • Before you upload, name images descriptively (robot-hand.jpg instead of IMG12345.jpg)
  • Ghost automatically populates the image path as absolute as /content/images/…; 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 haphazard 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

Back to top


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

Back to top


Formatting

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

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}$$

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>

Captions

Charter

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

Asides

An aside is useful for content which is tangentially related to the main content. It is floated in the gutters on md breakpoint and above, otherwise it exists in the flow of the document.

<aside class="aside">
    <img src="/content/images/2019/03/openai-about.jpg">
    <div class="caption">This is within an aside.</div>
</aside>

An aside is useful for content which is tangentially related to the main content. It is floated in the gutters on `md` breakpoint and above, otherwise it exists in the flow of the document.

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.

<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">

Typography

OpenAI CSS contains many out-of-the-box typography classes. For more granular control, explore the type and text utility classes, where you can set font weight, style, size; letter spacing; line height; and more.

X large
Large
Medium (default)
Small
X large copy
Large copy
Medium copy
Small copy
Small caps
X small caps

<span class="xlarge">X large</span>
<span class="large">Large</span>
Medium (default)
<small>Small</small>
<span class="xlarge-copy">X large copy</span>
<span class="large-copy">Large copy</span>
<span class="medium-copy">Medium copy</span>
<span class="small-copy">Small copy</span>
<span class="small-caps">Small caps</span>
<span class="xsmall-caps">X small caps</span>

Color

Specify background color (.bg-{color}) or foreground color (.color-{color}). where {color} is an OpenAI branded color. View the full list of colors.

.color-bright-red
.bg-medium-wash
.bg-dark-blue .color-white
<div class="color-bright-red">.color-bright-red</div>
<div class="bg-medium-wash">.bg-medium-wash</div>
<div class="bg-dark-blue color-white">.bg-dark-blue .color-white</div>

The foreground color fg is also accessible as utility classes for background or foreground at 5% opacity intervals.

.color-fg-40
.color-fg-60
.bg-fg-5
<div class="color-fg-40">.color-fg-40</div>
<div class="color-fg-60">.color-fg-60</div>
<div class="bg-fg-5">.bg-fg-5</div>

Spacing

Margin and padding utility classes can be mix-and-matched to create the desired spacing, based on units equivalent to the line-height of the base font size. Specify:

  1. property (margin m or padding p)
  2. optional direction (t, b, l, r, y, x)
  3. optional breakpoint (sm, md, lg, or xl)
  4. number of units (1/3, 0.5, 1, 1.5, 2, etc.)

If no direction is specified, the spacing property will be applied to all directions. Use n for negative units (margin only). See the full list of spacing units.

Spacing class examples

Class Description
mt-1 margin top 1 unit
mb-2 margin bottom 2 units
my-0.5 margin top and bottom 0.5 units
ml-n1 margin left negative 1 unit
mr-lg-2 margin right 2 units at lg breakpoint and above
p-0.25 padding 0.25 units (in all directions)
px-1/3 padding left and right 1/3 units
pb-2 pb-md-0 padding bottom 2 units, but padding bottom 0 at md breakpoint and above

Layout

By default, post content is contained within a .content container. To break out of this, use a .full or .wide element.

.full
.container
.content nested under .row
<div class="full bg-light-wash">
    .full
    <div class="container bg-medium-wash">
        .container
        <div class="row">
            <div class="content">
                <div class="bg-dark-wash">.content nested under .row</div>
            </div>
        </div>
    </div>
</div>
.wide
<div class="wide bg-medium-wash">
    .wide
</div>

Grid

Similar to Bootstrap, OpenAI CSS supports a responsive flexbox grid based on 12-columns, with breakpoints at sm, md, lg, and xl.

Basic columns
.col-8
.col-4
<div class="wide">
    Basic columns
    <div class="row">
        <div class="col-8">
            <div class="bg-medium-wash">.col-8</div>
        </div>
        <div class="col-4">
            <div class="bg-medium-wash">.col-4</div>
        </div>
    </div>
</div>
Responsive columns
.col-12 .col-md-6 .col-lg-2 .col-xl-4
.col-12 .col-md-6 .col-lg-5 .col-xl-4
.col-12 .col-md-6 .col-lg-5 .col-xl-4
<div class="wide">
    Responsive columns
    <div class="row">
        <div class="col-12 col-md-6 col-lg-2 col-xl-4">
            <div class="bg-medium-wash">.col-12 .col-md-6 .col-lg-2 .col-xl-4</div>
        </div>
        <div class="col-12 col-md-6 col-lg-5 col-xl-4">
            <div class="bg-medium-wash">.col-12 .col-md-6 .col-lg-5 .col-xl-4</div>
        </div>
        <div class="col-12 col-md-6 col-lg-5 col-xl-4">
            <div class="bg-medium-wash">.col-12 .col-md-6 .col-lg-5 .col-xl-4</div>
        </div>
    </div>
</div>
Equal-width columns
.col
.col
.col
.col
<div class="wide">
    Equal-width columns
    <div class="row">
        <div class="col">
            <div class="bg-medium-wash">.col</div>
        </div>
        <div class="col">
            <div class="bg-medium-wash">.col</div>
        </div>
        <div class="col">
            <div class="bg-medium-wash">.col</div>
        </div>
        <div class="col">
            <div class="bg-medium-wash">.col</div>
        </div>
    </div>
</div>
Variable-width columns
.col
.col-auto
<div class="wide">
    Variable-width columns
    <div class="row">
        <div class="col">
            <div class="bg-medium-wash">.col</div>
        </div>
        <div class="col-auto">
            <div class="bg-medium-wash">.col-auto</div>
        </div>
    </div>
</div>

Back to top


Updating content

About page timeline

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 papers

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."

Back to top