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.

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 make serve).

$ git clone https://github.com/Khan/engblog.git
$ cd engblog
$ make deps
$ make serve

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

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.

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:

title

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.

published_on

The date your post was/will be/is published. Must be in the format Janurary 1, 2020 (ie: [Full Month] [Day], [Full Year]).

author

The author's name. Must exactly match one of the keys of the authors dictionary in src/info.py.

team

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.

async_scripts

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/post.py.

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(' ', '-').

After this, just push your changes to master. Travis will take care of everything else. You can ping brownhead (@johnsullivan on HipChat) for help if anything explodes.

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.