This repository holds the files for MDST's github pages website.
This website uses jekyll
, and is hosted on Amazon S3. Here are a list of things which must be installed in order for you to test this website locally and push your changes to the live site.
s3cmd
: Can be installed viabrew
andapt-get
.jekyll
: Can be installed using RubyGems, which comes with an installation ofruby
, which is pre-installed on MacOS. Install with$ gem install jekyll bundler
git
: If you haven't used git before, I'm sorry, but you were gonna have to learn it at some point.
The MDST website has the nice feature of supporting blog posts. Here's how you do it. If you don't want to think about any of this that hard, the easiest thing to do will be to look for a post similar to the one you want to write, copy it, and change the file name.
If you just want to write a post as fast as possible, here's the quickest way to do that.
- Make sure you download and install the pre-requisite programs listed above.
- Clone this repository. If you have already cloned it and haven't updated recently, run
git pull
in the folder to update.$ git clone https://github.com/MichiganDataScienceTeam/MichiganDataScienceTeam.github.io.git
- Copy a post from
_posts/
and change the filename according to the pattern of the other files. - Make your own branch and push it to the repo.
$ git checkout -b my-new-post
- Change the variables at the top of the post between the two
---
dashes. - Preview your post.
$ jekyll serve
- Use your browser to navigate to
localhost:4000
- Add your changes, commit your changes locally, and push your changes to GitHub.
$ git add _posts/the-post-that-you-made.md
$ git commit
$ git push -u origin my-new-post
- Go to GitHub and create a pull-request. If you have successfully pushed your branch and it contains changes, there should be a button under the name of the repository towards the top left corner of the screen.
- Add some details and I'll merge the branch into master if it all looks good.
- After the branch is merged into master, you may run
$ ./update-live-site
if you have the password. Otherwise, someone with the password will update. All this said, you can actually run that script at any point, but until I move the script to an AWS Lambda function it will remain in the project repo.
Notice the /_posts/
directory. Inside, you will find files with the format YYYY-m-d-unique-title.md
. These are our blog posts, written in a markup language called markdown
. Markdown files in our repository have the extension .md
. Let's take a look at /_posts/2016-5-20-new-website.md
.
---
layout: post
title: "This is our New Website!"
excerpt: "... It's still a work in progress."
share: false
author: alex
image:
feature: construction.png
tags: [website, news]
---
If you are reading this, then ...
Alright, don't be afraid, but there's a bit to unpack here. At the top of the file, we see a bunch of key-value pairs between two sets of three dashes ---
, one on line 1
and the other on line 10
. The syntax of these configuration options is yaml
(Yet Another Markdown Language), which is similar to json
and xml
in the way that it is merely a way of organizing data that humans can read quite easily. yaml
.
Many of these options are pretty self explanatory, but I'll explain a few that aren't.
tags
:: This is for search engine optimization. Think of them as keywords for a research paper.image
:: Here, I am using thefeature:
child value, and setting it equal to an image calledconstruction.png
. This adds a really wide picture to the top of the page. Replacingfeature:
withheading:
will add the photo to the top of the post in a way which doesn't stretch across the top of the article. Try both out and pick which one you like. Be sure that the image you wish to display is located in/images/
.author
:: This is a cool one. If you add your information to the/_data/authors.yml
file, you will be able to specify your name in thename:
variable and see that the post is credited to you.share
:: This should be set tofalse
until further notice. We haven't configured these properly yet. Maybe one day.layout
:: This should always bepost
.