-
Notifications
You must be signed in to change notification settings - Fork 1
Home
Siteleaf is a content management system (CMS) for Jekyll websites that makes it easy for non-developers to take advantage of the simplicity of Jekyll. Jekyll re-generates the entire website each time a change is made meaning that our web server has to do 0 work to deliver any given page to a user. This means the website will always be super fast. Additionally, we have also placed it behind a worldwide cache offered by Amazon called CloudFront. This means that if you are in New York, you'll be served the website by a server in New York. If you're in France, the server will be in France. In Australia, China... etc. You get the idea.
All of this to say, the Power Report website will be very fast for anyone, anywhere.
If you don't yet have an account, you'll need to talk to @annlarson or @marcondag and have one of them make you an account. If you know how, you can create a GitHub issue in this repository and add one of them as an assignee in the toolbar on the right-hand side and they should be able to get to it. Once you have an account you'll be able to edit, upload, publish and unpublish content on the Power Report.
Note to current admins
You may add new users through the left hand sidebar'sUserssection. Once there, insert the new user's email address and clickInvite. Note, however, that due to our current Siteleaf subscription level, all users will be administrators. This means that they will be able to remove other administrators (except Ann as she is the owner and cannot be removed), add, publish, and delete content at will, without any oversight. Consider that instead of making someone a user account, it might be better to have them write up the post, interview, etc, in a document and one of the current administrators can do the work of publishing & editing. This follows the general principle of only granting access on a need basis. This reduces the possibility of someone's account being used by a malicious actor to vandalize the Power Report website.
Because Siteleaf does not support custom plugins at the tier that we are paying for, we do not depend on it to publish our site for us. To get around this limitation, we manually publish the website using GitHub and CircleCI each time an update is made. This means every time you hit the save button on a published page, the site will automatically begin to be updated!
Unfortunately, this also means that Siteleaf's publishing will always fail with the following error:
Invalid Markdown processor given: DebtCollective (RuntimeError)
To be able to track the publishing of the site, please join the #power-report-status channel in Slack. We publish a notification there every time the site is updated. The channel is a little noisy so if you join it I'd recommend muting the notifications in it and just checking it when you're making changes to the site.
There are some other providers that offer similar functionality to Siteleaf (Forestry, namely), that do not seem to have these limitations. However, it may not be less expensive than just upgrading our Siteleaf tier. Regardless, it'd be best to stabilize the platform before attempting to make any changes to the tools we use to publish it.
When a new post of any kind is created, it will take roughly 5 to 7 minutes for the changes to be pushed up to our web servers. This is the time it takes for Siteleaf to deliver the changes to GitHub, for our tools to build the new version of the website and then deliver that to the servers.
New pages should be accessible through a direct link to them immediately after the website is built and delivered to the servers. It may take up to 10 minutes for the new post to appear on the homepage or other pages where you'd expect a link to them to show up. This is a latency caused by the caching strategy which only checks for changes every ten minutes.
After an update is made to an existing page, the same process above happens, however, due to caching it may take up to 10 minutes before changes are visible to everyone. If you want to check something, look up how to do a "hard refresh" in your browser. After doing so on the page you are expecting changes to appear on you should see changes.
If new pages or changes are not appearing on the website after 15 minutes from when you clicked save inside of Siteleaf, contact one of the developers for them to take a look.
Note to devs:
Either one of two things happened:
- the Circle CI script failed or
- the CloudFront cache isn't work properly.
If Circle CI is failing, try troubleshooting it & contact @marcondag if you can't figure it out as he wrote the integration.
If Circle CI pushed the changes and you can see them in the S3 bucket (powerreport.debtcollective.org) and you suspect it is CloudFront, try creating a cache invalidation on the object(s) that aren't seeing changes. If that still doesn't work then you can try a global cache invalidation by just passing a
*to the object list in CloudFront's invalidation dialog box. This should be a last resort. We get a certain number (~1000?) of free invalidations a month but it is per resource so if we have 500 objects in the cache we'll run through those free ones pretty quickly. After that cache invalidations get pretty expensive so we need to be judicious when using this approach. It's sort of a scorched earth.
If you want to save your work on a post to come back to it later, you may click the "hidden" option on the right-hand side below the save button and then click save. This will make the page completely inaccessible, even with a direct link.
Siteleaf has a visual editor but it's very much a beta feature and it will probably break any images you have in the your markdown. This is a huge limitation of siteleaf and if you run into trouble with this then have someone who is more familiar with Markdown take a look for you and they should be able to fix it. Generally, the problem tends to be that the visual editor tries to make changes around the square brackets by adding \ in front of each of them. If you remove these then the embedded image should work again.
You should now be able to use the built in image insterting feature Siteleaf provides through their visual editor.
The only thing to note is that when you insert the image you'll get this:
The first part, inside the square brackets, will be what screen-readers will read out when they process the image. To ensure accessibility for the visually impaired, we need to change that part to be a description of the image, like so:
Pretty much ever page type except Artwork supports adding a youtube-id. This will embed the video at the top of the page below the title. What you need to put in here is the last part of the YouTube page's URL after the v=. So if the YouTube link looks like: https://www.youtube.com/watch?v=L92ucxA492M then the youtube-id would be L92ucxA492M.
Sometimes a YouTube page will look like this: https://www.youtube.com/watch?v=L92ucxA492M&feature=youtu.be or have a bunch of other cruft after the v= part. Make sure you only take the stuff between the v= and the first & you see.
To add a line break, you need to have two spaces and a new line after the previous line. So to make a plain text list of items, it should look like this
**Schools closing**
Arizona: Tuscon, Phoenix
Texas: Austin, Dallas
New York: NYC, Buffalo If you highlight the text in the box above you'll notice the two spaces after each line.
Paragraph breaks are similar to the line breaks above, but require a whole blank line before the new paragraph starts.
This is the first paragraph.
This is the next paragraph with one blank line before the start of it.If you want to plop the plain link into a document you can just write it directly into the document like so:
This is a sentence with a link to www.google.com in the middle of it.This will look like:
This is a sentence with a link to www.google.com in the middle of it.
To hide the link behind some text, you need to use the following syntax:
This is a sentence with a link to [Google](www.google.com) in the middle of it.This will look like:
This is a sentence with a link to Google in the middle of it.
Currently the Power Report website supports several different types of page layouts. Some of them are very similar and only have slight differences. Others have significant differences that will be highlighted below. The following page layouts are supported:
- Pages
- Artwork
- Letters
- News Analysis
- Posts
- Profiles
- Special Reports
A page is a very simple, no frills page. An example is the about page. I suspect these will get a facelift at some point to have a little bit of a different feel about them (maybe bigger text, centered copy, etc). For now though, they're pretty much exactly the same as a post but without any predefined metadata fields.
Artwork is a category for featuring art by Debt Collective members and artists in solidarity with our members.
When adding new artwork, contact one of the developers to have them create appropriately sized files and upload them for you. This is necessary because all the files on the site get pushed to GitHub and GitHub has a size limit for each repository. We can request an exception but we haven't yet. Until then, due to the size of artwork files, we need to host them on S3 to keep the cost low.
src : A URL to the full resolution version of the artwork.
preview : A URL to a smaller version of the artwork that will be embedded on the web page. This is to improve load times.
artist : The artist's name
featured
: Needs to be true or false. When this is set to true it will force this artwork to appear on any page with the Featured Artwork section at the bottom.
description : A description of the image. This is what will be read by screen readers used by our blind comrades so it should be a good description.
These are interviews and Q&A type posts between Debt Collective members. A good example is Dan Hong's interview with Dawn Thompson.
The format of these posts is important and should follow:
The text for a question should go here
: The first paragraph should have a `: ` (colon and a single space) before it.
Each paragraph of the answer should have two spaces after the final line.
And the next paragraph should come after a single line break.This syntax is unfortunately complex but the simplest one of the available options. If you have a trouble a developer will be happy to help you out. We're looking into/brainstorming ways of making this simpler.
author : The name of the interviewer
sub-title : An excerpt or description of the interview. A brief and interesting excerpt should be preferred over a description. Limit these to no more than 120 characters.
interviewee-picture : A picture of the person being interviewed. You should make sure that the person's face is in the center of the picture, so crop it appropriately. The dimensions don't really matter as the website will take care of making the image the appropriate size, but a vertical portrait or square shape works best.
These are the really fun one posts and are highly stylized. There are no real examples as of right now.
Typically these will be articles that have been copied from some other news source and we're putting our analysis on the original article through a series of annotations.
To highlight any given piece of the original article, surround the part you want to highlight with ==. For example:
This part will not be highlighted. ==But this stuff here will be!==For compatabilities sake, the previous <mark> syntax will continue to work.
To add an annotation, you need to surround the text with <( and >).
This is some dumb thing a neo-con said about the debt industry.
<(NEWS FLASH: The New York Times lets neo-conservatives drive the narrative once again!)>The part between the <( and )> will appear off to the right of the paragraph that immediately precedes it in the markdown document.
For compatabilities sake, the previous <aside> syntax will continue to work.
sub-title : This should be the original title of the article. It will be displayed below our own title for the news analysis post with a red strike through the middle.
author : The name of the publication/author that wrote the original piece
youtube-id : See above re: embedding videos
image : An image to embed at the top of the post (optional)
image-description : The description of the image for screen readers. This will also appear below the image as a caption.
summary : A summary of our analysis that will appear below the title on the homepage or other places where it is listed.
These are regular blog posts without any ceremony.
sub-title : A subtitle, super short description or excerpt from the post.
author : The author of the post
youtube-id : See above re: embedding videos
image : An image to embed at the top of the post (optional)
image-description : The description of the image for screen readers. This will also appear below the image as a caption.
summary : A summary of the post that will appear below the title on the homepage or other places where it is listed.
These are video interviews with our members. They are pretty different as the content of the post isn't really important. Sometimes a video needs some context or something and it should go there. Otherwise the metadata is more important.
Anything added to this collection will be added to the list of videos on the right hand side of the member profiles index page. The most recent profile will be the one embedded at the top.
sub-title : This should be the original title of the article. It will be displayed below our own title for the news analysis post with a red strike through the middle.
author : The name of the person(s) who filmed/conducted the interview
youtube-id : See above re: embedding videos. You should follow the same guidance about getting the YouTube ID for the video.
video-description : This will appear over-layed on the video underneath the title.
Special Reports are just like posts except they have a little blue special report blob next to the title on the homepage. See the Posts section for a description of the metadata.