How I Made this Website

Overview

This guide serves as a form of documentation for how I built my static website. It is also intended to be a resource for those looking to do the same thing.

What are Static Websites, and Why Use Them?

This guide will describe how I created this static website. A static website is one whose server provides files without doing any logic. For example, when you view this website, your computer is receiving and rendering HTML files sent by the server. Any animations or apparent logic are the result of code running in your browser (i.e. JavaScript), not code on the server.

This means that static websites can’t do things like send notifications or emails. They also generally do not support access controls, though there are exceptions and ways to get around this¹. However, static sites are easy to deploy, and without server-side code, they often have fewer security risks. Further, instead of paying for server space, you can host your static site on GitHub for free using GitHub Pages.

My Workflow

My website is built using Jekyll, which is designed to build static blogging websites. I write my pages in kramdown-flavored markdown, which Jekyll then combines with a theme to create the HTML and CSS files that comprise the built² static website. I then use deployWWW, a script I wrote, to upload those compiled files to GitHub Pages.

Setup

Dependencies

You will need to install the following:

• Jekyll, which we will use to build the site from the markdown source.
• git, which is how we will upload the built site to the hosting server.
• Bash, which you already have if you have a macOS or Linux machine (almost certainly). You’ll need this to run deloyWWW.

If you plan to host using GitHub Pages, you should also create a GitHub account at https://github.com.

If you plan to host using Stanford AFS (which you can only do if you have a full-service SuNet), you also really want to have kerberos setup. Otherwise, you’re going to have to authenticate a bunch of times whenever you update your site. For Stanford AFS you’ll also need to have SSH installed, which you probably already do.

Get Theme

I started with the bootblog theme for my website, but you can use any Jekyll theme you like. Search for Jekyll Theme and you’ll find plenty to choose from. They should all be pretty similar, but this guide will best match the process for bootblog³.

To get your theme, open up a terminal and cd into the directory you want to store your website source in. Then, git clone your theme. In the case of bootblog, this would look like

$ git clone https://github.com/sharadcodes/bootblog.git mySite
$ cd mySite

Now, you should have a directory structure that looks something like this:

.
├── 404.md
├── LICENSE.txt
├── README.md
├── _config.yml
├── _includes
│   ├── footer.html
│   ├── head.html
│   └── sidebar.html
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── _posts
│   └── 2019-05-06-siteInstructions.md
├── assets
│   ├── browserconfig.xml
│   ├── css
│   │   ├── bootstrap.css
│   │   ├── custom.css
│   │   ├── custom.min.css
│   │   └── syntax.css
│   ├── images
│   │   ├── android-chrome-192x192.png
│   │   ├── android-chrome-384x384.png
│   │   ├── apple-touch-icon.png
│   │   ├── favicon-16x16.png
│   │   ├── favicon-32x32.png
│   │   ├── favicon.ico
│   │   ├── mstile-150x150.png
│   │   └── safari-pinned-tab.svg
│   ├── js
│   │   ├── bootstrap.min.js
│   │   └── jquery.min.js
│   └── site.webmanifest
├── blog
│   └── index.html
└── index.md

General File Structure

Here is a brief overview of what these files are:

• /404.md: This describes the page that will be shown to your users if they request a non-existent page.
• /_config.yml: The site-wide configuration file that Jekyll follows when building your site.
• /_includes: HTML files that can be imported into other files by using syntax like {% include head.html %}. See the Jekyll documentation for details.
• /_layouts: Stores layout files. Layouts are like templates within which your content is displayed. If you look in one, you’ll probably see HTML, potentially some include statements, and {{ content }}, which is where the HTML generated from your markdown files will go. You can read more in the documentation.
• /posts: Where you’ll put any blog posts. Jekyll is built with blogging in mind, so this can be quite powerful.
• /assets: Various files that the site needs to work. This is where things like the CSS styles (which define the site’s aesthetics and are found in /assets/css) and the website icon (in /assets/images) are stored. Javascript also lives here, in /assets/js.
• /blog: This folder is where your users will go to see your blog. They’ll go to your-URL/blog and be shown index.html (the file named index is what gets shown when a user specifies the folder but not any file within it), which has the code to list your blog posts.
• /index.md: Your website’s homepage. This is probably the one you’ll want to customize the most!

Personalizing Your Theme

At this point, you can run jekyll serve and go to http://127.0.0.1:4000 to see what your website looks like now. It probably looks nice, but it’s not about you yet! Let’s fix that with some customization. Here’s what I did.

• Delete the example posts. Bootblog comes with example posts, which you might want to refer to when writing your own. However, I didn’t want them sitting around in the real website, so I deleted everything in /_posts/.
• Delete the author page. Some themes come with separate about pages in case you want your home page to be about something different, like the app the website is for. I put my bio on the homepage, though, so I deleted the /author.md file.
• Add a bio to the homepage. I put a brief introduction to myself on the homepage by writing it in /index.md.

• Add pages and folders. To organize the other content I wanted on my website, I added folders for my biology and computer science work. To do this , you just create folders, nested however far you like, in your website folder. For example, now my website folders might look more like this:

  .
  ├── 404.md
  ├── LICENSE.txt
  ├── README.md
  ├── _config.yml
  ...
  ├── biology
  │   ├── biofilms
  │   │   ├── index.md
  │   └── fernaldLab
  │       ├── bsurpsPoster.pdf
  │       ├── burtoni.png
  │       ├── fmPhotoInstructions.md
  │       ├── index.md
  │       └── poster.md
  ...
  

  To view the index.md file under biofilms, a user would go to https://your-url/biology/biofilms (remember that if you just go to the folder, you see the index file). You can use this technique to setup your website directories however you like. Again, you write the pages using markdown. However, you also need to define front matter, which tells Jekyll which layout to apply to your document. For example, to use the page layout, you would start your document with

  ---
  layout: page
  title: Your Title Here
  ---
  

  Then, you just write in markdown after the second ---.

• Write posts. To create posts, you follow the same kind of process as for pages, except all your files go in /_posts, and you’ll want to use the post layout (or whatever equivalent your theme has). Additionally, the front matter looks like this instead:

  ---
  title: Your Title
  layout: post
  date: Date
  description: Your Description
  author: Your Name
  ---
  

Adjusting the Configuration

To do this, edit the /_config.yml file. You will probably want to change the values of title, tagline, author, bio, and description to better suit your site. Also, set baseurl to null, which deployWWW needs. The base URL needs to be the part that will always prefix URLs to your site, which changes based on your hosting option. deployWWW will automatically set it when you deploy, and null works for local development just fine.

If there are files you don’t want to have included in the built site, you can exclude them by adding them to exclude: [exclusion1, exclusion2, ...].

Bootblog has a contact section of the config file where you can add links to whatever external sites you like.

Bootblog also has a toc section where you define what pages you link to from the menu bar. For example, the following config will have a menu with links to the homepage and the blog, plus a drop-down menu called Biology with links to Fernald Lab and Biofilms Research:

toc:
  - title: Home
    url: /
  - title: Blog
    url: /blog
  - title: Biology
    subfolderitems:
      - page: Fernald Lab
        url: /biology/fernaldLab
      - page: Biofilms Research
        url: /biology/biofilms

Deploying

Download deployWWW from https://github.com/U8NWXD/deployWWW. You can also use git to clone it if you like. Put the deploy.sh file somewhere you can execute it. This could be in your PATH or in your website directory (in which case you need to prefix the deploy.sh command with ./ to make ./deploy.sh).

Deploy to Stanford AFS

Run deploy.sh -s sunet where you replace sunet with your SuNet (the part that precedes the @stanford.edu in your email). That’s it! deployWWW will login to your account on myth, create a repository, build your website, git push the built website to the repository, and git pull from the repository into your ~/WWW/site folder on AFS. Then, you can see your website at https://web.stanford.edu/~sunet/site.

Deploy to GitHub

Create a GitHub repository with name username.github.io, replacing username with your GitHub username. Then, run deploy.sh -g username. If you prefer to use HTTPS, run deploy.sh -tg username.

More In-Depth Changes

Center Profile Photo

This HTML code in a markdown file will let you have a photo (image.png) with text to the right (Text to the Right) centered on the page.

<div class="row">
  <div class="col-md-3"></div>
  <div class="col-md" markdown="1">
  ![Image Description](image.png){:height="200px" width="200px"}
  </div>
  <div class="col-md" markdown="1">
  Text to the Right
  </div>
  <div class="col-md-3"></div>
</div>

Website Icon

To change the website icon, you need to replace all the images in /assets/images with the icon you want. Make sure to scale the new icon to match the icons already present. Gimp is one tool that can do this.

CSS Style Changes

Quotes

Markdown has a nice feature where you can include quotes by prepending lines with >. This looks like this:

Here’s a quote!

However, the CSS styling that came with bootblog didn’t support this. To fix this, I changed the /assets/css/bootstrap.css section with blockquote to read:

blockquote {
  margin: 0 0 1rem;
  color: gray;
  border-left: .25em solid gray;
  padding: 0 1em;
 }

Plaintext Formatting

Markdown supports formatting of plaintext, but bootstrap (upon which bootblog is built) uses a red color I dislike. To change this, I altered the CSS styling of the code.highlighter-rouge section to read:

code.highlighter-rouge {
  background: rgba(0,0,0,0.9);
  border: 1px solid rgba(255, 255, 255, 0.15);
  padding: 0px 10px;
  margin: 0px 3px;
  color: #fff;
  border-radius: 5px;
}

Set License by Config

I think it is important to think about whether and how you want to let other people use your work. In my case, I wanted to make it pretty easy for someone else to build on top of my work, so I speecified a fairly permissive license for my site. Whatever license you choose, it’s a good idea to put it in the footer of your site. I modified my site so I could specify the license in the _config.yml file. To do this, add the following to your /_includes/footer.html just after the <ul> tags (for bootblog at least):

<p>
    Unless otherwise noted, Copyright &copy
    {{ site.start_year  }} - {{ site.time | date: '%Y'  }}
    {{ site.author  }}, and content is
    licensed under the
    <a href="{{ site.license_link  }}">
         {{ site.license  }}
    </a>
</p>

Then, I added the following to my _config.yml:

# For copyright
start_year: 2019
license: CC-BY 4.0 International License
license_link: https://creativecommons.org/licenses/by/4.0/

You should change the license to be whatever license you choose. The year will automatically update to reflect when you last built the site.

Timestamp

To add the date you last built the website to the footer, add

<p>
    Last updated {{ site.time | date_to_string: 'ordinal', 'US' }}.
</p>

to /_includes/footer.html after the copyright information.

Redirects from Stanford AFS

There are two ways to do this. You can create an index.html page in your AFS ~/WWW directory that will redirect users when they open the page. The HTML would look something like this:

<meta http-equiv="refresh" content="0; url=https://your-url" />
<p>
If your browser does not automatically redirect, please click
<a href="https://your-url">here</a>.
</p>

Alternatively, you could use a .htaccess file, which will redirect any requests to the folder the file is in and any subdirectories. The file contents might look like this:

Redirect 301 /~sunet/folder/to/redirect https://your-url/

Concluding Thoughts

I hope this was a useful reference for you and inspired or helped you build your own website. If you have suggestions for better ways to do something, or if you catch a mistake I made, please let me know.