Renovating osamasidat.com, Part 1: Migrating to Wintersmith

This is first part of a (hopefully) multi-part series of posts in which I outline my thought process as I renovate my personal website.

 Introduction

Back in February, I developed a website for the BabySteps project using the static site generator Wintersmith. Previously, all of my websites and webpages had simply been “hand-written” in raw HTML, CSS, and if necessary, JavaScript.

While working on the BabySteps website, I learned a fair bit about the ease of design and development that Wintersmith provided me, along with the advantages of static site generators in general. I liked the separation of concerns, namely, content and design, and made a note to myself that I would continue to explore static site generators for future similar sites. Since my personal webpage is in need of a fresh redesign, I decided to make it a candidate for this experiment.

 Goals of the renovation

Currently, my website is composed of a single webpage, as seen below (full page screenshot taken using Fireshot on Mozilla Firefox):

osamasidat.com.png

I have three broad goals for this renovation project.

As far as timeline goes, I’m not really assigning one to myself. I’ll be working on the project and this (the blog post) as I get time.

 Why Wintersmith for this project?

Honestly, it’s more about personal preferences than anything else. I can outline a few of those.

 Migrating to Wintersmith

Note 1: My work on this project can be viewed through the commits I make on its GitHub repository.

*Note: The next steps assume an already-installed instance of Wintersmith and its dependencies. For help, check out the Wintersmith GitHub Repo.

 Setting up a new Wintersmith Project

The current personal-page directory looks like this:

├── README.md
├── images
│   └── osama.png
├── index.html
└── style
    ├── fa (...) // directory for font-awesome
    └── style.css

In case something goes wrong, I would like to return things to this exact state. Hence, I’ll add tags using git:

$ git tag v1.0 master
$ git push --tags

Next, while inside the personal-page directory, I’ll create a new empty wintersmith project.

First I tried:

$ wintersmith new . -T basic

Unfortunately, that didn’t work out (Wintersmith was expecting a new, non-existing directory instead of an existing, current directory, so I appended --force.

$ wintersmith new . -T basic --force

To test it out, I ran wintersmith preview from the terminal and was greeted by the basic Wintersmith Hello World page on localhost://8080 from my browser.

Let’s take a look at the files Wintersmith generated (in addition to the ones I already had in the personal-page directory.

├── config.json
├── contents
│   └── index.md
└── templates
    └── index.jade

The config.json file, as the name implies, contains configuration options (like webpage title, wintersmith plugins, etc.). The contents folder contains all assets including images, JavaScripts, CSS, as well as the actual content, in the form of Markdown or JSON. Finally, the templates folder contains our page templates.

This is what the files look like right now:

Screen Shot 2015-05-05 at 7.00.30 PM.png

 Moving assets around

I’ll go ahead and delete the contents of templates/index.jade and contents/index.md. I’ll rename index.md to index.json (makes it easier to have my data as key-value pairs), and, for now, this will be its new content:

{
  "title": "Osama Sidat",
  "template": "index.jade"
}

In config.json, I’ll change the title variable, nested under locals, to “Osama Sidat”.

Recall that from the old structure, I had the style and images folders. I’ll move these folders under contents.

 Converting HTML to Jade

I can either try and convert all my HTML in one shot (as a first step), or convert it bit by bit. Since I would like to make any corrections along the way, I’ll opt for the latter.

If I get stuck with any snippets, I’ll use the handy HTML2Jade.

The first part (upto the head tag) is easy:

Screen Shot 2015-05-10 at 10.51.56 PM.png

I may come back and modularize this bit later (separate the meta tags and the stylesheets into their own snippets which I can simply include in index.jade.

 The main-profile section

The first part is pretty simple - more or less a direct conversion.

section.main-profile
      header
        .top
        .me
          img(src="images/osama.png")
          h2 Osama Sidat
          h6 Problem Solver
      ...

At some point, the name and tagline could be refactored into the index.json file, but not now.

Next, we have something a little more interesting (same section):

section.main-profile
      ...
      .social
          each account in page.metadata.social
            a(href="#{account.url}" title="#{account.title}" target="_blank")
              i(class="fa fa-2x #{account.iconClass}")
      ...

I replaced the repetitive markup representing my social media icons with a loop. The loop goes through every social media account and constructs the link and the corresponding icon (from Font Awesome).

The necessary data is now placed in the index.json file, contents of which can be called via page.metadata (this can be refactored later into a separate data folder, but for now, since I have everything on one page, and a single Jade template file, it doesn’t matter). Following is my update to the index.json file:

{
  ...
  "social": [
    {
      "url": "http://ca.linkedin.com/in/osamasidat/",
      "title": "Visit my LinkedIn Profile",
      "iconClass": "fa-linkedin-square"
    },
    {
      "url": "http://github.com/oosidat",
      "title": "Check out my GitHub Profile",
      "iconClass": "fa-github"
    },
    {
      "url": "http://www.facebook.com/osama.sidat",
      "title": "Vist my Facebook page",
      "iconClass": "fa-facebook-square"
    },
    {
      "url": "http://twitter.com/SammSid",
      "title": "Follow me on Twitter",
      "iconClass": "fa-twitter"
    },
    {
      "url": "http://instagram.com/osamasidat",
      "title": "Follow me on Instagram",
      "iconClass": "fa-instagram"
    },
    {
      "url": "http://www.flickr.com/photos/osamasidat/",
      "title": "Check out my photos on Flickr",
      "iconClass": "fa-flickr"
    }
  ]
}

I’ll finish up the main-profile section with the intro and the down arrow:

section.main-profile
      ...
      .intro
        p
          | Aspiring Software Developer, with a passion for solving problems.
          br
          | 4th Year Computer Science @ UWaterloo.
          br
          | Hobbyist Photographer. Tech Enthusiast. Culinary Experimenter.

      .down
        i(class="fa fa-angle-down fa-3x")

Note to self: the down arrow is a great candidate for a simple refactor using Jade’s include feature.

 The blogs section

After doing the social part above, I have a pretty good idea how to do the blog tiles.

section.blogs
      .blog-header
        .me
          h3 Blogs
          h6 I write about tech, cooking and life experiences
      .blog-content
        .tiles
          each blog in page.metadata.blogs
            a(href="#{blog.url}" target="_blank")
              .tile
                .tile-title=blog.title
                .tile-description=blog.description
      .down
        i(class="fa fa-angle-down fa-3x")

There was a redundant <div class="tile-links"></div> that I ignored during the conversion.

Here, I’m looping through the blogs array to get the link, title and description. I updated the index.json:

{
  ...
  "blogs": [
    {
      "url": "http://blog.osamasidat.com/",
      "title": "My Tech Thoughts",
      "description": "This is a new blog I started on Svbtle where I express my tech thoughts, including my development experiences, industry trends I follow, and the changes and improvements I strive to push for."
    },
    {
      "url": "http://blog.osamasidat.net/",
      "title": "Personal Blog",
      "description": "I started writing this blog at the end of my first term at the University of Waterloo. It started off with mostly my life experiences, but has now evolved to contain my culinary experiments (read: recipes) and the occasional photography article."
    }
  ]
}

 The projects section

Pretty much the same thing as the blogs section above.

section.projects
      .project-header
        .me
          h3 Projects
          h6 Demos of my code work
      .project-content
        .tiles
          each project in page.metadata.projects
            .tile-unlinked
              a(href="#{project.url}" target="_blank" title="#{project.hoverTitle}")
                .tile-title=project.title
              .tile-description=project.description
              .tile-links
                each link in project.links
                  a(href="#{link.url}" title="#{link.title}" target="_blank")
                    i(class="fa fa-2x #{link.iconClass}")

In this case, each project contains its title, URL and description, and also, an array of links (basically just two for now, the project site itself, and its GitHub repository).

Added the following to index.json (left out a couple of projects):

{
  ...
  "projects": [
    {
      "url": "http://rockslasersprofit.com/",
      "title": "Rocks! Lasers! Profit!",
      "hoverTitle": "Visit the Project Site",
      "description": "An Asteroid Prospector game developed for the NASA Space Apps Challenge 2014, which won the regional grand prize in Kitchener-Waterloo. The goal of the game is to mine as many resources as possible before fuel runs out.",
      "links": [
        {
          "url": "http://rockslasersprofit.com/",
          "title": "Visit the Project Site",
          "iconClass": "fa-external-link-square"
        },
        {
          "url": "https://github.com/oosidat/NASAHack2014-asteroids",
          "title": "Visit the Project on GitHub",
          "iconClass": "fa-github"
        }
      ]
    },
    {
      "url": "http://leaveanote.meteor.com/",
      "title": "Leave A Note",
      "hoverTitle": "Visit the Project Site",
      "description": "A simple experiment with the MeteorJS framework and MongoDB to create public sticky notes and share them in real-time with any visitors of the site.",
      "links": [
        {
          "url": "http://leaveanote.meteor.com/",
          "title": "Visit the Project Site",
          "iconClass": "fa-external-link-square"
        },
        {
          "url": "https://github.com/oosidat/meteor-leaveanote",
          "title": "Visit the Project on GitHub",
          "iconClass": "fa-github"
        }
      ]
    },
    ...
  ]
}

 Recap

Let me summarize what I did in Part 1 of my site renovation

 What I did so far:

 Unresolved Issues:


At this point, I’ve achieved (more or less) visual and functional parity between my new Wintersmith-based site and my old raw HTML site. In the next part, I’ll go through some updates in terms of content, refactoring and duplicate code reduction, before attempting to move the site to GitHub Pages.

Until next time!

 
10
Kudos
 
10
Kudos

Now read this

RoadWatch wins Canon Canada’s Through Your Lens Competition

For the past couple of months, my former teammate from the NASA Space Apps Challenge, @femion, and I have been working on RoadWatch, a project for the Canon: Through Your Lens competition. Along with six other finalists, we pitched to... Continue →