Assignment: Build a personal website in the class archive describing you and your final project.
This is actually an area where I know what I’m doing - I like to make pointless websites for fun as a form of procrastination. (Check out Science Clickbait, Lazy Baker, The Owen Tribune, Jekyll Polymer, or my personal homepage.) I opted to use a static website generator that I already know but try out a new CSS theme framework on top of it.
Site Generator: Jekyll
This site is built with Jekyll, which lets you create HTML templates for your website and write individual posts in simple Markdown. Jekyll takes care of compiling the Markdown and templates into the complete HTML web pages that you serve from your website. This creates a static website – one where each page is just a saved HTML file that the server hands to the client when asked – instead of a dynamic website, where each page is generated by a server on demand. For small, simple sites like this, static is a lot faster and can be easily hosted for free on Github.
Setup
It takes a few commands to get Jekyll installed on your respective system. In Ubuntu, it was just sudo apt install jekyll. After that, I generated the initial site with jekyll new how-to-make and served it up with jekyll serve. Serving the website means that a server runs on your local machine to generate and serve you the static html pages whenever you make changes to any of your styles, content, or templates. In your browser, go to localhost:4000 to check out the new site.
Content
Now the site needs some content. When you created your Jekyll site, there were a number of folders generated. One of these is _posts. This contains all the posts you write for your site. (Think of it like a blog.) There should already be an example post in this directory. To add a new post to your site, simply add a new Markdown (.md) file here with a name starting with the post date in yyyy-mm-dd- format. All posts will get automatically generated URLs based on the date and name of the file. Each file needs what’s called “front matter” so that Jekyll knows what to do with the file. Check out the example post to see what this looks like – it’s a bunch of parameters between lines of ---. I think the only frontmatter element required is the layout, which tells Jekyll which template to put the post into. (More on templates later.)
Not every page on your website will be a blog-style post, though – for example, an “About” page or the home page. The default site includes some examples of these, too. In the root directory of your project you’ll see index.html and about.md. If you open up about.md you’ll see that it looks like the posts, but with an additional parameter in the frontmatter: permalink. Instead of an autogenerated URL like posts get, this tells Jekyll where to put the page. index.html is similar, but this time it’s written in full HTML instead of just Markdown. What’s cool about Jekyll, though, is that you can put HTML into your Markdown files if you want, and it will still all compile nicely to HTML. The index file, which is the home/root page of your website, also shows off the power of Jekyll templates. Notice the {% ... %} and {{ ... }} tags, which allow you to do things like loop through posts, create links within your website, and display site- or page-wide information. (I’ll let you look at the Jekyll documentation for more on that. For now, the default index setup will at least let you display your posts.)
Serving the Site (on Github)
At this point, everything is just on your personal computer. The generated files are all stored in a subdirectory called _site when you run jekyll serve. (You can also generate these without running the server using jekyll build.) For some cases, you may just want to copy the contents of this folder to wherever you’re hosting your page. (This is the case if you’re hosting on Github and using plugins to create the static pages, which I haven’t talked about here.) But in most cases hosting on Github, you don’t even have to worry about the contents of the _site folder, because Github will make it automatically on its servers.
- Create a git repository in your project root folder by running
git init. - Create a file called
.gitignore(which says what files git shouldn’t put in the repository). In my gitignore, I included the lines_site/and.sass-cache/. - Create your initial commit:
- Add all the files in your project:
git add . - Commit the additions:
git commit -m "Initial commit"
- Add all the files in your project:
- Create a repository on Github. (From you profile, go to the “Repositories” tab and click the green “New” button.) Give it a name, make it public or private, and do not initialize it with a README, .gitignore, or license.
- Add Github as a remote location for your repository. From your new repository, you should see a URL to your new repo. Add it as a remote like this: `git remote
Themes and Styling
Jekyll comes with simple built-in templates and CSS to get you up and running quickly. You could start making posts right away in this built-in theme and have a halfway decent looking website. If you don’t want to dig into the fun design side but want a more slick look, there are a ton of Jekyll themes already out there to plug into your new site. Just Google “jekyll themes,” or check out jekyllthemes.org, the free section of jekyllthemes.io, or themes.jekyllrc.org.
For this site, I decided to base the look on Google’s material design. I’ve worked with this idea before when I made a Jekyll theme using Google’s Polymer library (check out the repository and a demo). I was originally planning on using that for this site, but decided the size of the compiled site with all the library components was too large for this. So instead I tried out the Materialize CSS framework, which tries to implement the material design guidelines from scratch. It’s definitely got some shortcomings (for example, it can only create a few types of cards and its typography doesn’t strictly adhere to the material guidelines), but for this project is does the trick in a reasonably small package. Plus, it provides all of the source in SASS, which is what Jekyll uses for styling. That allowed me some more flexibility in making modifications to its styling/colors and adding bits like floating images. After that, I spent too much time deciding on a color scheme for the site from the material color palette.
Useful Bits & Pieces
There are a lot of useful little things I’ve picked up during my time making Jekyll websites that make for nice-looking sites once you know the tricks. Here are a few I include in almost every site I make now.
Embedded Code with Syntax Highlighting
Jekyll also has built-in support for nice-looking code. Code embedded in a paragraph looks like this is code. All you have to do is surround a bit of text with backticks: `...`.
You can also includes blocks of language-aware syntax-highlighted code both with and without line numbers. Without line numbers:
{% highlight ruby %}
...
{% endhighlight %}creates this:
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT. This is a long line to test scrolling if it goes past the box.With line numbers:
{% highlight ruby linenos %}
...
{% endhighlight %}creates this:
1
2
3
4
5
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
Math
It’s incredibly easy to add LaTeX math to your website. All you need to do is add a script to your site that will convert certain text to LaTeX math. Add the following line to near the end of the <body> of your site (probably in the default.html template in _layouts/):
<script type="text/javascript" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML"/>There are inline equations like \( y = x + 2 \) indicated by \\( ... \\).
You can also display an equation (not inline displayed) using inline code, like \[ y = x + 4\] which you do with \\[ ... \\].
Or you can display a block of math by surrounding it with $$ ... $$. Like this:
Typography
There are a lot of different styles you can end up with from all the Markdown formatting, syntax highlighting, and any additional CSS you might add. I find it useful to keep track of what everything will look like in Markdown-based posts and pages by keeping a typography page. It’s a useful reference when working on new content. You can check out mine for this site here.
Main images
Sites with images look snazzier. When showing previews of posts on a homepage, it looks nice to include an image with it. You can do this using the frontmatter. In your frontmatter, you can include a line like this:
image: path/to/image.jpg
Then, when referencing it from a loop through posts, you can reference this as the image src, like this (if you keep all your images in the path /assets/imgs):
In the file for the post/page itself, you reference it like this:
Extra Classes in Markdown
Sometimes you want to add extra classes to objects in your post for styling purposes, like making an image smaller expandable. This turns out to be really easy to do. The following adds the small and right classes to an img tag in the generated HTML:
{: .small .right}You can then style these in your SASS/CSS files. I used these classes on this website to make images that are 50% width and float in the right side of the text.