Skip to content
Branch: master
Go to file


Failed to load latest commit information.
Latest commit message
Commit time


Khan Academy Engineering Blog

Travis build status

This repo houses the content and code used to build the Khan Academy Engineering Blog.

The instructions in this README are geared towards the general public. If you're a KA employee who wants to make a blog post, this page is your best starting point.

Who can contribute?

Anyone can contribute patches (we're open source) but posting to the blog is generally restricted to Khan Academy employees.

Serving locally

The blog is a static website built using the code in this repo, from the content that is also in this repo.

In order to build and host the blog on your computer, first clone the repo, then run make deps, and finally run make serve (if you just want to build the site into the output/ directory without serving it, run make build instead of make serve).

$ git clone
$ cd engblog
$ make deps
$ make serve


Before committing any changes, make sure to run make lint.

Responsive PhantomJS Tests

The blog has a responsive design and will resize itself to match small viewports. To ensure this remains true, Travis will run a set of PhantomJS tests to check the width of each page on the blog before updating the live site.

You can run these tests yourself by running make phantomjs-tests (you'll need PhantomJS to be installed, which is available on many package managers including Homebrew).

If your post is failing these tests, you should open up view your post with an "iPhone 5" viewport (320x568) via Chrome DevTools. Then look for an element in your page that's too wide. You can then either modify the element in your post's markup, or add styling to the src/styles/post-template.less stylesheet to fix the problem.

If you have any trouble with this, anyone on the Web Frontend team should be able to help you. John Sullivan is also a good resource.

Making a new post

Create a new file in src/posts/ with a .md extension if you want to write your post in Markdown, or an .rst extension if you want to write your post in reStructuredText. The file should contain some YAML frontmatter followed by your post's contents. For example:

title: My great post file
published_on: January 1, 2020
author: Jane Doe
team: Web Frontend
async_scripts: ["javascript/some-javascript-i-want.js"]

Hello world! I'm some reStructuredText or Markdown!

The text above the three dots is parsed as YAML, the text below the three dots is parsed as reStructuredText or Markdown depending on the file extension.

The available options of the frontmatter are:

The title of your post (should be sentence case, ie: only the first word is capitalized). Regarding length, try not to make it so long that it exceeds two lines when rendered in the sidebar of the blog.
The date your post was/will be/is published. Must be in the format Janurary 1, 2020 (ie: [Full Month] [Day], [Full Year]).
The author's name. Must exactly match one of the keys of the authors dictionary in src/
The team at KA that the author belongs to (or feels like posting under). Must be one of Infrastructure, Web Frontend, Mobile, Eng Leads, or Team Design. If your team is not listed, you can add another by adding a class to src/styles/post-template.less. Search for team-infrastructure for the relevant code.
A list of scripts to load. These will be loaded with the async attribute.

If you'd like to add support for another markup language, see Post.get_html_content() in src/


If you're a KA employee, make sure to follow the publishing instructions.

You can’t perform that action at this time.