ello/wtf repository overview

⁠WTF — Static content for Ello

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⁠.

Docker Hub⁠

⁠Getting Started

There are two options for running WTF for local development:

⁠Making changes & previewing them locally with Docker

This is an easier alternative to the Jekyll install option below.

1. Download and install Github for Mac⁠
2. Download and install the Atom Editor⁠
3. Download and install the Docker Toolbox⁠
4. Create a Docker Hub account⁠ and ping [email protected]⁠ to get added to the Ello account
5. From Github for Mac, sign into your Github account. Click the + button in the upper left, switch to the Clone tab, and clone the wtf repository.
6. 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.

⁠Installing & running Jekyll natively

⁠Installing Jekyll:

This Jekyll⁠ install relies on a few different gems (in addition to Jekyll), so be sure to run bundle install:

• $ bundle install

⁠Running Jekyll Locally:

• $ 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

⁠Content Workflow (for Ello staff)

1. Edit the master branch in Github. Make sure no one else is editing so you don't collide.
2. Commit changes, check CircleCI to see if changes pass. The site is linted through html-proofer⁠ to check for build errors and broken links.
3. See how changes look on the staging server⁠.
4. Deploy master branch on Heroku.

⁠Authoring Posts & Pages

⁠Filename:

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.

⁠Post Metadata:

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
# page header ----------
header_image: header_post-default.png
header_credit: gb
header_credit_post: https://ello.co/gb/post/8s1kiwzxlnjd_yxhd3piza
header_credit_image: header_post-default_avatar.gif
# place header/avatar images in: _assets/images/page-headers/posts
---

• layout: this should always be set to post
• 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 or MDT)
• 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 the position 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)

⁠Page Headers

• header_image: a full filename for an image is expected here (i.e. header_post-help-by-gb.png) – the image should be located in _assets/images/page-headers and then either categories or posts
• header_credit: the username (without the @ sign) of the person you would like to credit the header image to
• header_credit_post: the post the image came from — a full link (https://ello.co/gb/post/8s1kiwzxlnjd_yxhd3piza) or simply the token (8s1kiwzxlnjd_yxhd3piza) works
• header_credit_image: a full filename for an image is expected here (i.e. header_post-avatar-gb.png) – the image should be located in _assets/images/page-headers and then either categories or posts

⁠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 normal title 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.

⁠Post Categories:

Available categories (anything else will be ignored and not appear on the category lists)

• about
• help
• policies
• resources

⁠Post Content:

All content goes below the Post Metadata and is formatted with Markdown.

Markdown Docs⁠

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.

Images should be called in Markdown format (with a liquid asset_path call baked in: ![Alternate text for accesibility]({% asset_path image-filename.png %})

⁠Emoji

Emoji support is baked in, just like the main site. Use colons to wrap the emoji you want⁠ to use: :bread: or :ello: :bread: :+1:

⁠License

WTF is released under the MIT License⁠

⁠Code of Conduct

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.