Making A Delightful Personal Page - P1: Introduction and Instant Gratification
Tags: html, surge, tutorial, matthewcalecom
Published: 2020-10-12 17:14:54

---
title: Making A Delightful Personal Page - P1: Introduction and Instant Gratification 
published: true
description: An introduction to building a static personal webpage using HTML/Pug, CSS/Stylus, and Javascript.
tags: html, surge, tutorial, matthewcalecom
cover_image: https://i.ibb.co/r69KLb6/t1-cover.png
---

## 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](https://pugjs.org/api/getting-started.html) (for HTML), [Stylus](https://stylus-lang.com/) (for CSS), [Gulp](https://gulpjs.com/) (for advanced task running) and [Surge](https://surge.sh/) (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](https://atom.io/), [VSCode](https://code.visualstudio.com/), or [Sublime](https://www.sublimetext.com/)
- A terminal program (like Terminal or iTerm)

_Verify your installation_

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

### Project Setup Steps

- Create project directory

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

- Initialize the project

```shell
# 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"_

```shell
# 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_

```shell
# In your terminal
mkdir dist
```

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

- Create an _index.html_ file

```shell
# In your terminal
touch dist/index.html
```

- Get your HTML boilerplate created as well.

```html
<!-- 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](https://fonts.google.com/) 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.

```html
<!-- 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:

```html
<!-- 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:

```css
/* 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.

![local-file](https://dev-to-uploads.s3.amazonaws.com/i/x36jzha21ugbbbmtvafi.png)

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.

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

Which when invoked outputs the following:

```shell
# 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.

```shell
# 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. 

```shell
dale-gribble.surge.sh
```

At this point your project structure should look like this:

```shell
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.

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

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

```shell
# 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:

```shell
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!

![deployed](https://dev-to-uploads.s3.amazonaws.com/i/j6sb8buh61n6zf7hos9t.png)

__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_](https://dev.to/mattcale/making-a-delightful-personal-page-p2-complete-content-and-make-it-pugly-kkd) 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._