This is the source code for the Origami website as well as a place to open up issues on Origami as a whole. Please visit origami.ft.com if you're looking for the documentation.
Editing this site
This is a rough guide to editing this site, and where the content lives.
Single static pages live in the
pages folder. These each have
permalink frontmatter set to indicate where the rendered page will live on the site. We store them in this folder to avoid cluttering up the root path of the repo.
Technical documentation pages
The actual documentation for Origami lives in the
_tutorials folders. This should contain an easier-to-digest version of the Origami specification as well as in depth guides on how to use Origami.
The formal Origami specification lives in the
Blog posts live in the
_posts folder and the file names are prefixed with the post date. Posts can include an
author frontmatter value to signify who wrote the post, and an array of
tags which are displayed alongside the post. The
description frontmatter is particularly important for blog posts as it is displayed as a preview on the blog listing.
Newsletter blog posts must have an accompanying email, this is outlined in the section "Authoring and sending a newsletter".
Authoring and sending a newsletter
Writing the Origami monthly newsletter extends the instructions for blog posts, as we also publish an email to the FT's Product and Technology department. The guide here won't cover the content of the newsletter, see the original proposal for that.
Branch off of master and create the required files. The format for the newsletter is strict, and you should probably copy an older newsletter to make sure it's correct. You need to create two files in this repo, replacing the date as appropriate (set to the expected published date): -
_posts/YYYY-MM-DD-newsletter.md: for the blog post on the website -
_emails/newsletter-YYYY-MM.html: for the email we distribute
Write the newsletter. This is best done in the blog post, as this is standard Markdown. The email newsletter relies on some pretty gross Liquid templating to ensure that we avoid copy/paste errors in the HTML. Sorry. The email also has required front-matter: a
titlewhich becomes the subject of the email, and
companion_post_urlwhich is used to link to the blog post and should be the full URL.
Open a pull-request on this repo, and get it approved by another member of the team. Once approved, merge into master. This must be done on or after the publish date indicated by the post file name. The blog post is now published, check it on the live site.
Now you'll need to review and publish the email, this is done in a locally cloned copy of the repo (this step may be automated later when we have confidence in the email format). You'll need to have npm dependencies installed:
Run the following command:
EMAIL_SOURCE_HTML=YYYY-MM make email-generate, where
MMcorrespond to the year and month of the newsletter. This will output details of the email that is to be sent including links to review the conent. It is very important to review these files, the HTML in-browser and the plain text in a text editor. If you want to test the newsletter email prior to publishing, you can use the a
EMAIL_LOCAL=trueenvironment variable, though it is not possible to actually send an email with this variable added.
Once reviewed, run the following command to send the email:
EMAIL_SOURCE_HTML=YYYY-MM EMAIL_RECIPIENTS=XX@XX EMAIL_API_KEY=XXXXXX make email-generate-and-send, where
MMcorrespond to the year and month of the newsletter,
XX@XXis the recipient email, and
XXXXXXis an email platform API key (you can find this in the shared Origami lastpass).
The email is sent! Enjoy
- Install dependencies:
- Build and serve the site:
- Visit http://localhost:4000/