Khan Academy Engineering Blog
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 forge 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.
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
$ git clone https://github.com/Khan/engblog.git $ cd engblog $ make deps $ make serve
Before committing any changes, make sure to run
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:
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
- The team at KA that the author belongs to (or feels like posting under). Must be one of
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-infrastructurefor 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
If you're publishing a new blog post, make sure to update the upcoming post section first, which you can do by editing the file
src/info.py. You can find the information to update to in the publish queue -- or, at least, everything except the team, which you may need to figure out (from the list of categories above) yourself. Or better yet, ask the author! For team_class, just do
team.lower().replace(' ', '-').
If you're a KA employee, make sure to follow the remaining instructions on the forge page. This includes at least posting to the KA Engineering twitter account.