Making A Delightful Personal Page - P1: Introduction and Instant Gratification

Introduction

Hello! Welcome to my walkthrough of how to make a delightful personal page. In this series you will be able to read along and quickly build a lovely little homepage that is 💯 runtime dependency free, and is also a 💯 delight to develop by using modern and elegant developer tools written in Node.js.

The page we will be making is a clone of my personal page, http://matthewcale.com. The tools we will employ and get a reasonable introduction to are: NPM scripts (for basic task running), Pug (for HTML), Stylus (for CSS), Gulp (for advanced task running) and Surge (for hosting). We will use these tools to create a pleasant to read, fun to develop, and simple to deploy website that requires no CSS* or Javascript libraries, which means that its footprint is tiny and that the amount of cognitive load it takes to develop is miniscule.

I wrote this to be approachable for developers of all skill levels, while not being tedious for more advanced devs. If things were markedly unclear or miserably tedious let me know. I may not be able to please everyone, but understanding what readers want is important to me. Thank you.

Aside, Why Make This?

Optional, read only if you are interested as to "why" I made this tutorial.

As developers we are tasked with knowing how to do a great many things and these things are often incredibly complex and require a (pretty) rigid structure. We need this rigidity in order to make massive projects that can easily scale both in the number of end consumers and in the number of active developers.

Frameworks exist to make this rigidity and boilerplate less off-putting and easier to understand and as such developers employ these frameworks to reduce the burden of hand rolling rigid structures. A good example is Bootstrap. Many development teams employ Bootstrap (or another CSS library like it) to keep from writing their own CSS components. This is a great idea! General pages, that users interact with (forms) and consume information from (dashboards) follow an expected format and Bootstrap has made these expected formats much easier to make.

There is however, another type of page that exists on the internet that CSS frameworks, by the nature of that selfsame useful rigidity fall short in being as useful for, and that is the bespoke "pretty" or "artistic" page (like the one we are making here). Don't get me wrong, the frameworks usually have the ability to make these pages as well, and offer their own advantages to seasoned users of those frameworks, but they were not written for this purpose. So, while they can be used to make these pages I have found that it feels much more natural to let frameworks tackle the common problems and let humans tackle creating artsy pages. That is what these pages are essentially, little artwork installations.

So, what I set out to do was see how easily and pleasantly I could create a (hopefully) lovely page with no frameworks.

What I discovered is that, with the help of a few developer tools, creating pages whose primary aim is to be lovely can be quite pleasant and I wanted to share my approach.

Instant Gratification

To start, let's get a cool page up online! This page will not be our final product, but will be a good place to start getting familiar with three of the technologies we intend to use and will give you a project setup that you can easily keep building upon. So let's get after it!

Tools you need

• Node.js installed
• A basic code editor, like Atom, VSCode, or Sublime
• A terminal program (like Terminal or iTerm)

Verify your installation

# In your terminal
matt.cale$ node --version
v12.16.3
matt.cale$ npm --version
6.14.4

Project Setup Steps

• Create project directory

# In your terminal
# Idea: Use "jane-doe" instead of "dale-gribble" in your command 
mkdir ~/Desktop/dale-gribble.com

• Initialize the project

# In your terminal
# Idea: Use "jane-doe" instead of "dale-gribble" in your command 
cd ~/Desktop/dale-gribble.com && npm init -y

Note: The command, npm init -y, will create the package.json file required for Node and NPM (Node's dependency management tool) to treat your project like a Node module thus allowing you to install the required dev-only dependencies.

• Install Surge.sh as a "developer dependency"

# In your terminal
npm i --save-dev surge

Note: A "developer dependency" is a code library or program / application that makes the creation of other libraries or applications easier.

Create Your Site's Content Steps

Now that we have a project we can hack on let's get to hacking! Later on we will be using Pug.js to create markup that is more elegant, modular, and extensible, but for now let's just hack some HTML so we can get something decent deployed.

• Create a directory called dist

# In your terminal
mkdir dist

Important: This will be the directory that we deploy as our static site.

• Create an index.html file

# In your terminal
touch dist/index.html

• Get your HTML boilerplate created as well.

<!-- In your dist/index.html file -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style></style>
    <!-- CSS font link here! -->
    <title>Dale Gribble</title>
</head>
<body>
    <!-- Content here! -->
</body>
</html>

• Get a 🆒 font from Google Fonts and place it in the head section as a stylesheet link. It's a good idea to get a regular, bold and italic version. Here' mine.

<!-- In your dist/index.html file -->
<!-- In between the <head> tags -->
<link href="https://fonts.googleapis.com/css2?family=Cabin:ital,wght@0,400;0,500;1,400&display=swap" rel="stylesheet">

Now that we have our HTML scaffolded out let's add our first bit of custom content. You can now add any HTML you want to your page, but if you are following along I went with the following format:

• Name (Dale Gribble)
• Identifiers (Exterminator, Treasure Hunter, Alientologist)
• Welcome Message (If you're from the CIA you have to tell me! 👽)

Inside of the body add the following:

<!-- In your dist/index.html file -->
<!-- In between the <body> tags -->
<div class="row">
    <div class="column hero">
        <div class="welcome-info">
            <h1>Dale Gribble</h1>
            <h2>Exterminator, Treasure Hunter, Alientologist 👽</h2>
            <p>If you're from the CIA you have to tell me!</p>
        </div>
    </div>
</div>

The content we are going to provide is going to be styled with Flexbox, a styling tool available in plain ol' vanilla CSS. To make this styling easier to understand we are going to split our UI into rows and columns. Sometimes we will have multiple columns, but in this case we just want a row with a single column. The column will contain one item, a welcome-info container element that contains our content.

Check it out in the browser, pretty boring, eh? Well, let's add some styling to spruce it up before we go public with it!

Up between the style tags in the head section of your index.html copy in the following:

/* In your dist/index.html file */
/* In between the <style> tags */
body {
    font-family:'Cabin', sans-serif;
}

h1 {
    font-size: 2.5rem;
}
.row {
    display: flex;
    justify-content: center;
}

.column {
    display: flex;
}

.hero {
    align-items: center;
    height: 100vh;
}

.welcome-info {
    text-align: center;
}

.welcome-info .sugar {
    font-style: italic;
}

The styles are pretty simple, but even so do not worry if you don't understand something I will be covering these styles in more detail in a later section.

Go ahead and open the index.html file in a browser, provided you are connected to the internet (for fonts) you should see the following.

If yours doesn't look like mine check out the dist/index.html in the demonstration repo and see if everything is the same there. If you checked and it's all the same please leave me a comment or create an issue.

Deploy Your Site to The Internet Steps

Great, you have a website that isn't horrible to look at! It also gives a fair amount of information about you, but this isn't useful unless other people can see it, right?

So how do we get this 💣 site deployed online? Well, remember earlier when you downloaded surge? Now we are gonna use it!

Surge is an insanely simple static site (what we just made) hosting platform. To get started we are going to create an NPM script that invokes the surge program we downloaded.

A NPM script is a command that is invoked with npm run <script> and references an entry in the package.json file's scripts section. It will use your shell's commands (Ex: Bash). An example script might look like this.

"scripts": {
  "say-hi": "echo hello there"
}

Which when invoked outputs the following:

# In your terminal
npm run say-hi
> echo hello there
hello there

Since we downloaded surge there will be a program that NPM can invoke inside of your node_modules directory called surge.

All that is required for surge to work is a directory that contains an index.html (dist for us), a file in the same directory called CNAME that has your desired surge address in it, and an account (email and password). Best of all, it's all free!

So let's create our deployment process.

• Create a file called CNAME (this file has no extension, like .html or .txt) in the dist directory.

# In your terminal
touch dist/CNAME

• Open the CNAME file and add your desired <site-name>.surge.sh site name to it. Here's the contents of my CNAME file.

dale-gribble.surge.sh

At this point your project structure should look like this:

dist
dist/index.html
dist/CNAME
node_modules
package-lock.json
package.json

• Create the deployment script in the package.json scripts. Here's the scripts section of my package.json file.

"scripts": {
  "test": "echo \"nothing to test\"",
  "deploy": "surge dist"
},

Now it's time for lift off 🚀! Run your deploy NPM script.

# In your terminal
npm run deploy

Note: Your first time running surge will prompt you for an email password word.

The output for me looks like this:

Running as <matt> (Student)

project: dist
domain: dale-gribble.surge.sh
upload: [====================] 100% eta: 0.0s (2 files, 1178 bytes)
CDN: [====================] 100%
IP: <IP>

Success! - Published to dale-gribble.surge.sh

Now in a browser, navigate to your site-name.surge.sh, and see your masterpiece!

Here's mine!

Wow! We just did quite a bit! We made a site, styled it, created a CNAME (networky) file, created a deployment script, and published a site to the internet. Let's bask in the glow of all we've done for a while before moving on to Part Two where we will make our markup prettier and more extensible using Pug and another NPM script!

Thanks for following along. I hope this was fun and educational. If you have any feedback or just wan to say "howdy" please drop me a line below. Have a wonderful day. 🤠

*For fonts I will be using some Google Fonts, but this is entirely optional, and suitable fallbacks will be available.