Brian's Website

How I Made This Website

I am not qualified to teach you how to make a website. I am not a programmer or developer or anything like that. There are wondeful resources and guides for Eleventy, and I relied on them. I did, however, take notes for myself as I went. I tidied those up a little bit, cutting out failed experiments and much trial and error. If you think that following my non-prgrammer notes would help - have at it!

If I were making this for teaching purposes, I would present things in a different order. Nothing here represents best practice or good advice. You will find better teachers in the Credit and Appreciation section below. It is better to think of this as breadcrumbs I've left for myself that I hope may have some value for others.

Contents

Credit and Appreciation

Internal Links and Go-To-Top Button

Homepage Content and Icons

Blog Post Tags

Publish

Blog Feed

Credit and Appreciation

If you want to make a website and, like me, are starting at zero, I strongly recommend HTML for People by Blake Watson. Blake assumes no prior knowledge but is not at all condescending. HTML for People is the right place for most non-programmers to start.

After HTML for People, I wanted to learn more, tinker, and automate. Eventually I found Eleventy. I learned how to use Eleventy from Zach Leatherman's great video 6 Minutes to Build a Blog from Scratch with Eleventy and Stephanie Eckles' fantastic class, 11ty from scratch. Stephanie's website, 11ty Rocks!, well, rocks! The Learn Eleventy project is outstanding, even if their scope is quite a bit broader than what I needed. 11tybundle.dev shares the latest and greatest.

Finally, but importantly, the folks at the 11ty Discord server have been welcoming, kind, and helpful - sometimes going out of their way to help me. I appreciate them very much.

Eleventy Setup

This goes through the basic steps of creating a new project and installing Eleventy. It closely tracks the examples above, especally Learn Eleventy.

Started writing down what I'm doing in a new document in Drafts.
Made project folder:~/Documents/Projects/Website.
Opened folder in VS Code.
Confirmed Node.js is installed with node -v. Version 22.14.0 is installed.
Made .gitignore file. Added code similar to what is used in the Learn Eleventy project:

# Misc
*.log
npm-debug.*
*.scssc
*.swp
.DS_Store
.sass-cache
.env
.cache

# Node modules and output
node_modules
public
src/_includes/css

Made .eleventy.js configuration file. Added code similar to what is used in the Learn Eleventy project:

module.exports = (eleventyConfig) => {
	return {
		dir: {
			input: 'src',
			output: 'public',
		},
	};
};

Made /src folder. Made index.md file in /src. Wrote: Hello world.
Added package.json with npm init -y.
In package.json, replaced test script with start script:

"start": "npx eleventy --serve"

Installed Eleventy from the terminal with:

npm install @11ty/eleventy

Ran Eleventy with npm start. Checked http://localhost:8080.
Made folder /src/css
Made simple.css file and added Simple CSS from https://cdn.simplecss.org/simple.css.
Made folder /src/_includes/layouts.
Made layout file base.njk in /layouts and added HTML:5 boilerplate.
Added <header></header>, <main></main> and <footer></footer> placeholders in base.njk.
In .eleventy.js added a passthrough for CSS:

// Passthroughs
eleventyConfig.addPassthroughCopy('./src/css/');

In base.njk in <head></head>, added CSS with:

<link rel="stylesheet" href="/css/simple.css">

In index.md, added front matter:

---
title: Home
layout: /layouts/base
---

ln base.njk, in <title></title> adde Brian's Website, and in <main></main> added

{{ content | safe}}

NOTE: to make code with curly brakets display correclty and not throw an error, but the code between {% raw %} and { % endraw % }.

Made folder /_includes/partials.
In /partials made header.html, and footer.html. Added placeholder content to those files.
Included header.html and footer.html in base.njk with {% include "/partials/FILENAME.html" %}.
Confirmed website looked correct at http://localhost:8080/ then terminated local server.
Initialized Git repository - message: Initial commit. Published branch (private) on GitHub.

As I write this, the GitHub repo is private. I might make that public in the future. Also, going foward I commit and sync at the end of each section - more or less. I do not add a note each time a commit and sync unless I'm doing somethign really significant.

Navigation

This adds a navigation bar to the website. I also made an empty blog index page to test the navitgation.

Installed the Eleventy Navigation Plugin v. 1.0.0 following instructions on the Eleventy website with CommonJS examples.
Made navbar.html in /partials and added code:

<nav>{{ collections.all | eleventyNavigation | eleventyNavigationToHtml({ activeKey: eleventyNavigation.key, useAriaCurrentAttr: true }) | safe }}</nav>

Note: This collects the EleventyNavigation keys and URLs (we are about to make those), and and adds a fuction to correctly set aria-current="page". Putting all of that in <nav></nav> makes everything display correctly.

In index.md front matter, added:

eleventyNavigation:
	key: Home
	order: 1

Included navbar.html in <header></header> in base.njk.
Made blog.md in /src with placeholder content and front matter:

---
title: Blog
layout: /layouts/base
eleventyNavigation:
	key: Blog
	order: 2
---

Started Eleventy with npm start and confirmed navbar displays and works correctly at localhost:8080.

Note: Going forward, I start Eleventy and check my work frequently. I do not note every time I do this.

“How To” Page

I wrote down a list of everything I did to make the website. Here, I move that list onto the website itself.

Made howto.md in /src with front matter:

---
title: How To
layout: /layouts/base
eleventyNavigation:
    key: How To
    order: 3
---

Copied notes from Drafts to howto.md.

Going forward, I put howto.md to the side in VS Code and take notes there. I can't imagine this is best practice, but ignorance is bliss?

Header and Footer

This replaces placeholder text added when creating the header and footer partials. This also adds an <h1></h1> to every page.

Note: for the header, it might have been easier to put the content directly into the layout file. However, by keeping the header as a partial, I hope to have more flexiblity if I make changes later. Also, the link in the footer tells Mastodon that I own this this website. That's neat, but it should not be taken as proof of identiity. It only means that the same person can access the same website and Mastodon account.

Replaced placeholder content in header.html with <h1>Brian's Website</h1>.
Replaced placeholder content in footer.html with: Made with ☕ and ⌨ by Brian

Date Filters

These filters enable Eleventy to display correct date, in the format of our choice, avoiding a common pitfall in which dates are off by one day. The first filter will make the date display correctly in ISO format (e.g. 2025-01-30). The second filter will make the date display with the month spelled out (e.g. 2025 January 30).

In the configuration fille .eleventy.js, above module.exports added:

const { DateTime } = require("luxon");

Still in .eleventy.js, below module.exports but above return { added:

// Filters
eleventyConfig.addFilter("correctISO", (dateObj) => {
	return DateTime.fromJSDate(dateObj, { zone: "utc"}).toFormat("yyyy-MM-dd");
});

eleventyConfig.addFilter("niceDate", (dateObj) => {
	return DateTime.fromJSDate(dateObj, { zone: "utc"}).toFormat("dd MMMM yyyy");
});

Blog

Now, we finally make the blog. I had a website before making this one, so I already had some posts. I started by making a folder for the posts and placing a .json file in that folder for tagging and layouts. Then, I added the blog files and made blog posts appear on the blog page. Last, I made a layout for the posts.

Made folder /src/blog.
Made file blog.json in /blog and set layout and tags:

{
    "layout": "/layouts/blogPost.njk",
    "tags": "posts"
}

Made layout posts.njk in /layouts. Copied content from base.njk.
Copied blog posts from prior website to /blog. These are markdown files all with ISO dates at the start of the file name. For example, the first post is named 2025-02-20-hello-again.md. Each post file has front matter in this format:

---
title: The Title of the Post
date: YYYY-MM-DD
blurb: A blurb about the post.
tags:
	- First Tag
	- Second Tag
---

Edited <main></main> in posts.njk as follows:


<h2>{{ title }}</h2>
<p><strong><time datetime="{{ date | correctISO }}">{{ date | niceDate }}</time></strong></p>
{{ content | safe }}

Note: The second line applies filters to the date in the post's front matter. For example, if the date in the front matter is 2025-02-20, the HTML on the post will be <p><strong><time datetime="2025-02-25">25 February 2025</time></strong></p>

Displayed blog posts on the blog index page by replacing the placeholder text with:


    2025-03-11 &mdash; [The Broken Earth](/blog/2025-03-11-the-broken-earth/)<br>
    _I recommend The Broken Earth book trillogy by N.K. Jemisin._

    2025-02-26 &mdash; [Balatro](/blog/2025-02-26-balatro/)<br>
    _I recommend Balatro, a video game._

    2025-02-25 &mdash; [This Post Has Tags](/blog/2025-02-25-this-post-has-tags/)<br>
    _How I learned to tag my posts._

    2025-02-20 &mdash; [Hello again!](/blog/2025-02-20-hello-again/)<br>
    _A new post for a new website._

One of the blog posts had an image. I would like to add more images in the future. The next steps create a folder for the images and a passthrough for that folder (the passthrough works the same way here as it did for the CSS file above).

Made folder /src/images and added the image file used in the blog post to that folder.
In .eleventy.js, just below the passthrough for /src/css, added:

eleventyConfig.addPassthroughCopy('./src/images/');

In /partials made backToBlog.html button with:

<a href="/blog/" class="button">&larr; Back to the blog</a>

Added the button to the posts.njk with {% include "partials/backToBlog.html" %}.

Internal Links and Back-To-Top Button

At this point, I realized that this "how to" page was getting long and unwieldy. I added internal links and a table of contents to this page at the top. I also added a button to go back to the top of the page that appears when you scroll down. Then, I added that button everywhere beucase it is quite useful.

The heading in each section was already an <h2></h2, so add IDs to each of those headings. For example, the heading for this section is:

<h2 id="internal">Internal Links and Scroll to Top</h2>

At the top of the page, added a table of contents dropdown down (thanks again to HTML for People for showing me how to do this). The finished code appears below.
For each heading, add a <li></li> in the dropdown. The end result (before adding this section) is:

<details>
	<summary>Contents</summary>
		<li><a href="#credit">Credit and Appreciation</a></li>
		<li><a href="#setup">Eleventy Setup</a></li>
		<li><a href="#nav">Navigation</a></li>
		<li><a href="#howto">&#8220;How To&#8221; Page</a></li>
		<li><a href="#handf">Header and Footer</a></li>
		<li><a href="#datefilters">Date Filters</a></li>
		<li><a href="#blog">Blog</a></li>
	</details>

Made a button that stays invisable untill scrolling down in /partials as topButton.html with:

<!-- this positions the button and hides it until you scroll down -->

<style>
    #topBtn {
        display: none;
        position: fixed;
        bottom: 20px;
        right: 30px;
        z-index: 99;
    }
</style>

<!-- this is the button -->

<button onclick="topFunction()" id="topBtn" title="Go to top">&uarr; Top</button>

<!-- this is the script that makes the button work -->
<script>
    // Get the button
    let mybutton = document.getElementById("topBtn");
    // When the user scrolls down 20px from the top of the document, show the button
    window.onscroll = function() {scrollFunction()};
    function scrollFunction() {
         if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) {
            mybutton.style.display = "block";
            } else {
                mybutton.style.display = "none";
            }
        }
    // When the user clicks on the button, scroll to the top of the document
    function topFunction() {
        document.body.scrollTop = 0;
        document.documentElement.scrollTop = 0;
    }
</script>

Thank you to W3Schools! That is a modified version of their template.

Added the back-to-top button to all pages by including it in the <body></body> of the base.njk and posts.njk layouts.

Homepage Content and Icons

I got very good advice and help for this part from the kind folks on the Eleventy discord server. Truly appreciate their guidence.

Added content to index.md, turning that into a combined homepage and 'about me' page.
Made head.html in /partials and cut/copied the <head></head> from base.njk to that file.
Deleted the contents in <head></head> from base.njk and post.njk and included the head.html partial instead. These were the same, and now I can change the <head> in both layouts by changing the partial.

At this point I decided to use Font Awesome icons and 11ty's Font Awesome plugin. That requires Eleventy v3.0.1-alpha.4 and newer. When I installed Eleventy, I got version 3.0.0. Upgrading to an alpha version of Eleventy felt like a big deal, so I branched my GitHub repo at this point.

Installed Eleventy v3.0.1-alpha.5 via terminal with npm install @11ty/eleventy@^3.0.1-alpha.5.
Installed the Eleventy Font Awesome plugin via terminal with npm install @11ty/font-awesome.
Added the Font Awesome plugin to the .eleventy.js configuration file as such:

const { default: fontAwesomePlugin } = require("@11ty/font-awesome");
// …
module.exports = (eleventyConfig) => {
  // …
  eleventyConfig.addPlugin(fontAwesomePlugin);
  // …
}

In simple.css added:

svg { 
    height: 1em; 
    width: 1em; 
}

Note: Adding that code to the CSS file makes the icos display at the correct size. They will look too big if that's missing. Major thanks to the fokls

In the head.html partial, added:

{% getBundle "fontawesome" %}

Throughout the website, I copied the Font Awesome icon HTML and added pasted it in. Eleventy let me mix HTML and Markdown. For example, "Welcome" line with the house icon in index.md is a mix of Markdown and HTML:

## <i class="fa-solid fa-house"></i> Welcome

Eleventy turns that into HTML in the /public folder like this:

 <h2><svg><use href="#fas-fa-house" xlink:href="#fas-fa-house"></use></svg> Welcome</h2>

Blog Post Tags

Next, I put the blog post tags to use (I probably should have done this when I set up the blog, but 🤷‍♂️). In fact, the first time I made a blog with Eleventy, I wrote a post about this process. If you want a detailed explianation about how I'm using blog post tags, you can read This Post Has Tags. However, when I did this again for the current version of the blog, I simplified things a little bit and you will notice differences between what I wrote then and what I did now.

In .eleventy.js made a filter to remove "posts" and "all" from the tags collection:

eleventyConfig.addFilter("filterTagList", function filterTagList(tags) {
	return (tags || []).filter(tag => ["all", "posts"].indexOf(tag) === -1);
});

In .eleventy.js made another filter to sort tags into alphabetical order:

eleventyConfig.addFilter("sortTags", function(tags) {
	if (!Array.isArray(tags)) return tags;
	return tags
	.filter(tag => typeof tag === "string") // Ensure only strings are processsed 
	.sort((a, b) => a.localeCompare(b));
});

In /src made the file tagpages.njk. Wrote front matter as follows:

---
pagination:
    data: collections
    size: 1
    alias: tag
    filter:
        - posts
permalink: /tags/{{ tag | slug }}/
layout: /layouts/base
---

In tagpages.njk, added a loop to display all posts with the specified tag:

<h2>Tagged: {{ tag }}</h2>

{% set taglist = collections[ tag ] %}
{% for post in taglist | reverse %}
    <p>{{ post.data.date | correctISO }} &mdash; <a href="{{ post.url }}">{{ post.data.title }}</a><br>
    <em>{{ post.data.blurb }}</em></p>
{% endfor %}

In posts.njk made the tags appear with:

<strong>Tags:</strong> 
{% for tag in tags | filterTagList | sortTags %}
	<a href="/tags/{{ tag | slug }}/">{{ tag }}</a>{% if not loop.last %}, {% endif %}
{% endfor %}

Wrap the "Back to the Blog" button in <p></p> so it displays under the tags.
In /layouts made blog.njk and copied content of base.njk to the new layout.
In <main></main>, added "Post by Tag" and put the "top" button in that section with:

<section><h2><i class="fa-solid fa-tags"></i> Posts by Tag</strong></h2>
	{% include "partials/allPostTags.njk" %}
    {% include "partials/topButton.html" %}
</section>

In blog.md fron matter, changed layout: /layouts/blog, added an <h2></h2> for "posts by date" and wrapped that in a <secton></section> (all this really does is take what was already on the blog page and make it into a section for recent posts). Like this:

<section>
<h2><i class="fa-solid fa-calendar-days"></i> Posts by Date</h2>
{% for posts in collections.posts reversed %}
    {{ posts.data.date | correctISO }} &mdash; [{{ posts.data.title }}]({{ posts.url }})<br>
    _{{ posts.data.blurb }}_
{% endfor %}
</section>

Publish

I made a new branch in GitHub before installing the alpha version of Eleventy needed for the Font Awesome plugin. When I saw that was working and not causing problems, I merged the branches. From the GitHub webpage: Pull Requests > New pull request > Compare (GitHub says "Able to merge") > Create pull request > Merge pull request > Confirm merge > Delete branch (the alpha branch, not the main branch).

In anticipation of publishing, I took a moment to tidy up an check for major typos. I'm sure that I missed some, but I found a few that would have been embarrassing.

Note: At this point, you can simply drag the contents of /public into any number of free hosting services like Neocities. Eleventy makes a static, HTML website that can be hosted anywhere. I chose to spend a few dollars to get my own doman and connect that to NearlyFreeSpeech.net. This lets me run a script from VS Code to upload changes to the server. This way, if I write a new blog post, I can automatically upoad the post without re-uploading the entire website. I don't think there is a wrong answer for small, personal websites like mine, but I am definately not an expert! Also, figuring out how to make the script work was a lot of fun!

In package.json add a deploy script under the start script. I've replaced some of the actual code here so that I am not publishing the name of every folder on my computer in the path to /public or my user name at NearlyFreeSpeech (I do this in a few other places in this section, too):

"scripts": {
    "start": "npx eleventy --serve",
    "deploy": "rsync -avz --checksum /Users/path/to/public/
    username@yourserver:/path/to/website"
  },

WARNING: I am not a security expert. I have no idea if what I did represents best practices or is considered secure. My security needs for this website are minimal. Please check with someone who really knows what they are doning before copying anything here.

Generate an SSH Key (two files, a public key and a private key):

ssh-keygen -t ed25519 -C "email@example.com"

Displayed my public key with:

cat ~/.ssh/id_ed25519.pub

Added my public key to my account at NearlyFreeSpeech.net.
Added my key to my keychain with:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Uploaded the public folder to NearlyFreeSpeech from the terminal with:

npm run deploy

Blog Feed

While I do not have much content, I wanted a blog feed so folks can subscribe. Eleventy makes that pretty straighforward. I followed the installation and virtual template instructions on the Eleventy website almost virbatim. I did not undertand how it works when I read the website, but I got it as soon as I saw it in practice.

Install Eleventy's RSS plugin with:

npm install @11ty/eleventy-plugin-rss

In the configuration file .eleventy.js, added the plugin to generate a feed template (again, this is taken from the Eleventy website – I put the const above module.exports and the addPlugin goes with the plugins I already installed):

const { feedPlugin } = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(feedPlugin, {
		type: "atom", // or "rss", "json"
		outputPath: "/feed.xml",
		collection: {
			name: "posts", // iterate over `collections.posts`
			limit: 10,     // 0 means no limit
		},
		metadata: {
			language: "en",
			title: "Brian's Blog",
			subtitle: "The blog on Brian's website.",
			base: "https://www.brianjasonford.com/",
			author: {
				name: "Brian Jason Ford",
				email: "", // Optional
			}
		}
	});
};

As soon as that plugin is saved in .eleventy.js, when Eleventy runs it will create a feed.xml fille in /public.
In blog.md, below the "Posts by Date" section, add:

<section>
<h2><i class="fa-solid fa-rss"></i> Blog Feed</h2>

[Add this feed to your reader of choice.](/feed.xml)
</section>

In posts.njk, under the tags, add:

<br><strong>Subscribe:</strong> <a href="/feed.xml">Blog Feed</a>