Content over layout

Grading this course will not take into account how beautiful results of the work are formatted. We more easily focus on content by using Markdown, an increasingly popular language used to document code and/or write blogs published on the web.

Markdown is convenient as a tool to publish on the web, especially when used in combination with GitHub Pages and git

Note: if an assignment pages include links, you are supposed to have a look at those before proceeding!

Equating webpages to files in a GitHub repository means that we edit and publish a website the exact same way as we version our code: git add, git commit, and git push the website, collaboratively and versioned. When setup correctly, a tool called Jekyll will automagically convert the markdown into HTML (without you doing anything, Jekyll will run at the Github servers upon git push).

Github for Education

Did you already request your github student pack? You might want to visit github for education to get benefits like private repositories. (BTW, all repositories created in the course are private unless you change that, so no worries about your future career if you write silly things here).

If you are not yet fluent in git and Github, then go ahead and study the online training material provided by Github. If you are unhappy working with the command line (a skill which I do recommend taking the effort to acquire), consider Github’s OS X or Windows tool suites (the Windows one is convenient, but I never use it really).

Earlier (on Brightspace), I already pointed you to MIT’s The Missing Semester of Your CS Education, which includes both commandline and git lectures. Recommended stuff!

How to Create a Blog Post

The goal in this first assignment is to just complete your first repository that contains a simple site, composed in Markdown, published online for free; make sure the process is familiar. Use the results of assignment one as your personal course website and blog, and deploy the same steps in the rest of the course to bootstrap new blog posts, one for every real course assignment.

So, after familiarizing yourself with git (or refreshing your memory) with the resources above, continue to write the first post on your blog:

  1. Follow the link to the Classroom for Github Bigdata Blog 2020 assignment, login with your github account, and accept the assignment. This creates a private repository under the rubigdata “organization”, specifically for this assignment. This newly created repository rubigdata/big-data-blog-2020-USERNAME contains the structure that you use throughout the practical assignments for the course.
  2. Go to your Github repository on Github (you can follow the link that is shown after accepting the assignment) and navigate to the settings tab. Scroll down to the Github Pages settings and select master branch /docs folder as source to enable Github pages. After a little delay your repository should appear on rubigdata.github.io/big-data-blog-2020-USERNAME.
  3. If you would like your blog to look better than plain HTML, select a theme in your repository settings after enabling Github Pages.

Editing the Blog post

In order to add your own content you should now clone the private assignment repository. The README.md demonstrates some Markdown markup that you may use. The docs/ directory contains the Github Pages source for your blog (if you followed the instructions above).

Proceed as follows:

  1. Edit docs/index.md to include some basic information about you (name, student number, course programme), and create a table of contents (ToC) (just use a bulleted list) with at least one link to a (so far non-existent) HTML file; that you will have Jekyll generate in the next step.
  2. Create a new markdown file, do the git add, git commit, git push sequence, and Jekyll will turn the new .md file into a .html file with the same name - the latter is what you should link to in the ToC.
  3. Create that blog post, including some extra information about yourself, e.g., hobbies, favourite study/sports/student association, why you follow this course, etc.

Finalize the test assignment

If you are just starting out using git, it is fine to use just simple markup and limited styling. Have you been committing and pulling for months or even longer, then you should figure out how to use the Github pages features for a blog series instead of having to create separate files manually (background info and this excellent blog).

See also

And