WTF is a Jekyll app that builds static content to be served up at https://ello.co/wtf, including help, FAQs, and about pages. It is patterned on Github's documentation workflow.
There are two options for running WTF for local development:
This is an easier alternative to the Jekyll install option below.
- Download and install Github for Mac
- Download and install the Atom Editor
- Download and install the Docker Toolbox
- Create a Docker Hub account and ping ops@ello.co to get added to the Ello account
- From Github for Mac, sign into your Github account. Click the
+
button in the upper left, switch to theClone
tab, and clone thewtf
repository. - Make changes to your local copy of WTF using Atom, then preview them in browser, restarting the container with Kitematic as needed. When you're done, commit your changes in Github for Mac and sync them to Github.
This Jekyll install relies on a few different gems (in addition to Jekyll), so be sure to run bundle install:
- $
bundle install
- $
jekyll serve
- Point your browser at: http://localhost:4000/wtf/ (the trailing slash is important)
- Content/design changes should update locally as you make them
- Edit the master branch in Github. Make sure no one else is editing so you don't collide.
- Commit changes, check CircleCI to see if changes pass. The site is linted through html-proofer to check for build errors and broken links.
- See how changes look on the staging server.
- Deploy master branch on Heroku.
All posts go in the _posts
folder and inside their respective category folder to keep things organized.
Files must end in the .md
extension and begin with a date (use the date the article was first created).
The words (and dashes) after the date make up the slug (end of the URL) for the post. For example, a filename of 2015-01-23-contact-us.md will result in a slug of contact-us. If you place this post in Help, the full URL will be: /wtf/help/contact-us.
Each Markdown post file contains meta data at the top of the file. This helps Jekyll know where to place the article on the site and when to publish it.
---
layout: post
title: "I am a title"
title_alternate: "I am a title for the title bar"
date: 2015-01-23 01:23:45 MDT
categories: about
position: 3
excerpt: "I am an (optional) SEO-friendly excerpt. Filling me out will place me in the <meta> description and as the summary for the search results page. The length can be a few sentences, but don’t make it too long!"
video: http://vimeo.com/30619461
shareable: true
---
layout:
this should always be set topost
title:
The title of your article, inside of quote marks:"I am a title"
title_alternate:
The title you wish to appear in the<title>
tag of the site:"I am a title for the title bar"
(optional)date:
The publish date of an article (or its last updated date):2015-01-23 01:23:45 MDT
(remember to include your time zone at the end: i.e.EST
orMDT
)categories:
Pick the single category for the article (see the list in the section below):policies
position:
This determines the position of the article in the category list. Lower numbers are at the top of the list. Other posts in the category are not auto-matically re-numbered, so if you want to place a new post at the top of the category, you will need to edit theposition
in the other posts as well.excerpt:
If filled out with a couple sentences, it will get used in the description<meta>
tag for the page and also in the search results display. (optional)video:
Include a Vimeo or Youtube link to feature a video at the very top of the post page (optional)shareable:
Add a social network “Share” button to the bottom of the article (optional)
Other Notes:
- Posts with future dates are ignored and not published until their publish date is reached (remember to set you time zone AND remember that times are in 24-hour format: i.e. 2pm is 14:00).
- Keep in mind that updating the post position may require updates to other articles in the list to get the ordering you desire.
- The
title_alternate
is optional. If not provided, the normaltitle
will be used in the<title>
tag. The Post category, main site title, and site subtitle line will still be appended. These are all configurable in the_config.yml
file.
Available categories (anything else will be ignored and not appear on the category lists)
about
help
policies
resources
All content goes below the Post Metadata and is formatted with Markdown.
You do not need to repeat the title of your post — it will be automatically add from the Post Meta Data. The most common sub-title or sub-section format option is the <h2>
which, in Markdown, is represented by using: ##
.
Lists (ordered, with numbers, or unordered, with bullet points) will be formatted. Code and blockquote formatting is also available.
Emoji support is baked in, just like the main site. Use colons to wrap the emoji you want to use: :bread:
or :ello:
🍞 👍
WTF is released under the MIT License
Ello was created by idealists who believe that the essential nature of all human beings is to be kind, considerate, helpful, intelligent, responsible, and respectful of others. To that end, we enforce the Ello rules within all of our open source projects. If you don’t follow the rules, you risk being ignored, banned, or reported for abuse.