HTML-Tricks

Creating a new site can be exciting. No matter what you need a site for, whether you are a student looking to impress future schools and employers with a personal blog, or an established professional trying to share your knowledge with others, this article is for you. In this post, I will walk you through how I created this HTML-Tricks blog site, and how you can do it too.

Planning Makes Perfect

The first step before beginning anything is to plan it out, and this applies especially to websites. It is not necessary to make your wallet cry by utilizing a design studio like the products offered by Adobe. If you know HTML and CSS already, then good for you. But for others, it may simply be too time-consuming to create a site from scratch, and that is where theming comes in.

To Theme or Not to Theme?

It is totally fine to use a theme for your website, but make sure that you are legally allowed to. There are tons of free site themes on the web, but for this exercise, we will be looking for “static” HTML themes, because the programs we will use later to generate the site only work with static sites (for more on that, see “The Strange Case of Dr. Jekyll” below).

For the HTML-Tricks website, I used the theme called Telephasic from a designer called “AJ” who is the author of “HTML5 UP!”. HTML5 UP! “makes spiffy HTML5 site templates that are: Fully Responsive, Built on intelligent HTML5 + CSS3, Super Customizable, 100% Free under the Creative Commons.” I recommend HTML5 UP! themes because they look great, and they are basically free to use, as long as you include the license somewhere in your site files and explicitly state that they created the design. Again, you could use any HTML site theme that you have access to, or you could create your own (see “Build-a-Jekyll Workshop” below).

Introducing GitHub Pages

In this section, I will assume that you have obtained some sort of HTML site that you are legally allowed to use. Now is the part where you decide how to host your site. There are many different ways to do this, and most involve extreme saddening of your wallet. However, there are ways to host your site for free. Enter GitHub Pages, a project created by the development platform GitHub. It is marketed as “Websites for you and your projects. Hosted directly from your GitHub repository. Just edit, push, and your changes are live.” It’s powered by a program called Jekyll (for more on that, see “The Strange Case of Dr. Jekyll” below), that allows you to “Transform your plain text into static websites and blogs.”

According to GitHub Help, GitHub Pages is a static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository. You can create and publish GitHub Pages sites online using the Jekyll Theme Chooser. Or if you prefer to work locally, you can use GitHub Desktop or the command line. GitHub Pages is a static site hosting service and doesn’t support server-side code such as PHP, Ruby, or Python…GitHub Pages sites are publicly available on the internet, even if their repositories are private. If you have sensitive data in your Page repository, you may want to remove it before publishing…GitHub Pages sites shouldn’t be used for sensitive transactions like sending passwords or credit card numbers. Your use of GitHub Pages is subject to the GitHub Terms of Service, including the prohibition on reselling…GitHub Pages is not intended for or allowed to be used as a free web hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS)…Warning: If the URL for your GitHub Pages site contains a username or organization name that begins or ends in a dash, or contains consecutive dashes, then people browsing with Linux will receive a server error when they visit the site. To fix this, change your GitHub username to remove non-alphanumeric characters.”

Take note that “Published GitHub Pages sites may be no larger than 1 GB.” However, unless you publish a lot of local videos to your blog, this will likely not be an issue. You can always use YouTube, and if you are worried about your video being “out there”, you can upload it as “unlisted” so that only people with the exact link will be able to view it. You can also insert your video into a Google Slides, then publish your Google Slides and embed that into your site.

Of course, the catch is that your site will have a subdomain, such as “your-GitHub-username.github.io/”. This can work in your favor if you intend for your site to based on topics like technology since GitHub is an industry-recognized product. If you prefer to not have your site domain with GitHub, you can check out other alternatives to GitHub Pages for free hosting, such as Netlify, which is “An all-in-one workflow that combines global deployment, continuous integration, and automatic HTTPS. And that’s just the beginning.” Sites published for free with Netlify will have a subdomain of “your-site-name.netlify.com”. GitHub Pages and Netlify are conceptually similar, but since I am more familiar with GitHub Pages, so I will be using that in this article. (And many of the terms and restrictions that I sourced from GitHub Help also apply to Netlify.)

As a last resort, you can always pay for a cheap domain from GoDaddy and host your GitHub Pages using a custom domain (but that would defeat the purpose of this article, right?).

Anyway, the way GitHub Pages works is that it uses your GitHub account username as the site name (“username.github.io”), so be sure to use an appropriate name. Although, if you desperately want to use a funny username, you can also create an organization page (see “GitHub User vs. Organization vs. Project Pages” below).

For now, let’s say that you are using your GitHub username to create your site from scratch. To do this, navigate to github.com and sign in. Next, you’ll need to create a new “repository” (which is developer lingo for a project folder with code) by clicking on any of those “New” buttons (at the time of writing, these buttons are green). You can also click the plus “+” sign at the top, and then clicking on “New repository”. From there, you’ll be able to name your repository.

GitHub User vs. Organization vs. Project Pages

Let’s take a quick break and explain the difference between GitHub User, Project, and Organization pages. Please note that this section is a quick introduction, and since things could change later, please refer to the official full article from GitHub Help on User, Organization, and Project Pages here. According to GitHub Help, “There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences.”

Basically, GitHub User pages are like a personal homepage, where you can put anything you’d like, and it would be accessible at “github-username.github.io”. A GitHub Organization page is the same concept, except for an organization that you own (you can create as many organizations under your GitHub username as you’d like, and from that, you could create as many “site-name.github.io” sites as you please). A GitHub project page is a site that lives specifically in the project repository, or folderof code. Its link would be “github-name.github.io/project-repository-name”, where “github-name” could be either your username or the name of an organization that you create.

The Strange Case of Dr. Jekyll

You’ve read a lot about Jekyll in this post already, but you must be wondering what on earth (or mars) it is. Jekyll is basically the opposite of a dynamic (clickable) CMS like Wordpress, Squarespace, or Wix; Jekyll is a static site generator. This means that it takes in plain text (with a little bit of Markdown for formatting, such as bold or italics) and spits out a ready-made site or blog. As mentioned in a previous section, Jekyll only works with static sites, so it will not work with sites that have PHP, etc. Those will need to be converted to something called Liquid and YAML.

Build-a-Jekyll Workshop

If you can dream, then you can build it. And while you can create your own Jekyll theme (you can convert pretty much any HTML theme into a Jekyll theme), that is beyond the scope of this article. Nevertheless, in this section, I’ll show you how to generate your own ready-to-go Jekyll site with a readymade theme called Minima. I’ll assume that you have a GitHub account and have installed the Jekyll gem from the official Jekyll documentation (I recommend that you follow the official “Guide” for your operating system, which can be found here), as well as Git.

Now, just follow the “Quick-start Instructions” on the Jekyll homepage, then, using your file manager, navigate to the file “_config.yml” within your newly created site (folder), and where the value is “baseurl”, add the name of your site with a prepended forward slash. If you had followed the Quick-start Instructions, your line of code would look like this:

baseurl: /my-awesome-site

Now, save and load (or reload) the page in your browser to see your site. Congratulations! You’ve just created your first Jekyll site. Now, we still need to put your site online for everybody to see, and if you are interested, then continue reading.

GitHub Pages in the Spotlight

While you could use an alternative, like Netlify, GitHub Pages is an amazing piece of software that is created by a reputable, industry-recognized software company (GitHub), and in just a few steps you can have a project site with a URL that looks like this: “your-username.github.io/site-name”. Let’s fire up your GitHub account and create a new repository by clicking on any of the green (as of the time of this writing) buttons that say “New”, or clicking the plus “+” dropdown menu at the top and selecting “New repository”. Then, in the repository name, you’ll type in the name of the site you created (the same value that you gave for baseurl, but minus the forward slash). So, if you had followed the Quick-start Instructions on the Jekyll homepage, you’d input “my-awesome-site” into the “Repository name”, and then check the box next to “Initialize this repository with a README”, then under “Add .gitignore”, search for and click “Jekyll” (a gitignore basically tells Git and GitHub not to worry about syncing a bunch of unnecessary files, produced in this case by Jekyll). Now, click “Create repository”, and voila! Now, it’s not done yet. You’ll have to switch to what is known as a new “branch”, call it “gh-pages”, and make it default.

1. You should be in the “Code” tab of your repository page
2. Click the dropdown for “Branch: master” (under “X commits” and “1 branch”), then type in “gh-pages” and hit enter on your keyboard
3. Now go to the “Settings” tab (next to “Insights”), and click on “Branches” on the side navigation
4. Under “Default branch”, click the dropdown and change the default branch to “gh-pages”, then go back to the “Code” tab
5. Click “2 branches” (in between “X commits” and “0 releases” and then click the trash icon on any row that says “master”
6. Wait a couple minutes, then navigate to your site (if you’ve been following these directions, your site should be at “your-github-username.github.io/your-repository-name”

And there you have it folks, your very own Jekyll site, online! You deserve to pat yourself on the back.

/proz/ written or spoken language in its ordinary form, without metrical structure…

Now that you have a site, it’s time to write great content for it in your blog! There is a great, free program called Prose that lets you write posts in, well, prose. You can even type posts online on your phone or tablet, and it is linked to your GitHub account (which is why I recommended GitHub Pages over Netlify). All that you need to do is visit the Prose website and authorize (which is a fancy term for sign in) to GitHub so that Prose can use the data from your GitHub repositories to help you write posts. Now, once you’ve authorized GitHub with Prose, you should start to see the repository name of your site (in this case, “my-awesome-site”). You can view the site, but for now let’s click on “View Project”, then click on “_posts” and “New File”. Now, just start writing! (Now would be a bad time to get writer’s block.) Be sure to occasionally save your file by clicking the WYSIWYG (an acronym for “what you see is what you get”) save button or typing ctrl+s on your keyboard. You can do so much with Prose in addition to editing your posts. You can preview your post, set metadata/front matter (I strongly recommend that you read this article from Jekyll on YAML front matter), and change basic settings. Have fun!

Wrapping Up

I sincerely hope that this tutorial has helped you create your very own website. The web is your canvas, and I cannot wait to see what you create!