This blog runs on Jekyll and GitHub Pages. Posts are written in markdown.
If you are actively involved in improving the infrastructure of this project, you should read the documentation for these platforms thoroughly (they're pretty short as it is). If you are simply contributing, this guide should be enough to get you going.
- Add yourself as a contributor on the blog (See an example file)
- Publish a new post (See an example file, published version)
- Dev blog (for employees only, where to preview posts before going live)
- Internal image uploader (for employees only, must be on VPN or on office network)
- Company editorial board and calendar (post ideas and see schedule)
This is the official company blog for Stack Exchange. Everything related to new features, announcements, engineering projects, and all things Stack Exchange live on this blog. The contributors on this blog are Stack Exchange employees, but in the future, we may open this up to outside contributors as well.
- Go to our Blog Editorial and Calendar Trello board and add any and all of your ideas to the
Ideas/Backlogcolumn. - In the card, you need to do the following (see example here):
- Add yourself as a member and anyone else you think might be helpful in writing the post
- Designate a single author in the description that is going to be responsible for writing the post
- You should also put a description of what the post is going to be about
- Add any relevant tags like
announcement,diversity, orengineeringonto the card
- As cards get added, Rachel Maleady and Jon Chan will go through all the cards in the
Ideas/Backlogcolumn, and move anything we want to discuss into theBeing Scheduled This Weekcolumn. Sometimes things that have to get scheduled (like the regular podcast posts) will get added directly into this column. If your card got moved into theBeing Scheduled This Weekcolumn, feel free to join Rachel and Jon in the meeting to chat about your ideas. - Every week during the editorial meeting, Rachel and Jon will move cards from
Being Scheduled This Weekinto aPublishing This MonthorPublishing Next Monthcolumn. Once that's done, you should start writing your post and we're going to ocassionally heckle you about it until it's published :) If you have trouble figuring out how to do this, feel free to ask Jon or Rachel. - As you write your post, feel free to commit it. Jon and Rachel will constantly be looking at what gets added here and nothing will get published publicly until we manually hit the production build, so don't worry too much about making mistakes and stuff. As you write and make commits, it automatically builds on an internal dev tier at http://dev.blog.stackexchange.com/, so if you want to see what it looks like before you publish, you can see it there.
- Once the deadline arrives, we'll check with you to make sure it's exactly as you like it, then we'll push to production!
###1. Add yourself as a contributor with an people file
Add yourself as a contributor on the blog (See example file)
You need to create a new markdown file with your username in the _people folder to be included as a contributor on the blog. For example, Jon Chan uses the username jonhmchan so he would create a new file named jonhmchan.md. In the content of this markdown file should be the following (you don't need the square brackets):
---
layout: author
id: [username, must be same as file name]
name: [your full name]
job: [job title]
avatar: [url to an image to be used with all your posts. Most people use their Gravatar pic url]
twitter: [your twitter handle, without the @]
github: [optional, your github user name]
stack: [optional, url to your stack overflow/exchange profile]
youtube: [optional, url to youtube video or playlist]
website: [optional, url to your personal site]
---
So Jon Chan's jonhmchan.md file would look like:
---
layout: author
id: jonhmchan
name: Jon Chan
job: Developer, Head of Evangelism
avatar: https://www.gravatar.com/avatar/0090f1f22a03e38ca61dc955e1d0a346?s=100
twitter: jonhmchan
github: jonhmchan
stack: http://stackoverflow.com/users/1043674/jon-chan
website: http://www.jonhmchan.com/
---
How to add this file
If you are a developer, you can do this simply by submitting a PR or adding this file to the _people directory. If you are not a developer, you can use this link on GitHub to create this file, then submit your changes by adding a commit message like Added [your name] to authors and hitting the Commit new file button:
Once you do commit this file, you may be asked to create a pull request. Click Create Pull Request to do so:
Then on the next screen, you can submit the pull request:
###2. Publishing a post
Publish a new post (See example post file, published version)
To create a new post, you need to create a new markdown file with a particular format in the _posts folder in order to publish. The file needs to include the date and title seperated by dashes: YYYY-MM-DD-Title-With-Dashes-As-Spaces.md. For example, Jon Chan published a post on January 28th, 2014 titled "My First Six Weeks Working at Stack Overflow". So the title of his file was 2014-1-28-My-First-Six-Weeks-At-Stack-Overflow.md. In the content of this markdown file should be the following (you don't need the square brackets):
---
layout: post
title: [title of your post]
author: [your author id]
date: [the date you want this to be published in YYYY-MM-DD HH:MM:SS format. If in the future, will be put in draft mode and will publish at that time. Optional, you can remove this whole line]
draft: [true or false, will hide the post from any display lists. If not a draft, you can also remove this whole line]
hero: [url of a high quality hero image to be used for your post. Optional, you can remove this whole line]
source: [url of the original post so a source banner will be added to the post. Optional, you can remove this whole line]
description: [a description that will show up in search results, up to 160 characters. Optional, you can remove this whole line]
tags: [what channel this post belongs to (engineering/company), and any related tags, required]
---
[Content of your post in markdown]
So Jon Chan's post 2014-1-28-My-First-Six-Weeks-At-Stack-Overflow.md would look something like the following:
---
layout: post
title: My First Six Weeks Working at Stack Overflow
date: 2014-01-28
author: jonhmchan
hero: https://ununsplash.imgix.net/photo-1416339306562-f3d12fefd36f?q=75&fm=jpg&s=dd8bffcffb3d622bea05c74d203121c6https://unsplash.imgix.net/photo-1416339442236-8ceb164046f8?q=75&fm=jpg&s=8eb83df8a744544977722717b1ea4d09
source: http://www.jonhmchan.com/blog/2014/1/16/my-first-six-weeks-working-at-stack-overflow
tags:
- engineering
- onboarding
---
I started working at [Stack Exchange](http://www.stackexchange.com/) (which many know for/as [Stack Overflow](http://stackoverflow.com/)) as a software developer just six weeks ago. This (lengthy) post is about a number of things: what it was like relearning a lot of what I know about web development, the challenges and resources I encountered doing so, and a few pointers others might benefit from on-boarding on a new development team.
...
You can see what this post looks like as a full markdown file by going to this link.
How to add this file
Adding this file is very similar to adding your original authors markdown file. You can use git to add your post markdown file in the _posts folder, or you can use the GitHub user interface to do so. Note that the moment you commit this file, it will be published to the blog.
Writing your post with Markdown
Everything following the second set of three dashes in your post markdown file will be the content of your post. We use markdown to format the post.
Uploading Images
Adding images to your post requires you to upload the image and use the URL in your markdown. We have an internal image uploader tool that you can access at the following link: http://blogtools.ds.stackexchange.com/ . You will need to be connected to the VPN or wired to the internal office network.
In addition to the different methods, there are some basic guidelines to what is allowed:
- Your images should never be bigger than 50KB
- Maximum width of any image should be 800 pixels
- Do your best to avoid images with text in them, it makes it difficult to use as a background
Note that using our internal tool will host the images in the right place and also deal with resizing/compressing.
Drafts
You can always set your posts as drafts. You can do this by adding the line draft: true into the metadata of your post. Putting your post into draft mode means it won't show up anywhere that blog posts are listed, but you can still see the post at its individual URL.
Adding tags
Every post is required to have at least one tag: either company or engineering depending on which channel it belongs on (it can also have both). You can then add any additional tags afterwards.
When writing a new post, you can add listed tags at the top of the post markdown file.
---
layout: post
title: [title of post]
author: [author id]
tags:
- [tag1]
- [tag2]
- [tag3]
---
Where to get good hero images
- Unsplash
- You can also upload them to
imagesand it will be accessible using/images/path-to-your-image - Search our internal drive for "Photos" there are a number of professional photos we have in store
Code snippets
Jekyll has support for code snippets and highlighting built-in using Pygments. To include a codeblock with in your markdown, use the following syntax:
{% highlight [language] %}
[Your code here]
{% endhighlight %}
So if you were going to be including a snippet of Ruby code in your post, it would look like:
{% highlight ruby %}
def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
end
{% endhighlight %}
If you are interested in making changes to the design, functionality, or structure of the blog, you're going to need to set up a local environment and understand some of the technologies behind the site.
1. Install Jekyll and dependencies. First thing you're going to need to do is set up Jekyll and the appropriate dependencies so you can develop locally. The easiest way to install everything is to use RubyGems and follow the instructions on the Jekyll website. In addition to the basic Jekyll installation, you also need to install a few dependency gems. After install RubyGems on your machine, you really only to run two basic commands:
gem install jekyll
gem install jekyll-sitemap
gem install jekyll-redirect-from
gem install rouge
2. Run a local version of the blog. Using Git, clone the latest version of this repository to your local machine using the following command:
git clone https://github.com/StackExchange/stack-blog.git
Then go into root of the folder and run jekyll serve:
cd stack-blog
jekyll serve
This will get a local version of the blog running on your machine, accessible on localhost:4000/blog/
3. Read up on the documentation. To really understand how to develop the site there are a few things you're going to need to read up on to make meaningful changes:
- Jekyll The static site generator used for the site
- GitHub Pages How the site is hosted
- Liquid The templating language used with Jekyll by Shopify
- Stack Overflow Careers Pattern Library Our pattern library by our designers that includes a full LESS framework for rapid development