Static Site Generators - freeCodeCamp.org

Lume SSG Handbook – How to Create a Static Blog with Lume

Rajdeep Singh — Fri, 18 Nov 2022 17:06:55 +0000

Lume is a new static site generator based on Deno. Deno is a JavaScript-based run-time environment that supports TypeScript.

Lume is not built around any specific language. It supports Markdown, Nunjucks, TypeScript, and JavaScript by default. Lume also supports plugins. Some plugins come preinstalled by default. This is why Lume itself is template-language agnostic.

Before learning more about Lume, let's discuss Deno and consider some important Deno features.

What is Deno?

Deno is an alternative to Node.js built by Ryan Dahl (who also developed Node). Deno is based on the Rust programming language, and the second main component in Deno is the JavaScript V8 engine for WebAssembly.

Deno has many cool features – it's fast, secure by default, is compatible with web assembly and has TypeScript support, has in-built development tools, and more. Deno also supports Node.js APIs so you can use all npm packaged with Deno.

In Deno, you do not need to create a configuration file to run a simple program. You simply deploy your website instantly with a second on-edge network. But my final favorite feature is the new node_modules folder in the workspace. Deno caches all the packages locally and uses them, which is very fast compared to Node.

You can check out the demo blog website here, and all the code is available on GitHub here.

Now let's dive into the tutorial.

Lume + Markdown
Why is Lume special?
How does Lume compare to other static site generators?
How to start a new project with Lume
Lume folder structure
Additional folders
How to create global data
How to create a dynamic page
How to create a Home and Pagination page
How to build an articles page
How to generate a category page
How to generate a tag page
How to enable search functionality
How to install page find
Lume SEO
Lume Sitemap
Lume plugins
How to enable comments
How to use Netlify CMS with Lume
How to deploly your blog with Deno Deploy
Github pages
Conclusion

Lume + Markdown

Lume is a new static site generator based on Deno created and maintained by Óscar Otero. Lume uses markdown-it as the default markdown. You can use the remark plugin to change the default markdown.

Markdown is a language that helps to write documents, readme files, and blogs on the internet. John Gruber created markdown in 2004.

Markdown-it is similar to GitHub-flavored Markdown (GFM) markdown. GFM and markdown-it both follow the exact markdown specifications.

If you've worked with GitHub and written README files, that means you are likely familiar with GFM markdown. If you don't like the default (markdown-it) markdown, you can change the markdown with the remark plugin.

There are tons of static site generators. So why is Lume special? What does it provide compared to other static site generators? Let's find out.

Why is Lume special?

As you know, Lume is built on Deno, and Deno is a Node.js alternative—that is why Lume provides lots of features out of the box.

Lume works similarly to a GitHub readme file. If you're familiar with writing one of those (and using markdown), you do not need to learn anything else to write articles and documentation with Lume.

Here are some benefits of Lume:

Lume supports multiple template engines like Markdown, Nunjucks, Eta, JSX, Liquid, or Pug.
It supports multiple authors
It has code syntax highlighting
There's great SEO support
Lume supports multiple languages
It has Windi CSS support
There's pagination and component support
It supports minifying JavaScript, HTML, CSS, and SASS
It has relations support
There is the built-in search functionality
It supports Netlify CMS
It supports images and SVGs
There's Remark.js plugin support
You can deploy with Netlify, Vercel, GitLab Pages, and the GitHub page.

How Does Lume Compare to Other Static Site Generators?

Lume is a new static site generator compared to others, but it comes with many configuration options, and you can do anything with it. You don't even need to use any third-party plugins.

With Lume processors and preprocessors, you can easily manipulate the HTML code with the JavaScript DOM API. Other static site generators support a few template engines, but Lume supports many template engines like JavaScript, JSX, Nunjucks, Eta, JSX, Liquid, and Pug.

Note that Lume can seem tough to get started with for beginners. But if you're following my article, just make sure to open the code which will make things much clearer for you.

How to Start a New Project with Lume

You can set up a new project with the Lume CLI with this command:

deno run -Ar https://deno.land/x/lume/init.ts

Lume installation demo

Follow these steps:

First, create an empty mkdir lume-deno folder project.
Then run the lume init.ts command.
Select an available plugin from the list.

And you should be up and running.

Lume Folder Structure

After the installation finished, we saw three files:

_config file is used to configure Lume.
deno.json is a defined script or task for Deno.
import_map.json is to help you import a Deno package for the internet.

lume default folder structure

How to run the Lume server

To run a local development server, you'll use the deno task lume --serve command. To build a website, run the deno task build command.

If you face a 404 - not found error, you can create a index.njk file within the root folder.

In the index.njk file, paste the following code.

---
title: "hello"
---
hello world

And you'll see the following output:

Lume hello-world

Additional folders:

posts folder is not a compulsory folder. It contains all your posts' markdown files.
pages folder is not a compulsory folder. It has all your pages' markdown files.
author folder is not a compulsory folder. It has all your author markdown files.
_components folder is a compulsory folder. It has all your components.
_includes folder is a compulsory folder. It contains your layout and templates for your site.
images folder is not a compulsory folder. It contains all your images.

The posts, pages, authors, and images folders are optional. You can rename these folders according to your wishes. The _components and _includes folders are mandatory and you don't rename them.

The difference between components, layout, and template are as follows:

The components are reusable code
The layout and template are not reusable like components.

How to Create Global Data

In Lume, you can create a data variable, which has access to the entire website by all template engines.

// Set a variable
site.data("post_per_page", 10);

// Set a function
site.data("randomNumber", function () {
  return Math.random();
});

How to create posts, pages, and author markdown files

You create posts, pages, and author folders in the root folder. Then, inside every folder, you write markdown files.

You can access all posts, pages, and authors by file name on the browser:

localhost:3000/posts/your-title.html
localhost:3000/pages/your-pages.html
localhost:3000/author/your-author.html

Suppose you need a demo post, pages, and author markdown for a project or template. Then, you can use demo-markdown posts for your project. It is free and open source, and you can create your own template.

How to create a dynamic page

In Lume, .tmpl.js and .tmpl.ts extensions use JS and TS as template engines. You can use them with regular pages or dynamic pages to create categories, tags, pagination, and so on for your website.

How to create a home and pagination page

The home page is based on pagination, and pagination is based on posts. Lume dynamically generates the pagination.

In Lume, I chose nunjucks and JavaScript to create my demo website. Nunjucks is the default template engine. You can easily change the default Nunjucks engine with another template engine with copy-paste code.

home page

Lume provides a JavaScript template function that helps create dynamic web pages. If you create a home page for the site, you need to create an index.tmpl.js file in your root or src folder. Lume also supports an src folder to organize your project. In my demo project, I'm not using the src folder.

The *.tmpl.js is an extension of a JavaScript template that helps create dynamic pages for websites. It comes pre-installed in Lume with the modules plugin.

For example, the following code creates pagination for your website. But the layout comes from the _includes folder.

// index.tmpl.js

// title for SEO
export const title = "Minimalist blog"
// description for SEO
export const description = "Minimalist blog theme is liteweight and work with lume."

export default function* ({ search, paginate }) {

//  Get all posts of type article.
  const posts = search.pages("type=article", "date=desc");

  // Configation for pagination
  const options = {
    // Page 1 is the homepage, set "/" as url
    url: (n) => n === 1 ? "/" : `/page/${n}/`,
    // par page posts
    size: 7,
  };

  // Yield the pages, but the index needs a different layout
  for (const page of paginate(posts, options)) {

    //  if home page, use diffrent layout "/"
    if (page.pagination.page === 1) {
      page.menu = {visible: true, order: 1, title:"Home" }
      page.title = "Home page"

      //  comes from _includes folder

      page.layout = "layouts/home.njk";
    } else {
      // Render diffrent layout if it is not home page page "/page/2","/page/3",etc
      page.title = "Pagination page"

      page.layout = "layouts/home.njk";
    }

    yield page;
  }

}

‌Lume has a search plugin that helps you search pages. In my demo blog, I search all pages base on the type.

In my all posts folder, all posts are defined in type=article, the author is described in type=author, and pages are defined in type=page . The search plugin is pre-installed with Lume.

On index.tmpl.js file, you can get all pages that have the type "article" (type=article ) using the following code: const posts = search.pages("type=article", "date=desc");. The search.pages("type=article", "date=desc") function only returns those that have type=article .

The layouts/base.njk layout file contains an HTML base and includes a header and footer for the website.



  
    
    
    {{ title }}
    
   
  

    {% include "layouts/header.njk" %}

    
      {{ content | safe }}
    

    {% include "layouts/footer.njk" %}

Inside the {{ content | safe }}, Lume renders other HTML, like cards, articles, home templates, Tag and category pages, and so on.

// rest code ...
  for (const page of paginate(posts, options)) {
  }
// rest code ...

I used the for loop on the index.tmp.js file that helps get all the posts and send them to the layouts/home.njk file and the layouts/home.njk file. You get all posts from the result, and then pass them to the card.njk template.

---
layout: layouts/base.njk
---

{% for post in results %}
    {% include "templates/card.njk" %}
{% else %}
     Posts is empty 
{% endfor %}

{% include "templates/pagnation.njk" %}

‌The templates/card.njk file runs for all blogs and generates HTML for each blog. Your card looks like this:

card.njk

In card.js template, you can access it using {{}} curly brackets. Get the title using {{post.data.title}} and {{post.data.description}}.

In my demo blog, I'm getting only the first category to show inside the card. So I use a defined filter _config.ts and use it with | symbols. Inside card.njk we get a zero index or first value in from categories with the following code: {{ post.data.category | category }}.

To get the author on card.njk I define the relationship between the article and the author type, which you can learn about from the docs.



    

        

        

            
                {{ post.data.category | category }}
            

            {{ post.data.title }}

            
                {{ post.data.description }}
            

            Read more


            

                {% if post.data.author.length <= 2 %}

                    {% for author in post.data.author %}

                        

                        
                            
                                {{ author.author_name}}
                            
                                {{author.job}}
                            
                        
                    {% endfor %}
                {% else %}

                    

                    
                        
                            {{ post.data.author.author_name}}
                        
                            {{post.data.author.job}}
                        
                    
                {% endif %}

The {{ title }} and {{description}} both show the markdown file title and description. To show the category, I used a filter to show a single category on the article page and define the filter on _config.ts file. I also show single and multiple authors with For loop. Every card has its own post.data.url property, after the user clicks on the read more button user ago respected the article read page. To show the image, I used {{ post.data.image }} property. I also show single and multiple authors with For loop on card.njk file.

How to Build an Articles Page

I know the page containing the article content is one of the most important for a blog. It's where readers should spend most of their time rather than the website's home page.

---
category:
  - Blog
date: 2022-03-20T13:09:24Z
description: Dolor excepteur ad ad fugiat Lorem consectetur velit excepteur duis qui.
image: /images/dice.jpg
tags:
  - npm
  - npm cli
  - npm install command
title: Random blog Title for markdown.
draft: false
author_id: 1
type: article
layout: templates/article.njk
---

Laboris consequat elit ad excepteur. Ipsum duis amet dolore voluptate dolore consequat ullamco incididunt ullamco. Dolore laborum cupidatat dolor ipsum reprehenderit excepteur cupidatat dolore.

## First
Cupidatat non amet irure esse quis aute qui enim. Est qui ullamco proident consequat aute reprehenderit eiusmod nisi. Laboris ullamco fugiat sint occaecat.

## Second 
Irure fugiat officia non esse esse irure eu sint commodo quis amet. Dolor culpa non amet elit adipisicing exercitation ex anim velit ipsum.

## conclusion
Culpa irure eiusmod labore ut proident sit enim laborum nulla voluptate eu. Id tempor velit cillum pariatur est laboris ipsum ad. Sint nostrud nostrud laboris Lorem consequat tempor voluptate dolore velit. Commodo elit nulla commodo pariatur. Deserunt ipsum fugiat id ipsum pariatur cupidatat magna ex. Fugiat aliquip nisi laboris aliquip velit velit id quis eu reprehenderit excepteur fugiat.

I created an article in the posts folder under type=article . The author_id defines the relation between the author and the article.

I used templates/article.njk as the layout for my articles page. You can design yours as per your requirements. You can design the article title, description, author card, and tags as well.

---
layout: layouts/base.njk
---

  

    {{ title }}
    {{ description }}

    {% if author %}
      


        {% if author.length <= 2 %}

          {% for author in author %}

            

            
              
                {{ author.author_name}}
              
                {{author.job}}
              
            
          {% endfor %}

        {% else %}

          

          
            
              {{ author.author_name}}
            
              {{ author.job}}
            
          
        {% endif %}

      

    {% endif %}

      
        {% for tag in tags %}
          {{ tag }}
        {% endfor %}
      

    
      {{ date | date('HUMAN_DATE') }}
    


  

  
    {{ content | safe }}
  


{%- set previousPost = search.previousPage(url, "type=article") %}

{% if previousPost %}
  
    {%- if previousPost %}
      
      ← Previous: {{ previousPost.data.title }}
      
    {% endif %}

    {%- set nextPost = search.nextPage(url, "type=article") %}
    {%- if nextPost %}
      
        Next: {{ nextPost.data.title }} →
      
    {% endif %}
  
{% endif %}

 

{# ==== #}
{#  Addding the utteranc Commenting script #}
{# ==== #}

 Comment

The layouts/base.njk file is the base file for our blog (which I've already explained). The {{ title }} and {{description}} both show the markdown file title and description.

To show tags on the article page, I used a for loop. I also showed single and multiple authors with the for loop.

To convert the date into a human-readable format, I used Lume date plugin and wrapped it with a date filter that looks like this: {{ date | date('HUMAN_DATE') }}. To show all markdown paragraphs, I used {{ content | safe }} .

For pagination, I used the Lume pagination plugin, and with the search.previousPage(url, "type=article") function, I showed the next and previous posts on the article page. For comments, I used utteranc.es.

How to Generate a Category Page

In Lume, you create a dynamic category based on article type. Lume also provides inbuilt functionality called a JavaScript template engine that helps you create a dynamic page. It is similar to creating pagination functionality.

In Lume, there's a special file called .tmpl.js that helps you create a dynamic category.

export const layout = "layouts/category.njk";

export default function* (props) {


  const { search }= props

  for (const category of search.values("category") ) {

    yield {
      url: `/category/${category}/`,
      title: `Categoryed ${category}`,
      type:"category",
      category,
    };

  }

}

In lume search.values() have a function that helps you find a category using markdown meta tags and sends data into the layout/category.njk file. It will generate all categories with the following URLs like /category/android/ , /category/android-phone/ , /category/human/ and so on.

How to Generate a Tag Page

Generating a dynamic tags page is similar to a category. Lume provides a special search.tags() function to generate tags:

export const layout = "layouts/tag.njk";

export default function* ({ search }) {

  for (const tag of search.tags()) {
    yield {
      url: `/tag/${tag}/`,
      title: `Tagged ${tag}`,
      type: "tag",
      tag,
    };
  }
}

The following code generates all tags with the following URLs like /tag/android/, /tag/android-phone/, /tag/human/ and so on.

How to Enable Search Functionality

Lume has many in-built plugins which provide an excellent development experience. You can solve lots of problems with Lume plugins, and they allow you to add and remove features easily.

Lume provides inbuilt search functionality for the site. You enable it with the lume page find plugin.

Add a search bar in lume

How to Install Page Find

The Lume page finds plugin provides you with a search bar. Simply copy the following code and paste it into the _config.ts file and restart your server.

import pagefind from "lume/plugins/pagefind.ts";

How to configure the page find plugin

You configure the plugin in the _config.ts fil. You can also change the default config.

// rest of code ...
import lume from "lume/mod.ts";
import pagefind from "lume/plugins/pagefind.ts";

const site = lume();

// config the pagefind plugin with default config
site.use(pagefind());

 // or 

// change the default config in pagefind plugin
site.use(pagefind({
  ui: {
    containerId: "search",
    showImages: false,
    showEmptyFilters: true,
    resetStyles: true,
  },
}));

export default site;

Lume SEO

Lume has a plugin to help with SEO called metas. With the plugin, you can easily add various SEO-friendly configurations.

How to install metas

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import metas from "lume/plugins/metas.ts";

How to configure metas

You can configure metas in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";

// install metas plugin for SEO
import metas from "lume/plugins/metas.ts";

const site = lume();

// config the metas plugin with default config
site.use(metas());

or

// add custom config 
site.use(metas({
  defaultPageData: {
    title: "title", // Use the `title` value as fallback.
  },
}));


export default site;

How to Use the Metas SEO Plugin in Lume

To use the SEO metas plugin, you'll need to create a _data.yml file in the root of the project folder and paste the following code into it:

metas:
  site: Minimalist blog
  twitter: "@Official_R_deep"
  icon: /images/icon.png
  lang: en
  generator: true

mergedKeys:
  metas: object

The following code helps you create all the various SEO tags for your website, and you can easily extend it with the metas plugin in Lume.

Lume Sitemap

Lume has a plugin called sitemap. This plugin helps you create sitemaps for your blog. With Lume 13 you do not need to create a sitemap manually.

How to install the sitemap plugin

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import sitemap from "lume/plugins/sitemap.ts";

How to configure the sitemap plugin

You can configure the sitemap plugin in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";
import sitemap from "lume/plugins/sitemap.ts";

const site = lume();

site.use(sitemap());

// or

// add custom config 
site.use(sitemap({
  filename: "my-sitemap.xml", // to change the sitemap filename
  query: "indexable=true", // Select only pages with the indexable attribute as true
  sort: "date=desc", // To sort by data in ascendent order
}));

export default site;

How to use the sitemap plugin in Lume

You do not need any special file to use the site map plugin. Simply add the plugin after calling the plugin in config.ts and it'll start working on your site. This creates the sitemap.xml file and you can change the file name with a custom configuration in _config.ts file.

How to access the sitemap on the website

You can access the sitemap with the filename, for example by default in the localhost [http://localhost:3000/sitemap.xml](http://localhost:3000/sitemap.xml) and production [http://my-domain-name/sitemap.xml](http://localhost:3000/sitemap.xml) .

Lume Plugins

Lume comes with inbuilt plugins, but you can easily add or remove features according to your requirements. You do not need all the stuff on your site – you can configure everything as you wish.

You can add more template engines, minify HTML, CSS, and JavaScript with plugins, enable code highlighting, date manipulation, image manipulation, SVG support, and more.

You can also easily create your own plugins with lume. Lume also provides excellent documentation where you can learn more.

How to Enable Comments

To add comments on your Lume site, I think utteranc.es is the best choice for all static site generators. utteranc.es is an open-source commenting system based on GitHub. It looks like this:

Enable comment

If you want to enable comments on the site, the first step is to install an utterances application on GitHub. Then, copy and paste the following code into the article read file or where you show comments on the site.

Next, you'll need to change the utterance comment script. The first change in the repo repo="your-github-repo" name is compulsory. The others are not. You can adjust according to your requirements – for example, changing the theme, issue term, and so on.

To read more about utterance, here's a great article written by Josh Collinsworth.

The best approach is to add utterance comments in lume and then read the GitHub discussion.

How to Use Netlify CMS with Lume

Netlify CMS is an open-source content management system. You can easily integrate Netlify with Lume using the netllify_cms plugin. It is provided by Lume, and you just need to install it and copy/paste the code.

How to Install the Netlify Plugin

Import the Netlify plugin in your _config.ts file to use it like this:

import lume from "lume/mod.ts";
import netlifyCMS from "lume/plugins/netlify_cms.ts";

const site = lume();

site.use(netlifyCMS());

export default site;

To configure it, you'll need to create a /_data/netlify_cms.yml file in the root level and then paste the following code after restarting your server:

backend:
  name: git-gateway
  branch: master

media_folder: statics

collections:
  - label: Posts
    name: posts
    description: List of posts
    folder: posts
    extension: md
    create: true
    fields:
      - label: Title
        name: title
        widget: string
      - label: Content
        name: body
        widget: markdown

Netlify will ask you for permissions for the CMS proxy. Type npx netlify-cms-proxy-server in a terminal, press enter or type y, and your Netlify CMS will start running locally on http://localhost:3000/admin URL. Now your Lume blog is ready for deployment on Netlify.

How to Deploy Your Blog with Deno Deploy

You can deploy Lume on various platforms such as Deno Deploy, GitHub Pages, Gitlab Pages, Netlify, Vercel, Fleek, AWS Amplify, and Cloudflare Pages. Lume also provides excellent documentation on deployment.

In this article, I'm deploying my Lume blog with Deno Deploy (and we'll also see how to do it with GitHub pages). Deno Deploy is an official platform built by the Deno team to deploy Deno-based applications.

Before deploying your Lume blog on Deno Deploy, make sure you create a server.ts file in the root level.


import Server from "lume/core/server.ts";

const server = new Server({
  port: 8000,
  root: `${Deno.cwd()}/_site`,
});

server.start();

console.log("Listening on http://localhost:8000");

Deployment Steps:

Create an account on Deno Deploy.
Push your local code to GitHub and then select the server.ts file. Deno Deploy automatically creates a site based on the server.ts the file.
Make sure to first create a custom server.ts file. Then move to the next step.
The easiest way to deploy your site is with GitHub Actions. Create a new .github/workflows/deno.yml file in your project root level and paste the following code into it:

name: Deploy
on: [push]

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Needed for auth with Deno Deploy
      contents: read # Needed to clone the repository

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      # TODO: add a build step here

      - name: Upload to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: "minimalist-blog"
          entrypoint: "./serve.ts"

How to Deploy Your Blog with Github Pages

GitHub Pages are free static sites you can use to host pages. You can also deploy your Lume blog it. The process of deployment is pretty easy.

To deploy Lume on GitHub pages you need to have GitHub Actions set up.

Deployment Steps

It's best if you have a GitHub repository so you can convert your local website to GitHub Pages.
Create a new repo and push all your local code into it.
Create a new .github/workflows/deno.yml in your project root level, then paste the following code into it and push it into the GitHub repo. The GitHub action runs based on the github.yml action and it generates a GitHub page.

name: Publish on GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      - name: Setup Deno environment
        uses: denoland/setup-deno@v1
        with:
          deno-version: v1.x

      - name: Build site
        run: deno task build

      - name: Deploy
        uses: crazy-max/ghaction-github-pages@v3
        with:
          build_dir: _site
        env:
          GITHUB_TOKEN: ${{ secrets.MY_GITHUB_TOKEN_PAGE }}

You need a GitHub token to deploy your Lume website to GitHub pages. This is a required part of the setup. I found a great article written by Davide that can help you learn more about GitHub Actions and how to create one.

GitHub Actions takes two or three minutes to finish hosting your website on GitHub Pages.

Check out the GitHub repository to learn how to configure the GitHub workflow for GitHub pages. You can also see a live demo website on the GitHub page.

A quick note: if you deploy your Lume site on GitHub pages and your image does not show on the website, there are two possible reasons for this:

If all image names aren't in lowercase, you might get an error. To resolve the error, convert your image names into lowercase with this command: your.github.com/your-reponame/images/my-image.png
If you're using the base_path and relative_urls Lume plugins in your project and relative_urls is redundant, and then you'll need to remove the relative_urls plugin in your project. Your image should now work fine.

Conclusion

Lume is an easy-to-learn and feature-rich static site generator. You can do anything you imagine with it. Lume gives you a lot of freedom with the code.

The Lume community is not as big as those of Hugo, 11ty, Jekyll, and other tools. But, the Lume maintainers actively reply to everybody who comments in the GitHub discussion. Without a strong community, this tool should be able to create a strong impact.

One challenge with Lume is that it's tough to get started for beginners and is more suited to intermediate and advanced developers. If you're jumping right into using Lume as a beginner, you might struggle with a lack of background knowledge about how static site generators work.

Because of this, it's helpful to have a little bit of knowledge about Nuckjunks, JSX, and other template engines that work based on markdown. Once you gain this experience, then you'll easily be able to use Lume to design your markdown-based blog.

I recommend using the lume MDX plugin for markdown. You can use JSX-based components inside the markdown file, and you can create beautiful code blocks, tip blocks, and so on.

I highly encourage all developers to try Lume out. If you have problems with Lume, you can reach out to its creator on the GitHub discussion and the Discord server.

If your course is about Computer science, Bioinformatics, and Biotechnology. You can join my free newsletter.

Learn the Eleventy Static Site Generator by Building and Deploying a Portfolio Website

Gerard Hynes — Tue, 06 Sep 2022 16:26:13 +0000

What is Eleventy?

Eleventy (also called 11ty) is a simple yet powerful static site generator. It uses JavaScript to transform data and templates into HTML pages.

It’s beginner-friendly, has fast build times, and generates fast sites by default. It also has a very active and friendly community.

Eleventy excels at content-driven sites and is used by Google, Netlify, MIT, CERN, the A11y Project, ESLint, and more.

Since pages are generated ahead of time, they can be served as fast as possible from a Content Delivery Network (CDN). Eleventy also generates no client-side JavaScript, which helps your site to load faster.

In this tutorial, we're going to build a simple developer portfolio site to demonstrate some of the main features of Eleventy.

Eleventy portfolio homepage

We’ll learn about:

Setting up and configuring an Eleventy project
Templating and layouts
Handling CSS and images
Working with collections and data files
Shortcodes and Eleventy plugins
Deploying the site to Netlify

The portfolio site will have:

A Homepage
An About page
A Contact page (with contact form)
A Projects page
A page for each project (with case study)

Eleventy can pull in data from APIs, a Content Management System (CMS), or from local files. To keep things simple, we’ll store our project data in Markdown files.

The full code for the finished portfolio is available on GitHub. If you get stuck at any stage, please check your code against the finished site.

Prerequisite - Install Node.js
Initial Project Setup
How to Configure the Project
How to Add a Template
How to Use Templates in Eleventy
How to Use Layouts in Eleventy
How to Configure the CSS and Images
How to Use Partials in Eleventy
How to Use Collections in Eleventy
How to Use Directory Data Files
How to Use Collections in Templates
How to Use Shortcodes
How to Use the Eleventy Image Plugin
How to Build a Contact Form with Netlify Forms
How to Deploy to Netlify
Where to Take it from Here

Prerequisite - Install Node.js

If you don’t already have Node.js installed, go to nodejs.org and follow the instructions for your operating system.

Open a terminal and use node --version to make sure it’s installed. As long as it’s version 12 or newer, you’re good to go.

Initial Project Setup

First, create a directory for your portfolio. You can call it eleventy-portfolio or whatever you want.

Open this directory in a terminal and run npm init -y to create a package.json file with the default settings.

Next, install Eleventy using npm install --save-dev @11ty/eleventy.

In the root directory of the project, create a .gitignore file with the following contents so that Git doesn’t track any unwanted files:

node_modules
/public

How to Configure the Project

Eleventy is “zero-config” by default. If you don’t change anything, Eleventy will take all the files in your root directory, run a build process, and output the resulting files to a _site directory.

But Eleventy also has flexible configuration options that let you customize your build process, watch for changes in certain file types, and manipulate content with filters and shortcodes.

Your Eleventy configuration goes in a .eleventy.js file in the root of your project.

For example, the default input directory is the root directory of your project, while the default output directory is _site. Some people prefer to change this, with src and public being common choices.

If you’d like this structure, create src and public directories in the root of your project and then set them as the input and output directories in .eleventy.js.

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

In case you’re wondering, the eleventyConfig argument that is passed to the function is the default configuration object that Eleventy provides. Soon we’ll use this object to customize our Eleventy build process.

How to Add a Template

Let’s add our first template. We’ll keep things as simple as possible by using a Markdown file.

In the src directory, create an index.md with # Hello World from Eleventy as its contents. This is your first Eleventy template.

To build and view the site we can use the development server that comes with Eleventy.

In your terminal, make sure you’re in the root directory of your project and run eleventy --serve. This starts the development server, which will watch your src directory and automatically reload your site whenever you change your code.

After a moment you’ll see:

[Browsersync] Access URLs:
 ----------------------------------
    Local: http://localhost:8080
 External: http://your_ip_address:8080
 ----------------------------------
[Browsersync] Serving files from: public

Open a web browser and go to http://localhost:8080. Congratulations, you’ve made a (very simple) Eleventy site! 🥳🎉

At this stage, your project will have the following structure:

node_modules/
public/
src/
.eleventy.js
.gitignore
package.lock.json
package.json

Most sites need more than one page, so we’re going to need to learn more about templates.

Before we do that, we can customize our build commands if we want to. This step is entirely optional.

Optional Step – How to Create Custom Build Commands

The default command to run the development server is eleventy --serve, while the default command to build the site is eleventy.

If you’d like to replace these with different commands, such as start and build, open package.json and under scripts replace the “test” command with your preferred commands:

"scripts": {
    "start": "eleventy --serve",
    "build": "eleventy"
  },

Now we can use npm start in the terminal to start the development server and npm run build to generate a build of our site.

You can use ctrl/cmd + c to stop the development server whenever you need to.

How to Use Templates in Eleventy

Turning Markdown files into HTML is neat, but so far you aren’t really getting much benefit over just writing your site in plain HTML. This is where templates come in.

First, we need to clarify some terms:

Template – A content file that Eleventy will transform into a page, or pages, in the built site
Layout – A template that wraps around another template, usually to provide a structure to present content in
Partial – A template that makes up part of another template

Templates let you combine content and data to generate whatever HTML your site needs.

Layouts let you give multiple templates the same basic structure.

Partials let you build small reusable components that you can use in larger templates.

Eleventy supports ten different languages for templating, including: HTML, Markdown, JavaScript, Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml, and Pug. (In version 1.0 Eleventy added support for custom templates using any arbitrary file extension, but this is probably better reserved for more custom/advanced use cases).

You can even mix different templating languages in the same file, such as Markdown and Nunjucks, if you want to.

In this project, we’ll use Nunjucks. It’s a templating language for JavaScript created by Mozilla, and is pretty popular in the Eleventy community.

In the src directory, delete index.md and create an index.njk file. If you’re using VS Code, type ! + tab to generate the basic HTML structure for the page. Change the title to "Eleventy Portfolio" and in the element, add

`Home Page`

Your page should look like this:


"en">

  "UTF-8">
  "X-UA-Compatible" content="IE=edge">
  "viewport" content="width=device-width, initial-scale=1.0">
  Eleventy Portfolio


  Home Page

Next, still in src, create about.njk and contact.njk files. You can copy the contents of index.njk into them and replace the

with `About Page` and `Contact Page` respectively.

Start your dev server. if it isn’t already running. Go to `http://localhost:8080` to see the homepage, `http://localhost:8080/about` for the About page, and `http://localhost:8080/contact` for the Contact page.

In our portfolio site, each of these pages is going to have the same basic layout. So instead of writing the same code in each page template, we’re going to use Eleventy layouts.

How to Use Layouts in Eleventy

Layouts are templates that wrap around other templates, presenting the content in a consistent way.

Inside the src directory, create a _includes directory. This is going to contain all our layouts and partials.

Inside _includes, create a base.njk file. This will provide a standard layout for every page of our site.

Copy the following code into base.njk:


"en">

  "UTF-8">
  "X-UA-Compatible" content="IE=edge">
  "viewport" content="width=device-width, initial-scale=1.0">
  "description" content="I'm a Frontend software developer who builds sites and apps that help people reach their personal and professional goals."/>
  {{ title }}


  class="content">
    <header class="header container">
    <h1 class="header__title">
      <a href="/">Marie Jacksona>
    h1>
    <ul class="header__links">
      <li>
        <a class="header__link" href="/about">Abouta>
      li>
      <li>
        <a class="header__link" href="/projects">Projectsa>
      li>
      <li>
        <a class="header__link" href="/contact">Contacta>
      li>
    ul>
    header>
    <main class="main container">
      {{ content | safe }}
    main>
  div>
  <footer class="footer">
      <p>&copy; Marie Jackson 2022p>
  footer>
body>
html>

The content value will be the main content of whichever template we use with base.njk as its layout. safe is a filter that prevents this content from being escaped (having potentially unsafe characters replaced).

Now, change index.njk to be:

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

{{ title }} Home Page

Notice how the template has frontmatter data at the top of the file. By default this is written in YAML, but you can use other languages too.

This frontmatter lets you set values for your templates. In this case, the layout value tells the template to use the base.njk layout and the title value provides a title that we are using in our template's

tag.

Next, delete everything from about.njk and paste in the following content:

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

class="bio prose">
  <h2 class="heading--main">My storyh2>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Aliquet risus feugiat in ante metus dictum.p>

  <p>Tellus pellentesque eu tincidunt tortor aliquam nulla facilisi cras fermentum. Turpis egestas integer eget aliquet. Vestibulum morbi blandit cursus risus at ultrices mi tempus. Ut lectus arcu bibendum at. Integer enim neque volutpat ac tincidunt.p>

  <p>Commodo ullamcorper a lacus vestibulum sed arcu. Et tortor consequat id porta nibh venenatis cras sed. Nulla pharetra diam sit amet nisl. Ipsum nunc aliquet bibendum enim facilisis gravida neque convallis a. Nec sagittis aliquam malesuada bibendum.p>

  <p>Tellus pellentesque eu tincidunt tortor aliquam nulla facilisi cras fermentum. Turpis egestas integer eget aliquet. Vestibulum morbi blandit cursus risus at ultrices mi tempus. Ut lectus arcu bibendum at. Integer enim neque volutpat ac tincidunt.p>

  <p>Commodo ullamcorper a lacus vestibulum sed arcu. Et tortor consequat id porta nibh venenatis cras sed. Nulla pharetra diam sit amet nisl. Ipsum nunc aliquet bibendum enim facilisis gravida neque convallis a. Nec sagittis aliquam malesuada bibendum.p>
section>

Now delete everything from contact.njk and paste in this content:

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

class="heading--main text-center">Want to get in touch?h2>
<p class="contact__sub-heading text-center">I'm always open to new opportunities and projects. p>

<form class="form" name="contact" action="/success" method="POST" data-netlify="true">
  <div class="form__section">
    <label class="form__label" for="yourName">Namelabel>
    <input class="form__input" name="name" type="text" id="yourName" required="true">
  div>
  <div class="form__section">
    <label class="form__label" for="yourEmail">Emaillabel>
    <input class="form__input" name="email" type="email"  id="yourEmail" required="true">
  div>
  <div class="form__section">
    <label class="form__label" for="message">Messagelabel>
    <textarea class="form__input" name="message" id="message" rows="4" required="true">textarea>
  div>
    <button class="form__button" type="submit">Let's talkbutton>
form>

We’re going to learn about how this contact form will work later in the tutorial.

Our portfolio is starting to take shape, even though things still look really bare. Let's get our CSS and images working next.

How to Configure the CSS and Images

While Eleventy can understand supported templating languages out of the box, it needs to be configured to process CSS and image files. Fortunately, this doesn’t require much configuration. While we’re at it, we’re also going to add a favicon to the site.

Inside the src directory, create three folders: css, images, and favicons.

src directory structure

Inside the css directory, make a style.css file. Since this isn’t a CSS tutorial, I’m going to provide the CSS in the GitHub repo for the project. You can copy and paste it from there, but I’m not going to cover the CSS in any depth.

The images for this portfolio are also available in the images directory in the GitHub repo. Copy these images into the images directory of your project.

Finally, copy the files from the favicons directory in the GitHub repo into the favicons directory of your project.

In base.njk add these lines to the element:

"icon" href="/favicon.ico" sizes="any">
"apple-touch-icon" href="/apple-touch-icon.png">
"preconnect" href="https://fonts.googleapis.com">
"preconnect" href="https://fonts.gstatic.com" crossorigin>
"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
"stylesheet" href="{{'/css/style.css' | url | safe}}">

The first two links include the favicon, the next three will fetch the Inter font from Google fonts, and the last one will connect style.css to base.njk.

Now, if we reload our homepage we’ll see that… absolutely nothing has changed.

By default, Eleventy will only process template files. To tell it to include CSS files and images, we need to add a few lines of configuration.

Add these lines to the configuration function in .eleventy.js:

module.exports = function (eleventyConfig) {
  eleventyConfig.addPassthroughCopy("./src/css/");
  eleventyConfig.addWatchTarget("./src/css/");
  eleventyConfig.addPassthroughCopy("./src/images/");
  eleventyConfig.addPassthroughCopy({ "./src/favicons": "/" });

  return {
    dir: {
      input: "src",
      output: "public"
    }
  };
};

addPassthroughCopy tells Eleventy to pass the CSS, favicons, and image files through to the final build.

addWatchTarget tells the Eleventy dev server to watch the css directory and reload the site if the files in this directory change.

With the favicons, we’re also telling Eleventy to output these files to the root of the generated content so that the links in base.njk will work.

Restart the server and you’ll see that the CSS is finally being applied and the favicon is showing up. We'll include the images shortly.

Homepage with styles applied

About page with styles applied

Contact page with styles applied

The About page and Contact page are fairly self-contained. But the homepage for our site is going to have a couple of parts to it. It will consist of a header and footer, as well as a profile section, technologies section, and projects section. Each of these parts is going to use a partial.

Layout of portfolio homepage

How to Use Partials in Eleventy

Partials are templates that make up part of another template. Partials help us to think about our site in terms of reusable components that we can include whenever we need them.

In the _includes directory, create a header.njk and footer.njk file.

Cut the header element out of base.njk and paste it into header.njk.

Cut the footer element out of base.njk and paste it into footer.njk.

Back in base.njk add {% include "header.njk" %} where the header element used to be and {% include "footer.njk" %} where the footer element used to be.

base.njk should now have this content inside its tag:

class="content">
    {% include "header.njk" %}
    <main class="main container">
      {{ content | safe }}
    main>
div>
{% include "footer.njk" %}

The site won’t look any different but our base layout is already becoming more modular.

Next, still in the _includes directory, create a profile.njk file with the following content:

class="profile">
  <div class="profile__image-wrapper">
    <img class="profile__image" src="/images/profile.jpg" alt="Marie Jackson, Software Developer">
  div>
  <div class="profile__card">
    <p class="profile__text">Hi! I'm <span class="profile__text--highlight">Mariespan>, a mathematician turned software developer from Hampton, Virginia.p>
    <p class="profile__text">As a <span class="profile__text--highlight">Frontend Developerspan>, I love building sites and apps that help people reach their personal and professional goals.p>
    <p class="profile__text">I focus on speed, security and scalability, using React.js and Firebase to create rich, dynamic experiences.p>
    <p class="profile__text">I'm always open to new opportunities and projects. So don't hesitate to <a class="profile__link" href="/contact">get in toucha>.<p>
  div>
section>

Next, create a technologies.njk file with this content:

class="technologies">
  <h2 class="technologies__heading">Technologies I love to work withh2>
  <ul class="technologies__list">
    <li class="technologies__item">
      <div class="technologies__logo">
      <img src="/images/javascript.svg" alt="JavaScript logo">
      div>
      <h3 class="technologies__title">JavaScripth3>
    li>
    <li class="technologies__item">
      <div class="technologies__logo">
      <img src="/images/react.svg" alt="React.js logo">
      div>
      <h3 class="technologies__title">React.jsh3>
    li>
    <li class="technologies__item">
      <div class="technologies__logo">
        <img src="/images/tailwindcss.svg" alt="Tailwind CSS logo">
      div>
      <h3 class="technologies__title">Tailwind CSSh3>
    li>
    <li class="technologies__item">
      <div class="technologies__logo">
        <img src="/images/firebase.svg" alt="Firebase logo">
      div>
      <h3 class="technologies__title">Firebaseh3>
    li>
  ul>
section>

In index.njk replace the

tag with:

{% include "profile.njk" %}
{% include "technologies.njk" %}

Portfolio homepage with profile and technologies sections

Our homepage is starting to take shape but the site still needs the most important part of any portfolio: projects.

To keep the project data organized, we’re going to use collections.

How to Use Collections in Eleventy

Collections let you group related content together. In our portfolio we’re going to create a projects collection using Markdown files to store information about each individual project.

Inside the src directory, create a projects directory. We’re going to need a Markdown file for each project. As placeholders, we’ll use three projects that I’ve been meaning to build.

Josh W Comeau has some great advice on building an effective developer portfolio and he strongly recommends describing your personal projects with detailed case studies. So for each of our projects we’re going to have a case study laying out:

What problem we solved
Why we chose these specific technologies
What challenges we faced
What lessons we learned

Copy the following three sample projects into the projects directory:

catch-up.md

---
title: "Catch Up"
summary: "Sometimes it's hard to keep in touch with friends and family. I made this app to remind me to schedule a call if we haven't talked in a while."
image: /images/catch-up.jpg
imageAlt: "Screenshots of catch up app"
tech:
  - "Next.js"
  - "Firebase"
  - "Tailwind CSS"
siteUrl: "#"
repoUrl: "#"
---

### Problem Solved

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Tincidunt tortor aliquam nulla facilisi. Feugiat scelerisque varius morbi enim nunc faucibus a pellentesque sit. Condimentum lacinia quis vel eros donec ac odio tempor orci.

### Technologies Used

Scelerisque eleifend donec pretium vulputate sapien nec sagittis aliquam. Diam sit amet nisl suscipit adipiscing bibendum est ultricies. Consequat ac felis donec et odio pellentesque diam volutpat commodo.

### Challenges Faced

Eget mauris pharetra et ultrices. Molestie nunc non blandit massa enim nec. Ut tortor pretium viverra suspendisse potenti nullam ac tortor vitae. Nulla at volutpat diam ut venenatis. Volutpat ac tincidunt vitae semper quis lectus nulla at.

### Lessons Learned

Non blandit massa enim nec. Tempor commodo ullamcorper a lacus vestibulum sed. Et netus et malesuada fames ac turpis egestas integer eget. In ante metus dictum at tempor commodo. Eu scelerisque felis imperdiet proin fermentum leo.

sourdough-sensei.md

---
title: "Sourdough Sensei"
summary: "Like a lot of people, I got really into sourdough in 2020. I made this app to help me bake delicious bread by putting all my recipes and schedules in one place."
image: /images/sourdough-sensei.jpg
imageAlt: "Screenshots of sourdough bread app"
tech:
  - "React.js"
  - "Firebase"
  - "Tailwind CSS"
siteUrl: "#"
repoUrl: "#"
---

### Problem Solved

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Tincidunt tortor aliquam nulla facilisi. Feugiat scelerisque varius morbi enim nunc faucibus a pellentesque sit. Condimentum lacinia quis vel eros donec ac odio tempor orci.

### Technologies Used

Scelerisque eleifend donec pretium vulputate sapien nec sagittis aliquam. Diam sit amet nisl suscipit adipiscing bibendum est ultricies. Consequat ac felis donec et odio pellentesque diam volutpat commodo.

### Challenges Faced

Eget mauris pharetra et ultrices. Molestie nunc non blandit massa enim nec. Ut tortor pretium viverra suspendisse potenti nullam ac tortor vitae. Nulla at volutpat diam ut venenatis. Volutpat ac tincidunt vitae semper quis lectus nulla at.

### Lessons Learned

Non blandit massa enim nec. Tempor commodo ullamcorper a lacus vestibulum sed. Et netus et malesuada fames ac turpis egestas integer eget. In ante metus dictum at tempor commodo. Eu scelerisque felis imperdiet proin fermentum leo.

spellbook.md

---
title: "Spellbook"
summary: "I'm a huge Dungeons and Dragons fan, but keeping my spells straight has always been a challenge. I built this app to put all the information I need at my fingertips."
image: /images/spellbook.jpg
imageAlt: "Screenshots of DnD project"
tech:
  - "Next.js"
  - "Firebase"
  - "Tailwind CSS"
siteUrl: "#"
repoUrl: "#"
---

### Problem Solved

Yes, I could have just used DnD Beyond. But where's the fun in that? Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Tincidunt tortor aliquam nulla facilisi. Feugiat scelerisque varius morbi enim nunc faucibus a pellentesque sit. Condimentum lacinia quis vel eros donec ac odio tempor orci.

### Technologies Used

Scelerisque eleifend donec pretium vulputate sapien nec sagittis aliquam. Diam sit amet nisl suscipit adipiscing bibendum est ultricies. Consequat ac felis donec et odio pellentesque diam volutpat commodo.

### Challenges Faced

Eget mauris pharetra et ultrices. Molestie nunc non blandit massa enim nec. Ut tortor pretium viverra suspendisse potenti nullam ac tortor vitae. Nulla at volutpat diam ut venenatis. Volutpat ac tincidunt vitae semper quis lectus nulla at.

### Lessons Learned

Non blandit massa enim nec. Tempor commodo ullamcorper a lacus vestibulum sed. Et netus et malesuada fames ac turpis egestas integer eget. In ante metus dictum at tempor commodo. Eu scelerisque felis imperdiet proin fermentum leo.

Just like with templates, the frontmatter at the top of these files makes values available that you can inject into your templates.

Since these Markdown files are ultimately inside the src directory, Eleventy will treat them as templates and create a HTML page from each file. Their URL will be in the format /subdirectory_name/filename, for example /projects/sourdough-sensei.

But Eleventy won't know what layout to use for these pages since they don't yet have a layout value in their frontmatter.

sourdough-sensei page without layout or frontmatter data

Right now these files aren’t a collection. Collections are defined by sharing a tags value, such as “tags”: “projects”.

Every file with the projects tag will be included in the projects collection.

Since we only have three projects, we could include a tags value in the frontmatter of our three Markdown files.

But if we had a site with a lot of content – for example dozens of blog posts, recorded talks, and tutorials that all shared dozens of tags between them – this could become difficult to manage. This is where directory data files are useful.

How to Use Directory Data Files

If you have certain values that are shared by every file in a folder, you can put these values in a directory data file.

Inside the projects directory, create a projects.json file. A directory data file should have the same name as the collection it’s attached to.

Any frontmatter fields that are shared by all the projects files should go in the projects.json directory data file:

{
  "layout": "project.njk",
  "tags": "projects"
}

The layout value means that every project will use the same layout (we’re going to create this project.njk file in a moment). The tags value is what turns them into the projects collection that we can use in our templates.

How to Use Collections in Templates

We’re now going to use the projects collection to:

Add a projects section to our homepage
Create a Projects page
Create a case study page for each project

To include data from a collection on a page of your site, you need to reference the collections object in a template.

We can use Nunjucks to loop over the collection and output its contents. To access a frontmatter value from a project in the projects collection, we use project.data.

For example:

{% for project in collections.projects %}
{{ project.data.title }}
{% endfor %}

In the _includes directory, create project.njk, project-card.njk and project-grid.njk files.

_includes directory structure

We’ll use project.njk to create a page for each of our projects.

Since these pages are generated from templates, we can access their frontmatter values directly, such as title, image, imageAlt, and content for the main content of the Markdown file.

---
layout: "base.njk"
---

class="project">
  <h2 class="project__heading">{{ title }}h2>
  <div class="project__image-wrapper">
      <img class="project__image" src="{{ image }}" alt="{{ imageAlt }}">
  div>
  <div class="project__content prose">
    {{ content | safe }}
  div>
div>

project-grid.njk and project-card.njk will form the list of projects on our portfolio homepage and Projects page.

project-grid.njk will loop over the projects collection and insert a project-card partial for each project in the collection.

Add the following content to project-grid.njk:

class="projects">
  <h2 class="project__heading">Recent projectsh2>
  <div class="project-grid">
    {% for project in collections.projects %}
      {% include "project-card.njk" %}
    {% endfor %}
  div>
section>

Add the following content to project-card.njk:

class="project-card">
  <div class="project-card__image-wrapper">
    <img class="project__image" src="{{ project.data.image }}" alt="{{ project.data.imageAlt }}">
  div>
  <div class="project-card__body">
    <div class="project-card__tags">
      {% for tag in project.data.tech %}
        <span class="project-card__tag">{{ tag }}span>
      {% endfor %}
    div>
    <h3 class="project-card__title">
      <a href="{{ project.url }}">{{ project.data.title }}a>
    h3>
    <p class="project-card__summary">{{ project.data.summary }}p>
    <a class="project-card__link" href="{{ project.url }}">Read project case study 
      <svg xmlns="http://www.w3.org/2000/svg" class="project-card__link-icon" viewBox="0 0 20 20" fill="currentColor">
        " d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clip-rule="evenodd" />

Since project-card.njk is accessing frontmatter values from a member of a collection, we need to use project.data to access these values in the template. Eleventy also generates a project.url value that we can use to link to the project's generated page.

In index.njk, add {% include "project-grid.njk" %} underneath the profile and technologies partials.

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

{% include "profile.njk" %}
{% include "technologies.njk" %}
{% include "project-grid.njk" %}

Grid of project cards on homepage

Next we're going to create a Projects page. In the src directory, create a projects.njk file with the following contents:

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

class="projects__heading">Recent projectsh2>
<div class="project-list">
  {% for project in collections.projects %}
    {% include "project-card.njk" %}
  {% endfor %}
div>

Projects page

The projects are now being displayed on our homepage as well as the projects page, and each project now has its own page with its case study.

We could stop here, but there are a few more Eleventy features that will make our portfolio site even better, namely shortcodes and plugins.

How to Use Shortcodes

A shortcode is a way to inject reusable content (often a JavaScript string template literal) into your templates.

We’re going to create a simple year shortcode that outputs the current year so that the footer in our portfolio site is always up to date.

Add the following line to the configuration function in .eleventy.js.

eleventyConfig.addShortcode("year", () => `${new Date().getFullYear()}`);

When you use the shortcode in a template the function will be run and the year value will be injected into the template.

In footer.njk use {% year %} to access the year shortcode.

class="footer">
  <p>&copy; Marie Jackson {% year %}p>
footer>

You might need to restart your development server for it to recognize the shortcode.

Now whenever you trigger a build of your site in the future, your footer will always show the correct year.

Shortcodes can do a lot more than this. Next, we’re going to use the Eleventy Image plugin, which uses shortcodes, to optimize our site’s images and improve our page load speed.

How to Use the Eleventy Image Plugin

Eleventy has a number of official plugins, from ones to check your writing for inclusive language to others that let you leverage Serverless functions.

The Image plugin is particularly useful since images are often the largest resource your site loads. It optimizes your images so your site uses the appropriate size and format for the user's browser, saving bandwidth for your user and making your site load faster.

First we need to install the Image plugin from npm. In the root of your project, run:

npm install @11ty/eleventy-img

At the top of .eleventy.js, we’re going to import the Image plugin and configure the shortcode that the plugin will use to optimize our images.

const Image = require("@11ty/eleventy-img");

async function imageShortcode(src, alt, sizes) {
  let metadata = await Image(`./src${src}`, {
    widths: [300, 800, null],
    formats: ["avif", "jpeg"],
    urlPath: "/images/",
    outputDir: "./public/images/"
  });

  let imageAttributes = {
    alt,
    sizes,
    loading: "lazy",
    decoding: "async"
  };

  return Image.generateHTML(metadata, imageAttributes);
}

The image shortcode takes in arguments for src, alt and sizes. These will be the URL for the image, the text for the image’s alt tag, and the sizes that are used to display different sized images at different screen sizes.

The widths property specifies what size images the plugin will generate. In this case, 300px, 800px, and the image's original size.

The formats property specifies which image formats to generate. Here we're using avif (which produces high quality images at low file sizes) with jpeg as a fallback for browsers that don't support avif.

urlPath and outputDir tell the plugin where to get the images from and where to output the optimized images to.

The plugin adds loading and decoding attributes to the generated HTML to lazy-load the images and decode them asynchronously, both of which will help with page load times.

Next, we’re going to include the shortcode in our configuration function. We'll call it EleventyImage for the sake of clarity.

eleventyConfig.addNunjucksAsyncShortcode("EleventyImage", imageShortcode);

Notice that we’re using addNunjucksAsyncShortcode rather than addShortcode. This is because the image generation process is asynchronous. It will take some amount of time to generate different image sizes and formats and we want our shortcode to wait until these have all been generated before it injects the finished HTML into our templates.

Since our shortcode is asynchronous, we’re going to run into an issue with using this shortcode inside a Nunjucks for loop. We need to use asyncEach, the asynchronous version of Nunjuck’s for.

In projects.njk and project-grid.njk, replace this:

{% for project in collections.projects %}
{% include "project-card.njk" %}
{% endfor %}

with this:

{% asyncEach project in collections.projects %}
{% include "project-card.njk" %}
{% endeach %}

Now, in project.njk we can replace this:

class="project__image" src="{{ image }}" alt="{{ imageAlt }}">

with this:

{% EleventyImage image, imageAlt, "(min-width: 30em) 50vw, 100vw" %}

The image, imageAlt and "(min-width: 30em) 50vw, 100vw" values are the src, alt and sizes parameters for the Image shortcode.

Next, in project-card.njk, we can replace this:

class="project-card__image" src="{{ project.data.image }}" alt="{{ project.data.imageAlt }}">

with this:

{% EleventyImage project.data.image, project.data.imageAlt, "(min-width: 30em) 50vw, 100vw" %}

Finally, in profile.njk we can replace this:

class="profile__image" src="/images/profile.jpg" alt="Marie Jackson, Software Developer">

with this:

{% EleventyImage "/images/profile.jpg", "Marie Jackson, Software Developer", "(min-width: 16em) 50vw, 100vw" %}

When our site builds, the Eleventy Image plugin will do a couple of things:

there will be multiple formats and sizes for every image in public/images
our generated HTML will now use the element
the tags will have loading="lazy" and decode="async" attributes

Now our site will serve the optimal image format and size depending on the browser and screen size of the site visitor. And images will be lazy loaded as they are about to enter the viewport.

If we use the network tab in a browser's developer tools, we can test the difference. On an iPhone 12, the unoptimized image on one of our project pages would be 30.37KB, while the image optimized by the Image plugin is just 6.01KB, an 80% saving!

Unoptimized image on mobile - 30.37KB

Optimized image on mobile 6.01KB

We’re almost ready to deploy our site. But before we do that, we need to complete our contact form.

How to a Build Contact Form with Netlify Forms

Contact page

Eleventy is a static site generator. But Eleventy works really well with the Jamstack architecture, where you statically generate as much of a site as possible in advance and use APIs and third-party services to add dynamic content and functionality.

In the past, if you wanted to have a contact form on your website, you would need some sort of server, such as a PHP app, to process the form submission.

We’re going to use Netlify Forms to add a contact form to our portfolio without needing to manage a server to handle the submitted forms.

To make this work, we need to make sure our form has two attributes. The most important one is data-netlify="true". The other is action="/success".

class="form" name="contact" action="/success" method="POST" data-netlify="true">
  <div class="form__section">
    <label class="form__label" for="yourName">Namelabel>
    <input class="form__input" name="name" type="text" id="yourName" required="true">
  div>
  <div class="form__section">
    <label class="form__label" for="yourEmail">Emaillabel>
    <input class="form__input" name="email" type="email"  id="yourEmail" required="true">
  div>
  <div class="form__section">
    <label class="form__label" for="message">Messagelabel>
    <textarea class="form__input" name="message" id="message" rows="4" required="true">textarea>
  div>
    <button class="form__button" type="submit">Let's talkbutton>
form>

By having a data-netlify="true" attribute on our contact form, when the site is deployed to Netlify, Netlify will recognize this and take over handling the form submission.

By default, when someone completes a Netlify form, they will get a generically styled success message with a link back to the form page. But we can direct them to a custom page by including an action attribute on our form.

The action="/success" attribute means that when the form submits, the user will be redirected to a "success" page on your site (you can give this page a different name if you like). So we had better build that page now.

In the src directory, create a success.njk file with the following content:

---
title: "Eleventy Portfolio"
layout: "base.njk"
---

class="container text-center">
  <h2 class="heading--main">Thanks for getting in touch!h2>
  <p>I'll respond as soon as I can.<p>
div>

Once we deploy the site to Netlify, any submitted forms will show up in the Netlify interface. So let’s finally deploy our portfolio site.

How to Deploy to Netlify

You can deploy an Eleventy site on any static hosting platform: Netlify, Vercel, GitHub Pages, even an AWS S3 bucket.

I'll show you how to deploy to Netlify since we're using Netlify Forms for our contact form. On another hosting platform, you could use a Serverless function to handle submitting the form and sending an email.

If you don't already have a Netlify account, go to netlify.com and create a free one.

Netlify will give you the option to:

Import an existing project
Start from a template
Deploy manually

We already have our portfolio site, so we don't need a template.

I'll walk you through the two other options.

Netlify project start screen

Option 1 – How to Deploy Manually

If you're not comfortable with Git and GitHub, Netlify lets you drag and drop to upload a project into their interface.

On your command line, run npm run build or eleventy to build your site.

Now upload the site's public directory to Netlify's file upload interface. In a few moments Netlify will have the site live on a URL that you can visit.

If you want to make future changes to your deployed site, click on "Deploys" and scroll down to find the file uploader.

You can rebuild your site locally and upload the new version of your public folder to Netlify whenever you want.

Option 2 – How to Import a Project from Git

If you are familiar with Git and GitHub, commit your code and push it to GitHub. Then click on the "Import from Git" button.

Netlify will ask you to connect a Git provider. Choose GitHub and authorize Netlify to access your GitHub repositories.

Choose the repository that holds your portfolio site. You can search for "eleventy", or whatever name you gave it.

Netlify import project interface

Netlify will detect that this is an Eleventy project and will ask you to confirm the basic build settings.

Make sure the build command is either npm run build or eleventy.

Under "Publish directory", enter public instead of _site.

Now click the "Deploy site" button.

Netlify build settings page

In a few moments Netlify will tell you that your site is live and give you a URL for it.

Once your site is live, if go to the Contact page, fill out the form, and submit it. You'll be redirected to the custom success page that you made.

If you click on "Forms" in the Netlify interface, you'll be brought to the Netlify Forms dashboard.

The form will have whatever name you used in the name attribute on your contact form, in this case "contact".

Netlify forms dashboard

Congratulations, you've built and deployed an Eleventy portfolio site. 🥳🎉🎉🎉

Feel free to use this project as a template for your own portfolio and customize it any way you'd like. So many portfolios look similar, so it's always good when a portfolio shows off your personality and passions.

Where to Take it from Here

This tutorial has hopefully taught you the basics of Eleventy, and how to combine data and templates to make fast sites without a whole lot of tooling or configuration.

If you'd like to take your Eleventy journey further, the Eleventy docs are very good. There's lots more to learn about manipulating data, not to mention adding personalized content and dynamic interactivity with Serverless and Edge Functions.

11ty.rocks by Stephanie Eckles is also a great resource, with practical tips and helpful tutorials on all sorts of Eleventy features.

I hope this guide has been helpful and made you excited to learn more about Eleventy, static site generators, and the Jamstack.

From WordPress to Hugo – How I Migrated a 250+ Page Site and the Scripts I Used

Lane Wagner — Tue, 30 Aug 2022 23:25:47 +0000

I recently decided to switch Boot.dev's blog from WordPress to a static site generator.

I decided on Hugo, partly because I’m a huge fan of the Go programming language, but also because it just seemed like the best option from a dev-experience perspective.

Here’s why I decided to move away from WordPress:

I wanted to write and store all my posts in Markdown.
I wanted to version control all my posts in Git/Github.
I wanted to be able to use ctrl+shift+f to find and edit the content on my blog.
I wanted a less buggy way to do “global blocks”
I didn’t want to spend hours fine-tuning performance. My posts are just text and images, so page speed scores should be 100 by default!
I wanted to use straight CSS for styling, making it easier for my blog and app to have identical styling.
I wanted to host the site for free

With all those goals in mind, Hugo was a perfect choice. I’ve been super happy since making the switch, but there were some hiccups along the way.

WordPress takes care of some of the nuances of SEO-tuning for you, and if you forget to redo them yourself, you’ll end up sacrificing rankings.

How to Export WordPress Posts as Markdown

Manually copying and pasting all of your posts out of the WordPress GUI into Markdown files could take a very long time. Especially if you have hundreds of posts like I do.

In order to speed up the process, I used this Markdown plugin to export all of my posts as markdown at once. It’s called “Gatsby Markdown Exporter”, but it works for Hugo just as well.

I’m not going to go over the basics of getting up and running with Hugo, as I’m going to assume you are already familiar with it. But if you’re not, you can read the quick start guide here.

How to Use Hugo’s Built-in SEO Templates

WordPress and its various SEO plugins take care of a lot of SEO-related hocus-pocus for you. So when you move to a static site generator you often have to do some of that stuff yourself.

As it turns out, Hugo has some turn-key solutions for most of this, so using the right internal templates can get you all the open-graph, schema, and Twitter meta tags out of the box.

For me, that meant simply adding these 3 lines to my layouts/partials/header.html file within the tag:

{{ template "_internal/opengraph.html" . }}
{{ template "_internal/twitter_cards.html" . }}
{{ template "_internal/schema.html" . }}

Now we'll get into the scripts I wrote to help me with this process.

Script 1 — Checking for Broken Links

You can solve a lot of your WordPress woes by installing plugins for various tasks. Well, assuming those plugins don’t break your entire WP installation.

With Hugo, I just write little text-manipulation or HTTP scripts to do my bidding.

This first script is just a simple iterator that crawls the site and reports any broken links. You can see the full source code here. It's small edit of the script the Go team uses to check for broken links on the Go programming language's website.

Script 2 — Minifying Images

When working with WordPress, you would typically upload a blog post image, and some SEO plugin would optimize that image’s size for you.

In Hugo, no such optimizations are made for you. It simply serves the exact image you add to your “static” folder.

I wrote a little script to optimize my images. It does the following:

Takes an input image of nearly any type (.png, .jpeg, .gif, etc).
Converts it to the .webp format (a performant format).
Shrinks the image to a max image size I've configured if it’s too large.

This script is written in Node.js and the source code can be found here.

Script 3 — Managing Global Shortcodes

WordPress had a feature called “global blocks”. They're super useful for things like newsletter signup boxes that show up in the middle of your articles, but that you want to be able to update in a single place.

In Hugo, you can use shortcodes to achieve a similar purpose.

Unfortunately, it’s the inserting and removing of the shortcodes themselves that actually becomes tedious at scale.

For example, let’s say I added my newsletter signup shortcode after the 5th paragraph in all my articles, but now I want it to come after the 7th paragraph. I have to go manually copy/paste the short code!

Well, not anymore. Again, this is the great thing about storing all your blog posts in a text format — we can script some simple solutions. I wrote two scripts, and their source code can be found here:

These two scripts allow me move my global blocks with ease. For example, to remove all instances of myshortcode from the blog:

rmshorts myshortcode

Then to add myshortcode as its own paragraph after the 2nd section of every blog post across the site:

addshorts myshortcode 2

This has been a huge time saver.

Script 4 — Converting .docx to Markdown

Last but not least, I work with some non-technical writers. My writers aren’t used to writing Markdown. Google docs is their tool of choice.

I have no problem with that, as I want them to be effective. My solution was to write a little bash script that uses pandoc under the hood to convert the Google Docs to Markdown files.

Wrapping Up

I hope some of these scripts are valuable to you, and I really can’t recommend enough making the switch to a static site generator. If you’re willing to put in a few hours to get a great working environment up and running for your blog it will save you a lot of time and money in the long run.

Remember, always automate the boring stuff!

How to Create a Theme-able Static Website

Spruce Emmanuel — Mon, 08 Feb 2021 21:00:38 +0000

A while ago I wanted to create a dark theme for my personal site. So I did some clicking around to find out the most suitable and clean way to do this.

I read Max Bock's article on creating a custom theme, where he explained the process quite clearly. He also really went super pro (with TEN different color schemes).

But for my case I wanted more. I wanted users to be able to change the color scheme to the different options provided.

I also wanted them to be able to change the font size. This is because I had a fixed header on my site which was kind of great, but on small mobile devices it took up quiet a lot of space – not great for UX design, right? So I also gave users the ability to turn off that fixed header.

Spruce.com.ng Theme-able static site

You can find a live preview of this on my personal site spruce.com.ng. You can also copy the source code here to save you some read time.

What I Wanted to Do

Ask users their preferred color scheme, font size, and header type (fixed or static)
Collect user choices
Save them in localStorage
Get them from localStorage and show them to the user immediately on page reload, if they switch tabs and come back, and if they close their browser and come back after a week or month, until they clear their browser storage

How I Created the Theme

In 11ty (the static site generator I'm using) you can create a JSON file in the _data folder. You can access the data globally in your template (Jekyll does this too). It's likely that your preferred static site generator (SSG) can do the same.

_data/themes.json file

[
    {
        "id": "default",
        "colors": {
            "text": "#222126",
            "text-dark": "#777;",
            "border": "rgba(0,0,0,.1)",
            "primary": "#665df5",
            "secondary": "#6ad1e0",
            "primary-dark": "#382cf1",
            "bg": "#ffffff",
            "bg-alt": "#f8f8f8",
            "overlay": "rgba(255, 255, 255, .4)"
        }
                }, 
    ... other color schemes
]

How to Generate the CSS

To use the data file, create a file called theme.css.liquid and give it a permalink where you want the CSS file to output to.

css/theme.css.liquid file
---
permalink: /css/theme.css
---
// when no theme is selected
// use default theme
:root {
    --text: {{ themes[0].colors.text }};
    --text-dark: {{ themes[0].colors.text-dark }};
    --border: {{ themes[0].colors.border }};
    --primary: {{ themes[0].colors.primary }};
    --secondary: {{ themes[0].colors.secondary }};
    --primary-dark: {{ themes[0].colors.primary-dark }};
    --bg: {{ themes[0].colors.bg }};
    --bg-alt: {{ themes[0].colors.bg-alt }};
}  
// if user preferred color scheme is dark
// use the dark theme

@media(prefers-color-scheme: dark) {
    :root {
    --text: {{ themes[1].colors.text }};
    --text-dark: {{ themes[1].colors.text-dark }};
    --border: {{ themes[1].colors.border }};
    --primary: {{ themes[1].colors.primary }};
    --secondary: {{ themes[1].colors.secondary }};
    --primary-dark: {{ themes[1].colors.primary-dark }};
    --bg: {{ themes[1].colors.bg }};
    --bg-alt: {{ themes[1].colors.bg-alt }};
    }
}
// generate the theme css from the data file
// here we use a for loop
// to iterate over all the themes in our _data/themes.json
// and output them as plain css


{% for theme in themes %}
 [data-theme="{{ theme.id }}"] {
    --text: {{ theme.colors.text }};
    --text-dark: {{ theme.colors.text-dark }};
    --border: {{ theme.colors.border }};
    --primary: {{ theme.colors.primary }};
    --secondary: {{ theme.colors.secondary }};
    --primary-dark: {{ theme.colors.primary-dark }};
    --bg: {{ theme.colors.bg }};
    --bg-alt: {{ theme.colors.bg-alt }};
 }
{% endfor %}

Notice that I'm using themes[0].colors.text because my default theme is the first one on the list. It has an index of 0, so also my dark theme has an index of 1.

In Jekyll you can output liquid in CSS by just adding empty front matter at the top of the file.

css/theme.css file
---
---

// your liquid in css goes here

I'm sure your favourite static site generator provides a similar way to output liquid in a CSS file. You can also handcode all this if you are just writing plain HTML and CSS without a SSG.

How to Use the CSS in Your Site

If you are reading this, then I assume that you already know how to work with CSS custom properties. So I won't go in depth into that here.

// css custom properties are declared using the keyword **var**
// color: var(--text);
body {
    background: var(--bg);
    color: var(--text);
}
h1,h2 {
    color: var(--text-dark)
}
// i also had default font-size and margin-top properties set
// i added this to the :root in css
:root {
    --font-size: 18px;
    --position: fixed;
    --top-margin: 96px;
}

You just have to change every bit of color on your site to the custom properties you have generated.

How to Generate the HTML

Now let's provide a UI to allow users to change the font size, header type, and color scheme of our site. Mine is a bit simple, but you can take yours further. I'm just explaining the concept here.

theme.html file
// create the font buttons
// I gave each button a value
// I want to get the value and save it in local storage 

<section class="theme-section">
    <div class="theme-btn-wrapper">
        <button class="btn btn--small btn--border js-font-btn" value="16">16pxbutton>
        <button class="btn btn--small btn--border js-font-btn" value="18">18pxbutton>
        <button class="btn btn--small btn--border js-font-btn" value="20">20pxbutton>
        <button class="btn btn--small btn--border js-font-btn" value="22">22pxbutton>
    div>
section>

// Create the toggle button
// To turn On & Off
// The fixed header
// The **sr-only** is used to hide the text visually 
// while keeping accessibilty in mind
// note the **role="switch"** nd aria-checked
// they are what turns the button to a On and Off switch
<div class="check-wrapper">
    <span id="btn-label" class="sr-only">Fixed or static headerspan>
   <button role="switch" type="button" aria-checked="true" aria-labelledby="btn-label" class="js-theme-toggle btn btn--border btn--rounded btn--toggle">
       <span>Onspan>
       <span>Offspan>
   button>
div>

That's pretty much the HTML for my use case. Again you can do more if you want, and there is some CSS styling involved (which would be left out in our case).

The Fun Part: How to Create the JavaScript

/assets/js/theme.js file
class CustomTheme {
    constructor() {
        // part A: check if localStorage works
        this.islocalStorage = function() {
            try {
                localStorage.setItem("test", "testing");
                localStorage.removeItem("test");
                return true;
            } catch (error) {
                return false
            }

        };
        // part B: Get the value from the buttons
        this.schemeBtns = document.querySelectorAll('.js-theme-color');
        this.schemeBtns.forEach((btn) => {
            const btnVal = btn.value;
            btn.addEventListener('click', () => this.themeScheme(btnVal))
        });

        this.fontBtns = document.querySelectorAll('.js-font-btn');
        this.fontBtns.forEach((btn) => {
            const btnVal = btn.value;
            const btnTag = btn;
            btn.addEventListener('click', () => this.themeFont(btnVal, btnTag))
        });

        // part C: get the html button element
        this.switchBtn = document.querySelector('.js-theme-toggle');
        const clicked = this.switchBtn;
        this.switchBtn.addEventListener('click', () => this.themePosition(clicked))
    }

    // part D: Save the data in localStorage
    themeScheme(btnVal) {
        document.documentElement.setAttribute('data-theme', btnVal);
        if (this.islocalStorage) {
            localStorage.setItem('theme-name', btnVal);
        }
    };

    themeFont(btnVal,btnTag) {
        document.documentElement.style.setProperty('--font-size', `${btnVal}px`);
        if (this.islocalStorage) {
            localStorage.setItem('font-size', btnVal);
        }
        ;
        if (btnVal == localStorage.getItem('font-size')) {
            removeActive();
            btnTag.classList.add('active');
    }
};

    themePosition(clicked) {
    if (clicked.getAttribute('aria-checked') == 'true') {
        clicked.setAttribute('aria-checked', 'false');
        document.documentElement.style.setProperty('--position', 'static');
        document.documentElement.style.setProperty('--top-margin', '0px');
        if (this.islocalStorage) {
            localStorage.setItem('position', 'static');
        }

    } else {
        clicked.setAttribute('aria-checked', 'true');
        document.documentElement.style.setProperty('--position', 'fixed');
        document.documentElement.style.setProperty('--top-margin', '96px');
        if (this.islocalStorage) {
            localStorage.setItem('position', 'fixed');
        }
    }

    }
}

function removeActive() {
    const btns = document.querySelectorAll('.js-font-btn');
    btns.forEach((btn) => {
        btn.classList.remove('active');
    })
}

// part E: Only use our class if css custom properties are supported
if (window.CSS && CSS.supports('color', 'var(--i-support')) {
    new CustomTheme()
};

// part E: Add an active class to selected font size button

window.addEventListener('load', () => {
    const fontBtns = document.querySelectorAll('.js-font-btn');
    fontBtns.forEach((btn) => {
        const btnVal = btn.value;
        const btnTag = btn;
        if (btnVal == localStorage.getItem('font-size')) {
            btnTag.classList.add('active');
    }
    });   
})

I know that's a big chunk of JavaScript code, but it basically only does a few things:

it collects and checks if localStorage is supported
then it saves the data in localStorage

Also notice that I used Javascript Classes, but you could use functions as well.

Checking for local storage

A lot of browsers support localStorage these days, but why do we still need to check?

Some users may be browsing your site in incognito mode (private browsing mode). And sometimes localStorage is turned off by default so it doesn't save anything on the users device.

So instead of saving it directly and sometimes getting an error on browsers that don't support it, we can check if the browser does support it. If it does, great – and if it doesn't then we're also cool.

Now if you notice, everything seems to work just fine. But if you change the theme or font size and you reload your browser, everything is going to revert to default. This is because we haven't used the data we stored in localStorage

So go ahead and add this piece of code to the top of your head file before any CSS files. We're doing this to eliminate the flash you get when you reload your browser.

Wrapping up

And that's it! You now have a simple and customizable static site.

The main purpose of this guide was to show you the endless possibilities of creating a user-customizable website. So go ahead and play around with it – there are a lot of things you can do, like:

Show users specific content based on their choices
Display notification messages based on user's visits
Display ads in the least annoying way by showing users ads based on user choices

You can do these things and a lot more with our SSG's. Just imagine the endless possibilities.

Not much of a tutorial person? You can copy the complete source code here.

How to Build a Blog Using a Static Site Generator and a CDN

freeCodeCamp — Fri, 29 Jan 2021 16:46:23 +0000

By Aaron Katz

I wanted to set up a fun project for myself to learn some new technologies. And this time I decided I wanted to learn a bit about Static Site Generators (SSGs).

My goal was to build a blog using an SSG and have it deploy any time the code repository changed. You can see the result at https://caliburnsecurity.com.

Blog Requirements

Below are the requirements I put together when determining what I wanted my blog to support.

Support Markdown for content generation
Syntax highlighting
Code line numbering
"Serverless"
Ready made themes/plugins - I am so NOT a frontend developer
SEO capabilities
Browse by keyword/category
Search support (because this is statically generated, searching is through Google's index - there are other articles that discuss how to add a dynamic JavaScript powered search)
RSS support
Version controlled
Static - no dynamic content (with a neat side effect of shrinking the site's attack surface and improving security)

So what actually is a Static Site Generator?

In short, an SSG is a framework designed to manage your website and transform it into a site serving only static pages.

Why use a SSG to build the blog?

One thing that took me some time to comprehend was why I would use a static site, if I already had a CMS. There were so many articles online about using an SSG with a headless CMS...but why?

Best I can tell, the benefits are simply that you have more flexibility using familiar frameworks such as React or Vue, while using a CMS to handle all content.

However, as I am by no means a frontend developer, I was close to scrapping this project. I thought "Oh well, I should just use Ghost - it's only $5/month if hosted on a platform like DigitalOcean, and is an all-in-one platform to serve content as well as manage the content".

However, I really wanted to try to learn something new, and see if I could just deploy a blog for free using only Markdown.

As always ends up happening, what I was hoping would take a few hours took quite a bit more time as I went down the rabbit hole of research into various technologies.

I played around with several different technologies, such as (not all of these are SSGs, more on that later):

Pelican (Python)
Hugo (Go)
Hexo
Gridsome (Vue - JS)
VuePress (Vue - JS)
Ghost
Gatsby (React - JS)
Jekyll (Ruby)

Why I Chose Hugo

I won't go in too much detail on all of the technologies I looked at. But in general, I found Hugo to be super quick to set up and build, and just the SIMPLEST of all the options.

While I know this is similar to Jekyll, I really just didn't want to deal with configuring a Ruby environment, and the speed of Hugo left everything else in the dust.

How to Start Building the Blog

For this exercise, let's build a static blog hosted by Netlify (free!).

Note: I'll be using PowerShell on my Windows box for this tutorial, so please recall that if copy/pasting.

Make sure you have these dependencies:

Git
Visual Studio Code (or your preferred editor)
Hugo binary

Here's a high level overview of our workflow:

Download/Install Hugo
Create a Hugo project
Add and configure a theme
Add to Git
Deploy to Netlify
(Optional) Configure the free Netlify CMS

Download or install Hugo

To install Hugo, I went over to their GitHub Releases page and downloaded their standalone Windows x64 binary. I placed it in my Projects directory, where we will be creating our site (you can always install it properly/add the binary to your PATH, but I wanted quick).

How to Create the Hugo Site

To create a new site, simply run the below commands:

.\hugo.exe new site hugo-blog
mv .\hugo.exe .\hugo-blog
cd .\hugo-blog
.\hugo.exe server -D --gc

We now have our project created, and have just started the Hugo server. We used the -D flag to tell Hugo to show draft content, and I typically add in --gc to ensure that cleanup is run each time by clearing the cache.

You can access your site at http://localhost:1313.

Understanding the directory structure

You should now see the following directory structure:

|__archetypes
|__assets *this will not show up by default
|__config *this will not show up by default
|__content
|__data
|__layouts
|__static
|__themes
|__config.toml

archetypes: Content template files with pre-configured front matter. We won't really be touching this.
assets: Store any files processed by Hugo Pipes. This is out of scope for this tutorial.
config: Optional directory to store configuration files. We won't be doing anything too crazy, so we will just use the default config.toml file.
content: This is where your content lives - your posts and pages. The top level folders within this directory are treated as a section.
data: Contains configuration files used by Hugo. I never had a need to touch this directory.
layouts: Stores partial or full page HTML templates for the site. Anything in here can overwrite a corresponding entry from your theme, allowing you to customize the theme without modifying the theme's actual files.
static: Store any static content, such as images, CSS, or scripts. Anything in this folder is copied as-is, without any modification or interpretation by Hugo. This is where you will store your media, such as images, for reference in your blog posts.
themes: The directory where you will install any Hugo themes.
config.toml: The default site configuration. You can use a separate directory if you want to separate different environments.

How to Add Your First Theme

For this blog, we will use the tale theme for Hugo. Run the following commands from the root of the project:

git submodule add https://github.com/EmielH/tale-hugo.git .\themes\tale

We will NOT be editing any files from the theme, but will make all modifications in the layouts folder discussed above. This will let us always update the submodule to update our theme without worry that we will overwrite any changes we have made.

To initialize the theme, edit the config.toml in your root directory and add the following lines (while also editing the defaults):

# Theme Settings
theme = "tale"
[params]
  Author = "Aaron Katz" # Add the name of the author (this theme only supports one author)
[author]
  name = "Caliburn Security" # Used by the foot copyright

There we go, the theme is now active! (Note that in many cases, themes will require you to copy and paste the theme's theme.toml file into your config.toml)

Go ahead and check out your page – every time you save a file Hugo rebuils the site live.

How to modify theme files

One issue with the current theme is that non-post content will be displayed in the homepage list.

To change this, let's copy the .\themes\tale\layouts\index.html page to .\layouts\index.html.

Once there, replace: {{range (.Paginate .Site.RegularPages).Pages}} with {{ range where .Paginator.Pages "Section" "post" }}. This will ensure only the "post" section will be displayed in the list.

I also wanted to add a brief footer, so go ahead and create a new file at .\layouts\footer.html and add the following code:

<footer>
    <span>
    © <time datetime="{{ now }}">{{ now.Format "2006" }}time> {{ .Site.Author.name }}
    span>
footer>

How to Add Google Analytics

I also wanted to add some Google Analytics to my blog, and I noticed the theme didn't incorporate this functionality.

Luckily, Hugo makes adding analytics extremely simple. Open up the config.toml file and add the following line:

googleAnalytics = "" # The UA-XXX number from Google Analytics

Once the configuration is saved, copy the .\themes\tale\layouts\partial\head.html file to .\layouts\partial\head.html and add the following code right below the head tag:

{{ template "_internal/google_analytics_async.html" . }}

There we go, now we have Google Analytics working. Cool!

How to Write Content

Let's add a nice About page so people know everything there is about me. :)

.\hugo.exe new about.md

To ensure that this page is added to the main menu, add the following line to the page's front matter: menu: main.

Note: To build Hugo, which will generate the content under the .\public folder, simply run .\hugo.exe

What is front matter?

This was a new term for me. Essentially, front matter is just structured metadata for your content.

By default, your template will add the following metadata fields to each page or post you create:

title
date
draft

Other potentially useful front matter elements are:

description - This allows you to enter a description for the content.
expiryDate - Set a datetime for when the content should no longer be published.
keywords - The meta keywords for the content.
lastmod - The datetime for when the content was last modified (if you are using the enableGitInfo configuration command, this will be automatically set as the last time the file was mofieid in Git)
markup - When set to "rst", you can use reStructuredText instead of Markdown (this feature is experimental)
publishDate - Set a date in the future for the content to be displayed.
slug - The tail of the output URL. Defaults to the filename if not specified.
summary - The text used when providing a summary of the article. I find this useful if I don't want the first paragraph to appear in the summary, which is the typical default.
- Use the plural form of the taxonomy index, such as tags or categories.

How to create an archetype for blog posts

Let's go ahead and change the default front matter we see for blog posts. In the archetypes folder, create a new file called posts.md and add the following:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true

slug: {{ .File.BaseFileName }} # Will take the filename as the slug. Feel free to change this to any format you like.  I like including this, so that I remind myself I have the option to change if I want.

summary: "" # Remove this if you want Hugo to just use the first 70 (configurable) characters of the post as the summary.
description: ""

# Lists
keywords:
tags:
categories:
---

Now let's do one final build with .\hugo.exe and get ready to configure our Git repository.

How to Configure Git

Time to configure the project for Git:

git init
git remote add origin 
git push -u origin master

Great, we now have our code stored within our repository, and we are ready for deployment!

How to Deploy Your Blog

Now that we have our site stored in Git, it's time to deploy! Almost done - I'll now show how to deploy to Netlify in under 10 minutes.

First, we need to create the Netlify application (feel free to create an account using any method available):

Next, we need to create the site and tell it where our Git repository is for our Hugo content:

Tell Netlify where your site is located

Select the repository

These can be left at the default settings

Next up, we will set up a custom domain for our site:

Select the custom domain option

Enter your custom domain

You should now see your domain with a message saying to Check DNS configuration. Click on that, and enter the provided DNS record information into whichever service provider manages your DNS records:

Example configuration within my Cloudflare account

Once complete, wait a few minutes for the DNS settings to propagate, and then select Verify DNS configuration:

Behold, your site is now live!

Example of my new blog hosted on Netlify!

Last, we should set up SSL for our site as a best practice. Netlify offers the option to use Let's Encrypt to automatically provision a certificate for your application. To do so, simply select Provision certificate:

Note: It can take quite some time for the certificate to be generated, so just be patient.

Netlify deployment settings

We have one final step before we are truly ready to use Netlify. Unfortunately, the version of Hugo used by Netlify is somewhat outdated by default. However, we can fix this by creating our own configuration for Netlify to follow when deploying our site.

First, create a file called netlify.toml in the root of your repository, and then add the following configuration:

[build]
publish = "public"
command = "hugo --gc --minify"

[context.production.environment]
HUGO_VERSION = "0.74.3"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

[context.split1]
command = "hugo --gc --minify --enableGitInfo"

[context.split1.environment]
HUGO_VERSION = "0.74.3"
HUGO_ENV = "production"

[context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
HUGO_VERSION = "0.74.3"

[context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

[context.branch-deploy.environment]
HUGO_VERSION = "0.74.3"

[context.next.environment]
HUGO_ENABLEGITINFO = "true"

All that's left to do is select Deploy site within the Netlify console, and your site is now live on a custom domain with SSL!

Wrapup

Whew! That was a lengthy blog post, but hopefully this shows how quick it is to get up and running with a "serverless" blog. Let's see what I learned :)

What I loved

Super simple to build, just run hugo serve
Live reload - make a change, save, and the page will reload
Just simple in general - I didn't need to deal with grunt, gulp, webpack, or others
Customizable output formats let you generate your static site, as well as a Google AMP site, JSON files, and so on.
FAST. Did I mention fast?
Can be deployed just about anywhere - whether using Netlify (my current choice), Amazon S3 & Cloudfront, Heroku, GitHub Pages, and more.
Shortcodes are available if Markdown isn't enough
Continuous deployment - everything is version controlled, and deployed when I publish to the master branch
Allow commenting and sharing of posts

Challenges

Hugo is sometimes too simple. No plugins or extensions at all, etc.
Using Go is less intuitive and the shortcode feels messier than something like Vue
Not too many themes available, but I expect the library to keep growing, as there is a very active user base

So do I need a CMS?

After all of this, I still had this question in the back of my mind. And the answer is, "it depends".

If I were to incorporate a lot of media, such as images or videos that I need to upload, it would certainly get tedious adding and organizing them all to the images folder in static.

At that point, I would look into a headless CMS such as Ghost, Netlify, or Sanity to manage the content, as long as I could still write my posts using Markdown.

References

https://medium.com/backticks-tildes/hugo101-getting-started-with-hugo-and-deploying-to-netlify-9a813fe23b94
https://blog.risingstack.com/static-site-generator-hugo-netlify/
http://cloudywithachanceofdevops.com/posts/2018/05/17/setting-up-google-analytics-on-hugo/
https://www.sitepoint.com/premium/books/a-beginner-s-guide-to-creating-a-static-website-with-hugo/read/1

What is Static Site Generation? How Next.js Uses SSG for Dynamic Web Apps

Colby Fayock — Wed, 18 Nov 2020 17:49:33 +0000

Static websites are as old as the web itself. But the rise of JavaScript has opened the door to make those static sites more dynamic.

While that can include building an HTML file by hand, how can we leverage static generation to build apps with modern tools?

What is Static Generation?
What happens during Static Generation?
How does Next.js use Static Generation?
Statically generating an app with Next.js

What is Static Generation?

Static Generation describes the process of compiling and rendering a website or app at build time. The output is a bunch of static files, including the HTML file itself and assets like JavaScript and CSS.

If you haven’t heard of Static Generation but that concept sounds familiar, you might have heard of it by its longer name Static Site Generation or its acronym SSG.

What happens during Static Generation?

JavaScript-based web apps as we traditionally know them work by running libraries like React or scripts at run time in the browser.

When the browser receives the page, it’s usually simple HTML without a lot of content. This then loads the scripts to pull the content into the page, a process also known as hydration.

With Static Generation, tools like Next.js try to render that page mostly like it would in the browser but at compile time. This gives us the ability to serve the entire content on first load. The scripts still hydrate the page during this process, but ideally with fewer changes or no changes at all.

How does Next.js use Static Generation?

Out of the box, Next.js will attempt to statically generate any pages that it can. It does this by detecting how an app is fetching its data.

Next.js provides a few different APIs to fetch data including getStaticProps and getServerSideProps, which, depending on how they’re used, determines how Next.js will build your app.

If you only use getStaticProps to fetch data, Next.js will fetch that data at build time, leaving you with a completely static page.

If you use getServerSideProps, Next.js will know that the app requires a server to render those pages.

Alongside a deployment solution like Vercel that will automatically handle configuring a server, Next.js will load any of the data when someone requests the page from the server.

While it doesn’t do it by default, Next.js also provides the ability to export the app into static files into a separate directory after the app has been built.

First, you would run the next build command to build the app, then you would run next export which, by default, makes the app available as static files in the out directory.

How to statically generate an app with Next.js

To get an idea of how this works, we can quickly create a new Next.js app.

The only requirements for this is that you have Node installed with npm and the ability to use a terminal to run commands.

How to create a Next.js app

Getting started is as simple as running a single line in the terminal.

Open up the directory you’d like to create your project in and run:

npx create-next-app my-static-nextjs-app

After the installation is complete, you can navigate to your new project directory:

cd my-static-nextjs-app

Once there, start your development server:

npm run dev

And once the server is ready, you can open up http://localhost:3000 in your browser where you can now see your new Next.js app!

New Next.js app

How to build a Next.js app

Now that we have our application available, let’s try to build it.

In the same directory, run the command:

npm run build

If you look at the output inside of the terminal, we see a few important things happen.

First, Next.js lets us know that it’s running through its build process, including optimizing the app for performance, compiling the app, and collecting data.

Building with Next.js

Next, we see that Next.js shows us a breakdown of how it’s built each page.

The default Next.js starting template includes a few static pages and an example API route.

Using the legend at the bottom, we can see that all of the pages and assets were statically generated with one route tagged as requiring a server, which would be our API route.

Next.js generating pages

Note: For the purposes of this walkthrough, we can ignore the API route, but Next.js along with Vercel provides the ability to build lambda functions as part of the Next.js API.

How to build a static Next.js app

With our Next.js build output, we know that we just built some static pages, but we might have trouble finding them. If we look at the folders and files in our project, it’s not immediately clear where those files are.

When Next.js builds an app, by default, it only outputs that app inside the .next directory. This includes configuration files that tools like Vercel can use and understand to deploy the app.

Technically, that directory includes our entire app, but this isn’t something we can easily deploy to static hosting.

Next.js also provides the ability to export an app. This will take the app that we built and produce a set of static files which we can then use to deploy our app.

Inside of the package.json file, update the build script to include next export:

"build": "next build && next export",

Once updated, run the build command again in the project directory:

npm run build

And now we can see that not only did we build the app like we did in our last step, Next.js lets us know that we’re also exporting the app that we built into static files.

Exporting static Next.js app

If we look inside of our project folder, we should now see a new directory called out.

If we look inside of that folder, we can now see our entire app statically compiled including the index.html file as well as all of the CSS and JS needed to use the app!

Where can we go from here?

We learned that we can use Next.js and the concept of Static Generation to statically compile an app.

Tools like Next.js can do this by compiling our code, similar to what we might see in a browser, so that by the time our app hits the browser, it’s all ready to go.

With a simple command, we can also build and compile our app, as well as export it into static files. We can deploy those static files to any static storage service like Vercel or AWS S3. This provides us with an easy way to craft dynamic web apps that are fast and cheap.

Learn more about how Next.js leverages its different APIs to provide both static and dynamic experiences by visiting the Next.js docs.

Hugo vs Jekyll: an Epic Battle of Static Site Generator Themes

Victoria Drake — Mon, 27 Apr 2020 13:42:00 +0000

In this article, we'll compare the nuances of creating themes for the top two static site generators.

I recently took on the task of creating a documentation site theme for two projects. Both projects needed the same basic features, but one uses Jekyll while the other uses Hugo.

In typical developer rationality, there was clearly only one option. I decided to create the same theme in both frameworks, and to give you, dear reader, a side-by-side comparison.

This post isn’t a comprehensive theme-building guide, but is rather intended to familiarize you with the process of building a theme in either generator. Here's what we'll cover:

How theme files are organized
Where to put content
How templating works
Creating a top-level menu with the pages object
Creating a menu with nested links from a data list
Putting the template together
Creating styles
How to configure and deploy to GitHub Pages

Here’s a crappy wireframe of the theme I’m going to create.

If you’re planning to build-along, it may be helpful to serve the theme locally as you build it – and both generators offer this functionality. For Jekyll, run jekyll serve, and for Hugo, hugo serve.

There are two main elements: the main content area, and the all-important sidebar menu. To create them, you’ll need template files that tell the site generator how to generate the HTML page. To organize theme template files in a sensible way, you first need to know what directory structure the site generator expects.

How theme files are organized

Jekyll supports gem-based themes, which users can install like any other Ruby gems. This method hides theme files in the gem, so for the purposes of this comparison, we aren’t using gem-based themes.

When you run jekyll new-theme , Jekyll will scaffold a new theme for you. Here’s what those files look like:

.
├── assets
├── Gemfile
├── _includes
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
└── .gemspec

The directory names are appropriately descriptive. The _includes directory is for small bits of code that you reuse in different places, in much the same way you’d put butter on everything. (Just me?)

The _layouts directory contains templates for different types of pages on your site. The _sass folder is for Sass files used to build your site’s stylesheet.

You can scaffold a new Hugo theme by running hugo new theme . It has these files:

.
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── header.html
│       └── head.html
├── LICENSE
├── static
│   ├── css
│   └── js
└── theme.toml

You can see some similarities. Hugo’s page template files are tucked into layouts/. Note that the _default page type has files for a list.html and a single.html.

Unlike Jekyll, Hugo uses these specific file names to distinguish between list pages (like a page with links to all your blog posts on it) and single pages (like one of your blog posts). The layouts/partials/ directory contains the buttery reusable bits, and stylesheet files have a spot picked out in static/css/.

These directory structures aren’t set in stone, as both site generators allow some measure of customization. For example, Jekyll lets you define collections, and Hugo makes use of page bundles. These features let you organize your content multiple ways, but for now, let's look at where to put some simple pages.

Where to put content

To create a site menu that looks like this:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

You’ll need two sections (“Introduction” and “Advanced Usage”) containing their respective subsections.

Jekyll isn’t strict with its content location. It expects pages in the root of your site, and will build whatever’s there. Here’s how you might organize these pages in your Jekyll site root:

.
├── 404.html
├── assets
├── Gemfile
├── _includes
├── index.markdown
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── index.md
│   └── quickstart.md
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
├── .gemspec
└── usage
    ├── customizing.md
    ├── index.md
    ├── settings.md
    └── support.md

You can change the location of the site source in your Jekyll configuration.

In Hugo, all rendered content is expected in the content/ folder. This prevents Hugo from trying to render pages you don’t want, such as 404.html, as site content. Here’s how you might organize your content/ directory in Hugo:

.
├── _index.md
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── _index.md
│   └── quickstart.md
└── usage
    ├── customizing.md
    ├── _index.md
    ├── settings.md
    └── support.md

To Hugo, _index.md and index.md mean different things. It can be helpful to know what kind of Page Bundle you want for each section: Leaf, which has no children, or Branch.

Now that you have some idea of where to put things, let’s look at how to build a page template.

How templating works

Jekyll page templates are built with the Liquid templating language. It uses braces to output variable content to a page, such as the page’s title: {{ page.title }}.

Hugo’s templates also use braces, but they’re built with Go Templates. The syntax is similar, but different: {{ .Title }}.

Both Liquid and Go Templates can handle logic. Liquid uses tags syntax to denote logic operations:

{% if user %}
  Hello {{ user.name }}!
{% endif %}

And Go Templates places its functions and arguments in its braces syntax:

{{ if .User }}
    Hello {{ .User }}!
{{ end }}

Templating languages allow you to build one skeleton HTML page, then tell the site generator to put variable content in areas you define. Let’s compare two possible default page templates for Jekyll and Hugo.

Jekyll’s scaffold default theme is bare, so we’ll look at their starter theme Minima. Here’s _layouts/default.html in Jekyll (Liquid):

html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

  {%- include head.html -%}

  <body>

    {%- include header.html -%}

    <main class="page-content" aria-label="Content">
      <div class="wrapper">
        {{ content }}
      div>
    main>

    {%- include footer.html -%}

  body>

html>

Here’s Hugo’s scaffold theme layouts/_default/baseof.html (Go Templates):

html>
<html>
    {{- partial "head.html" . -}}
    <body>
        {{- partial "header.html" . -}}
        <div id="content">
        {{- block "main" . }}{{- end }}
        div>
        {{- partial "footer.html" . -}}
    body>
html>

Different syntax, same idea. Both templates pull in reusable bits for head.html, header.html, and footer.html. These show up on a lot of pages, so it makes sense not to have to repeat yourself.

Both templates also have a spot for the main content, though the Jekyll template uses a variable ({{ content }}) while Hugo uses a block ({{- block "main" . }}{{- end }}). Blocks are just another way Hugo lets you define reusable bits.

Now that you know how templating works, you can build the sidebar menu for the theme.

Creating a top-level menu with the `pages` object

You can programmatically create a top-level menu from your pages. It will look like this:

Introduction
Advanced Usage

Let’s start with Jekyll. You can display links to site pages in your Liquid template by iterating through the site.pages object that Jekyll provides and building a list:

<ul>
    {% for page in site.pages %}
    <li><a href="{{ page.url | absolute_url }}">{{ page.title }}a>li>
    {% endfor %}
ul>

This returns all of the site’s pages, including all the ones that you might not want, like 404.html. You can filter for the pages you actually want with a couple more tags, such as conditionally including pages if they have a section: true parameter set:

<ul>
    {% for page in site.pages %}
    {%- if page.section -%}
    <li><a href="{{ page.url | absolute_url }}">{{ page.title }}a>li>
    {%- endif -%}
    {% endfor %}
ul>

You can achieve the same effect with slightly less code in Hugo. Loop through Hugo’s .Pages object using Go Template’s range action:

<ul>
{{ range .Pages }}
    <li>
        <a href="{{.Permalink}}">{{.Title}}a>
    li>
{{ end }}
ul>

This template uses the .Pages object to return all the top-level pages in content/ of your Hugo site. Since Hugo uses a specific folder for the site content you want rendered, there’s no additional filtering necessary to build a simple menu of site pages.

Both site generators can use a separately defined data list of links to render a menu in your template. This is more suitable for creating nested links, like this:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

Jekyll supports data files in a few formats, including YAML. Here’s the definition for the menu above in _data/menu.yml:

section:
  - page: Introduction
    url: /intro
    subsection:
      - page: Getting Started
        url: /intro/quickstart
      - page: Configuration
        url: /intro/config
      - page: Deploying
        url: /intro/deploy
  - page: Advanced Usage
    url: /usage
    subsection:
      - page: Customizing
        url: /usage/customizing
      - page: All Configuration Settings
        url: /usage/settings
      - page: Help and Support
        url: /usage/support

Here’s how to render the data in the sidebar template:

{% for a in site.data.menu.section %}
<a href="{{ a.url }}">{{ a.page }}a>
<ul>
    {% for b in a.subsection %}
    <li><a href="{{ b.url }}">{{ b.page }}a>li>
    {% endfor %}
ul>
{% endfor %}

This method allows you to build a custom menu, two nesting levels deep. The nesting levels are limited by the for loops in the template. For a recursive version that handles further levels of nesting, see Nested tree navigation with recursion.

Hugo does something similar with its menu templates. You can define menu links in your Hugo site config, and even add useful properties that Hugo understands, like weighting. Here’s a definition of the menu above in config.yaml:

sectionPagesMenu: main

menu:  
  main:
    - identifier: intro
      name: Introduction
      url: /intro/
      weight: 1
    - name: Getting Started
      parent: intro
      url: /intro/quickstart/
      weight: 1
    - name: Configuration
      parent: intro
      url: /intro/config/
      weight: 2
    - name: Deploying
      parent: intro
      url: /intro/deploy/
      weight: 3
    - identifier: usage
      name: Advanced Usage
      url: /usage/
    - name: Customizing
      parent: usage
      url: /usage/customizing/
      weight: 2
    - name: All Configuration Settings
      parent: usage
      url: /usage/settings/
      weight: 1
    - name: Help and Support
      parent: usage
      url: /usage/support/
      weight: 3

Hugo uses the identifier, which must match the section name, along with the parent variable to handle nesting. Here’s how to render the menu in the sidebar template:

<ul>
    {{ range .Site.Menus.main }}
    {{ if .HasChildren }}
    <li>
        <a href="{{ .URL }}">{{ .Name }}a>
    li>
    <ul class="sub-menu">
        {{ range .Children }}
        <li>
            <a href="{{ .URL }}">{{ .Name }}a>
        li>
        {{ end }}
    ul>
    {{ else }}
    <li>
        <a href="{{ .URL }}">{{ .Name }}a>
    li>
    {{ end }}
    {{ end }}
ul>

The range function iterates over the menu data, and Hugo’s .Children variable handles nested pages for you.

Putting the template together

With your menu in your reusable sidebar bit (_includes/sidebar.html for Jekyll and partials/sidebar.html for Hugo), you can add it to the default.html template.

In Jekyll:

html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

{%- include head.html -%}

<body>
    {%- include sidebar.html -%}

    {%- include header.html -%}

    <div id="content" class="page-content" aria-label="Content">
        {{ content }}
    div>

    {%- include footer.html -%}

body>

html>

In Hugo:

html>
<html>
{{- partial "head.html" . -}}

<body>
    {{- partial "sidebar.html" . -}}

    {{- partial "header.html" . -}}
    <div id="content" class="page-content" aria-label="Content">
        {{- block "main" . }}{{- end }}
    div>
    {{- partial "footer.html" . -}}
body>

html>

When the site is generated, each page will contain all the code from your sidebar.html.

Create a stylesheet

Both site generators accept Sass for creating CSS stylesheets. Jekyll has Sass processing built in, and Hugo uses Hugo Pipes. Both options have some quirks.

Sass and CSS in Jekyll

To process a Sass file in Jekyll, create your style definitions in the _sass directory. For example, in a file at _sass/style-definitions.scss:

$background-color: #eef !default;
$text-color: #111 !default;

body {
  background-color: $background-color;
  color: $text-color;
}

Jekyll won’t generate this file directly, as it only processes files with front matter. To create the end-result filepath for your site’s stylesheet, use a placeholder with empty front matter where you want the .css file to appear. For example, assets/css/style.scss. In this file, simply import your styles:

---
---

@import "style-definitions";

This rather hackish configuration has an upside: you can use Liquid template tags and variables in your placeholder file. This is a nice way to allow users to set variables from the site _config.yml, for example.

The resulting CSS stylesheet in your generated site has the path /assets/css/style.css. You can link to it in your site’s head.html using:

<link rel="stylesheet" href="{{ "/assets/css/style.css" | relative_url }}" media="screen">

Sass and Hugo Pipes in Hugo

Hugo uses Hugo Pipes to process Sass to CSS. You can achieve this by using Hugo’s asset processing function, resources.ToCSS, which expects a source in the assets/ directory. It takes the SCSS file as an argument.

With your style definitions in a Sass file at assets/sass/style.scss, here’s how to get, process, and link your Sass in your theme’s head.html:

{{ $style := resources.Get "/sass/style.scss" | resources.ToCSS }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" media="screen">

Hugo asset processing requires extended Hugo, which you may not have by default. You can get extended Hugo from the releases page.

Configure and deploy to GitHub Pages

Before your site generator can build your site, it needs a configuration file to set some necessary parameters. Configuration files live in the site root directory. Among other settings, you can declare the name of the theme to use when building the site.

Configure Jekyll

Here’s a minimal _config.yml for Jekyll:

title: Your awesome title
description: >- # this means to ignore newlines until "baseurl:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
theme: # for gem-based themes
remote_theme: # for themes hosted on GitHub, when used with GitHub Pages

With remote_theme, any Jekyll theme hosted on GitHub can be used with sites hosted on GitHub Pages.

Jekyll has a default configuration, so any parameters added to your configuration file will override the defaults. Here are additional configuration settings.

Configure Hugo

Here’s a minimal example of Hugo’s config.yml:

baseURL: https://example.com/ # The full domain your site will live at
languageCode: en-us
title: Hugo Docs Site
theme: # theme name

Hugo makes no assumptions, so if a necessary parameter is missing, you’ll see a warning when building or serving your site. Here are all configuration settings for Hugo.

Deploy to GitHub Pages

Both generators build your site with a command.

For Jekyll, use jekyll build. See further build options here.

For Hugo, use hugo. You can run hugo help or see further build options here.

You’ll have to choose the source for your GitHub Pages site. Once done, your site will update each time you push a new build. Of course, you can also automate your GitHub Pages build using GitHub Actions. Here’s one for building and deploying with Hugo, and one for building and deploying Jekyll.

Showtime!

All the substantial differences between these two generators are under the hood. All the same, let’s take a look at the finished themes, in two color variations.

Here’s Hugo:

Here's Jekyll:

Wait who won?

Both Hugo and Jekyll have their quirks and conveniences.

From this developer’s perspective, Jekyll is a workable choice for simple sites without complicated organizational needs. If you’re looking to render some one-page posts in an available theme and host with GitHub Pages, Jekyll will get you up and running fairly quickly.

Personally, I use Hugo. I like the organizational capabilities of its Page Bundles, and it’s backed by a dedicated and conscientious team that really seems to strive to facilitate convenience for their users. This is evident in Hugo’s many functions, and handy tricks like Image Processing and Shortcodes. They seem to release new fixes and versions about as often as I make a new cup of coffee - which, depending on your use case, may be fantastic, or annoying.

If you still can’t decide, don’t worry. The OpenGitDocs documentation theme I created is available for both Hugo and Jekyll. Start with one, switch later if you want. That’s the benefit of having options.

How to Publish a no-code website in 10 minutes

freeCodeCamp — Sat, 28 Mar 2020 20:59:47 +0000

In this article, I'll introduce a no-code, no-software and no-cost solution to publishing sophisticated web sites managed by non-technical people. The full codebase is on GitHub here.

Sir Issac Newton discovered the law of gravity when practicing “social distancing” during the Plague. What will YOU do? One silver lining of quarantine is that all this free time brings out the entrepreneur spirit and creativity in us.

However, especially because of the quarantine, now more than ever, any new idea or project must have a web site. Traditional CMS solutions like Wordpress, Squarespace, or Wix are difficult to use, look dated, are expensive, or all of the above!

We wanted to create a web site that has a sophisticated look and feel, yet is easy to customize. A non-technical person should be able to edit the source files and see the changes appear on the live web site in a few minutes. Ideally, it should also be free (forever free, not just free-for-now), and can scale to handle millions of visitors if it becomes popular.

Is this possible?

In this short article, I will walk you through a solution based on the Hugo framework, GitHub Pages, and GitHub Actions. You can get up and running with your shiny new website by the end of this article.

It is so easy that my 9-year-old son did it. He now manages a web site for his fictional country called Arenztopia. Check out the back story.

TL;DR

If you just want to get started with a working web site as soon as possible, first make sure that you have a free GitHub account.

Go to this GitHub repository, and click on the “Fork” button on the top right, and fork it to your own account.

Go to your forked repository, and click on the Actions tab. You will see a message like the one in the picture below. Click on the “I understand my workflows …” button.

Go to the Settings tab of your repository, and then scroll down to GitHub Pages. Re-select the gh-pages from the dropdown for the web site to build.

Go to the Code tab of the repository, open the config.toml file, and edit it. Change its title attribute to something else, and click on the “Commit changes” button at the bottom. We need this step to trigger the workflow at the new repository.

Wait a few minutes, go to the “published at” web address at GitHub Pages and you will see the template web site.

Next, you can customize the site by editing the config.toml file and the files in the content folder. Go to the “Add your own content” section at the end of this article to see how. You can check out the instructions for the Ananke theme here.

That’s it for the quick start! In the next several sections, I will explain in more detail the concepts and processes.

Hugo basics

Older generation CMS solutions like Wordpress are too difficult to adapt to new web site designs, and commercially hosted solutions like SquareSpace are too expensive and not flexible enough. Static web site generators like Hugo offer a good balance among features, flexibility, and ease of authoring.

Hugo web sites can be customized and modified through configuration files.
New pages and content sections can be written in markdown instead of HTML. That makes content authoring much easier.
There are many modern design themes to choose from.
The output of Hugo is a static HTML web site that can be deployed on any low-cost hosting provider.
Together with static web site hosting services like GitHub Pages and Netlify, they can offer a completely free solution.

The Hugo software distribution is available on all major operating systems. You can learn about it here. But, since we will use GitHub Actions to automatically build our Hugo web sites, we do not actually need to install Hugo software here.

Here is how to do it.

Create a template website

First, select a Hugo theme. There are many. Some are geared toward web sites with one or more content web pages, while others are optimized for blog-like sites with timestamped posts.

Hugo themes

Find one you like, download a zip package or clone a GitHub repo, and unpack the theme into a folder. Let’s assume that the theme distribution is unpacked into a folder called my-theme. The following are commands in a Linux terminal. You could use the Terminal app on Mac or PowerShell on Windows.

Next, create your web site project directory on your computer.

$ mkdir -r my-site/themes

Copy the theme folder into your project.

$ cp -r my-theme my-site/themes

Next, copy the theme’s exampleSite to the project’s top-level directory.

$ cd my-site
$ cp -r themes/my-theme/exampleSite/* ./

Edit the config.toml in the project root directory my-site/ to point to the right theme.

baseURL = "/"themesDir = "themes"theme = "my-theme"

Next, create a GitHub repo called my-site, and push the my-site directory onto its master branch. Here are the steps for uploading files from GitHub’s web UI. Now we are ready to publish the theme example site.

For a Hugo-based system to be useable to a non-developer (or a young developer who has yet to master the command line tools), we must automate the process of building and deploying the static web site.

Automate deployment

In the GitHub project, go to Settings and enable GitHub Pages. Select the source to be the gh-pages branch.

Settings, GitHub Pages

Next, we create a GitHub Actions workflow to run the Hugo command on the source files from master branch, and push the generated HTML files to the gh-pages branch for publication. From the project’s Actions tab, click on the “set up a workflow yourself” button.

Set up a workflow yourself

The workflow is stored in the master branch as .github/workflows/main.yml file. The content of the file is as follows.

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v1  # v2 does not have submodules option now
        # with:
        #   submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.62.2'
          extended: true

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

What happens here is that the web site authors and editors will change content and files on the master branch. Whenever new content is pushed to the master branch, the automated GitHub Actions workflow will set up the Hugo software, run the hugo command, and turn those files into HTML files for a static web site.

The HTML files are pushed to the gh-pages branch of the same repository. They will be published on the specified web address by GitHub Pages as configured.

Notice the cname attribute in the last line. That is the custom domain name we set up with GitHub Pages. If you do not have a custom domain name, just remove this line, and you can access your web site at the domain provided by GitHub Pages.

Now go to the web site, and you should see the theme’s default web page.

The HugoSerif template for one of our web sites.

Add your own content

To change the default theme web site to your own content, you just need to change the files on the master branch. Please refer to the documentation of your selected theme. In general, Hugo templates work like this:

The web pages are authored in markdown format and the md files are in the content folder.
Each md file has a header section with properties such as the page’s menu placement, priority, timestamp, excerpt, etc.
The overall configuration, such as the menu items and properties used by multiple pages, are stored in the data folder.
Static content such as raw HTML files, JavaScript files, and image files can be placed in the static folder.

In particular, here is how you customize the Ananke theme that comes with our template:

The config.toml file allows you to configure the website title, social icons on all pages, and the big featured image on the home page.
All images should be uploaded to the static/images folder.
The content/_index.md file contains the text for the home page.
To add pages to the site, you can just create markdown files in the content folder. An example is the contact.md file. Notice that at the top of the file, there are attributes to control whether this page should be on the website menu.
To add articles to the site, you can create markdown files in the content/post folder. Those are blog-like content articles that have dates and titles at the top. The most recent two articles will show up on the home page.

If you are interested in learning more and see how we did it, you can watch our progress at

The Country of Arenztopia [GitHub] [Web site]
Second State blog [GitHub] [Web site]

Good luck and stay healthy!

About the author

Dr. Michael Yuan is the author of 5 books on software engineering. His latest book Building Blockchain Apps was published by Addison-Wesley in Dec 2019. Dr. Yuan is the co-founder of Second State, a VC-funded startup that brings WebAssembly and Rust technologies to cloud, blockchain, and AI applications. It enables developers to deploy fast, safe, portable, and serverless Rust functions on Node.js.

Prior to Second State, Dr. Yuan was a long time open source contributor at Red Hat, JBoss, and Mozilla. Outside of software, Dr. Yuan is a Principal Investigator at the National Institutes of Health, with multiple research awards on cancer and public health research. He holds a PhD in astrophysics from the University of Texas at Austin.

How to host and deploy a static website or JAMstack app to AWS S3 and CloudFront

Colby Fayock — Wed, 11 Mar 2020 13:16:31 +0000

S3 and CloudFront are AWS cloud services that make serving static assets powerful and cheap. How can we host a simple static website or JAMstack app on it?

A little about AWS
What are the benefits of serving from S3 and CloudFront?
Before we start, you’ll need an AWS account
Storing your website on S3
Serving your website on S3
Distributing your website on CloudFront
Custom domain names
Advanced AWS Usage
Resources

A little about AWS

If you’re not familiar, AWS (Amazon Web Services) is a cloud service provider that gives developers opportunities to build pretty much anything they can imagine in the cloud.

Though their services extend beyond the likes of machine learning and artificial intelligence, we’re going to stick with the entry level services for the purpose of this guide that will allow us to easily host an HTML website.

Types of AWS services available

Building a site with S3 and CloudFront is a common recipe that small and high scale companies across the web use, but let’s break down what each service actually does.

Object storage with S3

S3 (Simple Storage Service) acts as your hosting for your static website. Think of it like a hard drive in the cloud which we’re not able to use it for processing purposes, but rather for simple file storage and access.

List of files from a static site in an AWS S3 bucket

When an app or website is compiled in static form, this is all we need to serve it to the people visiting our site. The HTML is sent in the initial request “as is” (unless there’s processing with your provider) and any additional work occurs after the page loads in the browser usually by JavaScript. This allows us to take this simple (and cheap) approach by serving these files from S3.

Content Delivery Network with CloudFront

CloudFront works as a CDN (Content Delivery Network) that sits in front of your website, caching the files, and serving them directly to the people visiting your site.

CDN Diagram

Where you host and serve your website from, typically called the origin, is the main source of your files and can serve the website itself. But putting a CDN in front of it provides the people accessing your content a shorter and faster way to make their request.

What are the benefits of serving from S3 and CloudFront?

Given the rise in the JAMstack era, many services are popping up that provide similar services for static sites that make it really easy to deploy. Some even come with a generous free tier like Netlify and Zeit!

But sometimes developers need a little bit more control over their services or they need to integrate into a larger cloud pipeline that’s already 99% percent in AWS, which is exactly where S3 shines. Also, chances are, during your first year you might still qualify for AWS’s free tier.

Fitting in to the AWS Well-Architected Framework

As a lead provider in cloud services, AWS has published many guides to help developers and teams strive for excellence in their solutions in terms of performance, cost, and security.

One particular guideline is their 5 pillars of what they describe as a “well-architected" infrastructure.

AWS Well-Architected Framework

By default, we check all of these boxes with our hosting solution by using S3 and CloudFront. Out of the box, the HTML and assets you serve will be fast, cheap, secure, and reliable.

The beauty of static and JAMstack sites

Building on top of the pillars, what you’re actually serving is a static HTML file and group of assets that won’t require any type of rendering resources on the initial request. Before this, a common problem was having to worry about a site crashing due to heavy load. But with S3 and CloudFront, your website is infinitely scalable.

On a similar note, when that server scales up as it's trying to serve millions of hits on your post that went viral, so will your costs. Serving a static site is cheap and can greatly reduce the cost associated with running a web server.

Before we start, you’ll need an AWS account

To work through this guide, you’ll need an AWS account. Luckily, it's free to create an account – you’ll only pay for the services used.

On top of that, AWS provides a generous free tier for some of its services. Some services provide only 12 months of a free tier (like S3) where others are always eligible for the free tier (like Lambda), so make sure to do your homework so you don’t rack up an unexpectedly high bill.

To create your account, head over to the AWS website and then continue on to get started: https://aws.amazon.com/.

Storing your website on S3

To get started, we’re going to begin with a simple HTML file that will serve as our website. This will allow us to focus more on the process of hosting rather than the intricacies of the website itself.

Creating our website file

Begin by creating a new folder called my-static-site. Inside that folder, let's create a new file called index.html and add the following to the file:

html>
<html lang=“en”>
<head>
  <meta charset=“UTF-8”>
  <meta name=“viewport” content=“width=device-width, initial-scale=1.0”>
  <title>My Static Websitetitle>
head>
<body>
  <h1>Hello World!h1>
  <p>This is my static website. ?p>
body>
html>

If you open this file from your computer in your favorite browser, you should now be seeing this.

Hello World! Opening a local webpage

Creating a new bucket

Head on over to your AWS account, log in, and navigate to your S3 console.

Once there, let’s create our bucket by clicking on the blue Create bucket button:

Creating a bucket in AWS S3

The first thing AWS wants us to do is enter a Bucket name. The bucket name must be globally unique, meaning, the name you use can be the only one in the world, so let’s try something like [yourname]-static-website, where I’ll use colbyfayock-static-website.

Naming a bucket in AWS S3

Next, let’s set the Region. This is the geographic location where AWS will host the bucket and your website. You’re probably fine with the default, but if you’d like, you can select the location closest to you if it’s permitted. Since I’m in Virginia, I’m going to stick with my default of US East (N. Virginia).

Setting the region of a bucket in AWS S3

Finally, hit the Create button on the bottom left of the page.

Note: even if you use the [yourname]-static-website pattern, there’s a chance the name will be taken. If it’s taken, AWS will show an error stating “Bucket name already exists,” at which point you’ll want to try a new name of your choosing.

Alternatively, you can hit Next for advanced usage, but for this guide, we’re okay with all of the defaults S3 provides.

If successful, you should now see your bucket in the list on the S3 console dashboard.

New bucket in AWS S3

Uploading your website to the bucket

Let’s navigate to our new bucket by clicking the row of our bucket. You’ll be greeted with a message stating “This bucket is empty. Upload new objects to get started,” so that’s what we’ll do.

Click the Upload button to get started.

Uploading files to AWS S3

You’ll then see a popup that will ask you to upload a file. Click on the Add files button and select your index.html file we created earlier.

Once selected, click the Upload button on the bottom left.

Selecting files to upload in AWS S3

And now your file is uploaded to S3!

Serving your website on S3

If you try to navigate to your index.html file and open it, you’ll notice a big ugly "Access Denied" message.

Access Denied to bucket file

This is because your file doesn’t currently have the permissions and settings necessary to serve the file to the public, so let’s fix that.

Setting up your bucket as a website

Navigate to the Properties tab inside of your bucket, then click Static website hosting.

Setting up an AWS S3 bucket for statice website hosting

Once there, we want to do a few things:

Note down the Endpoint at the top of the block. We’ll use this to access our site later (you can always find this here again)
Select the “Use this bucket to host a website” option
Enter index.html in the Index document field
Finally hit Save

Configuring an AWS S3 bucket for static website hosting

Setting up your bucket policy and permissions

Next, navigate to the Permissions tab. Here we’ll want to do 2 things: unblock all public access and add a Bucket Policy.

First, on the main page, let’s click Edit to unblock all access.

Configuring an AWS S3 bucket permissions

Then, uncheck the “Block all public access” checkbox and hit Save.

Allowing public access to an AWS S3 bucket

AWS will ask you to confirm these settings, as this may not always be what you want to do with your bucket. But for the purposes of hosting a website, we want the whole world to see, so type in the word “confirm” and hit the Confirm button.

After confirming, click the Bucket policy button and you’ll be taken to a text editor.

In this text box, we’ll want to paste the following snippet. Within this snippet, make sure to replace [your-bucket-name] with the name of your bucket, otherwise you will not be able to save this file.

{
  "Version":"2012-10-17",
  "Statement":[{
    "Sid":"PublicReadGetObject",
        "Effect":"Allow",
      "Principal": "*",
      "Action":["s3:GetObject"],
      "Resource":["arn:aws:s3:::[your-bucket-name]/*”
      ]
    }
  ]
}

This policy states that it’s allowing the public to perform a GetObject request on the S3 resource, which is your S3 bucket.

Setting up a public policy for an AWS S3 bucket

After you add the policy, click the Save button. Your should now see a message stating "This bucket has public access.”

Previewing your new bucket website

If you noted down the Endpoint from your Properties page, you can now visit that address to see your website. The endpoint should look like this:

http://[your-bucket-name].s3-website-[region-id].amazonaws.com

If you didn’t, jump back up a few steps to remind yourself how to find it or look under the Properties tab.

Hello World! Opening an AWS S3 website

Congrats, you're halfway there! ?

Distributing your website on CloudFront

Now that we have our static website being served from a bucket on S3, let’s take it up another level and serve it across the world using CloudFront.

Creating a CloudFront distribution

Navigate to your CloudFront dashboard and click the Create Distribution button.

Creating a new distribution in AWS CloudFront

Next, select Get Started under the Web delivery method.

Getting started with an AWS CloudFront distribution with Web delivery

Here, we’ll enter a few custom parameters to get our distribution set up.

Click into the Origin Domain Name field. Once selected, a dropdown list should appear where you can select the S3 bucket you just created. Go ahead and select your S3 bucket.

Setting the origin domain name in AWS CloudFront to your bucket

While you can customize most of the settings to your liking, for our purposes, we’re going to leave all as their default values except for one.

Scroll down to the Default Root Object field and type index.html.

Setting the Default Root Object for a distribution in AWS CloudFront

After, scroll down to the bottom and click Create Distribution in the bottom right.

Creating an AWS CloudFront distribution

Previewing your new CloudFront distribution

After hitting the Create button, it will take some time for your distribution to be created and set up. You’ll notice on the CloudFront Distributions list page that the Status of your new distribution is In Progress.

AWS CloudFront distribution deployment is In Progress

Once this completes, it will say Deployed. Then you can find your Domain Name in the same row.

AWS CloudFront distribution is Deployed

Using the value in the Domain Name column, open your distribution in your browser and success! You now are viewing your S3 bucket through CloudFront’s distribution network.

Hello World! Opening an AWS CloudFront website

Custom domain names

While most of us will probably want to use a custom domain name with our website, we’re not going to dive too deep into that this guide, as there are many ways to set that up depending on where you purchase your domain name.

However, here are a few things to consider.

HTTPS / SSL Certificate

If you’re creating your CloudFront distribution to use with a custom domain name, you'll most likely want to configure your distribution with an SSL certificate using AWS’s Certificate Manager. Alternatively you can provide your own certificate with tools like Let's Encrypt, but by using ACM, AWS makes it easy to pull in the records for use with your distribution.

Once in ACM, you’ll want to configure the certificate, map what domains and subdomains should match (typically *.domain.com), and then create your certificate to use with your distribution.

To get started, you can check out the AWS guide for requesting a public certificate.

CNAMEs and Aliases

A common approach to setting up a custom domain is to use a CNAME. CloudFront makes this pretty painless, as you’ll add it as a configuration option when you’re configuring your distribution.

To get started with setting up a CNAME in CloudFront, see the AWS guide.

If you’re using Route53 to manage your DNS, you can then set up an A record (alias) to point to your distribution. You can learn more using this guide.

Advanced AWS Usage

For this guide, we walked you through setting up a new static website and app using the AWS console. But whether you want to learn more, improve your deploy efficiency, or want to automate this process, you’ll want to take a it a step further with the AWS CLI or CloudFormation.

While we won’t walk you through how to use these tools here, we’ll get you started with a little bit of an idea of what you’re up against.

AWS CLI

The AWS CLI allows someone to perform AWS operations from the command line. This can be incredibly powerful when you want to script out your resource creation or if you simply prefer to do all of your work from the terminal.

Once set up locally, you’ll be able to perform actions like creating a bucket using the following command:

aws s3api create-bucket —-bucket [your-bucket-name] —-region [bucket-region]

To get started, check out the AWS CLI Github page or the AWS CLI User Guide .

AWS CloudFormation

AWS preaches “infrastructure as code.” It’s the idea that you can spin up your infrastructure using something that’s written in a file, where in this particular case, it would be a CloudFormation template. This allows you to have a repeatable process that will be the same each time you perform the deploy.

CloudFormation allows you to set up a configuration file that will deploy the services and resources of your choosing by pointing to that file with the CLI or by uploading it in the console.

Here’s an example from AWS of what that looks like for a static S3 bucket that could serve as a website.

AWS CloudFront template example

To get started, check out AWS’s CloudFormation example templates or their Get Started guide.

Resources

If you’re interested in getting deeper into the AWS ecosystem, here are a few resources to get started:

AWS Certified Cloud Practitioner Training 2019 - A Free 4-hour Video Course (freeCodeCamp.org)
Introducing The #AWSCertified Challenge: A Path to Your First AWS Certifications (freeCodeCamp.org)
10-Minute Tutorials (AWS)
A Cloud Guru (Paid courses)
AWS Case Studies (AWS)

Brilliant Add-on For Static Sites That Will Make You Dance

freeCodeCamp — Mon, 08 Jul 2019 12:30:00 +0000

By Jared Wolff

This post is originally from www.jaredwolff.com

Privacy.

Performance.

Brilliant looks.

Can you have all three?

(Of course!)

Having a statically generated blog is great. Many folks use services like Disqus and Google Analytics to make them even better. Not surprising if you were one of them! Privacy concerns are are the forefront of everyone’s attention. So, rather than keeping the status quo, it’s time to do something about it!

If you've been looking to protect your site visitor's privacy and improve performance this blog post is for you.

In this article we'll be using DigitalOcean’s Docker droplet. It allows you to host several different applications/services on one (virtual) machine. By the end of it you'll know how to run your own comments server using Commento. Plus i’ll share a few tricks i’ve learned along the way to make it much easier for you.

Leeeets go!

Reverse Proxy

One of the most important aspects of this setup is the reverse proxy. A reverse proxy acts like a router. Requests come in for a certain domain. That request is then routed to the service associated with that domain.

Here’s a diagram from the Nginx Reverse Proxy + Let’s Encrypt Helper documentation. It'll help illustrate the idea.

Another benefit is that there’s an extra layer of protection to the outside world. Your websites run in a private network and the only access is through the Nginx reverse proxy. Point your DNS to the server and Nginx handles all the magic.

Here's how to get it setup:

Go ahead and set up your Digital Ocean Droplet. All the info you need is right here. The $5 version is more than sufficient.
Go here to clone the repository. You can also run this in your terminal. Make sure you SSH into your Digital Ocean droplet first!

git clone git@github.com:evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git
Change directories to the cloned repository.
Copy .env.sample to .env and update the values inside. I had to change the IP value to the IP of my Digital Ocean Droplet. I left all the other ones alone.
Run docker-compose up -d to start everything. (you can run without the -d option to make sure everything starts ok. Or you can attach the log output using docker container logs -f


When pointing your sub-domains to this server, make sure you use an A record. Here's an example of mine:

Depending on your DNS provider, you'll have to figure out how to set an A record. That is beyond the purpose of this article though!
Setting Up Commento with Docker Compose

Here is the current docker compose file i'm using for Commento. It includes a few more environment variables for configuring Github, Gitlab and Google. It also includes the environment variables for setting the SMTP settings. These parameters are important. Otherwise you can't receive password reset or moderation emails!
    version: '3'
    services:
      commento:
        image: registry.gitlab.com/commento/commento
        container_name: commento
        restart: always
        environment:
          COMMENTO_ORIGIN: https://${COMMENTS_URL}
          COMMENTO_PORT: 8080
          COMMENTO_POSTGRES: postgres://postgres:postgres@postgres:5432/commento?sslmode=disable
          COMMENTO_SMTP_HOST: ${SMTP_HOST}
          COMMENTO_SMTP_PORT: ${SMTP_PORT}
          COMMENTO_SMTP_USERNAME: ${SMTP_USERNAME}
          COMMENTO_SMTP_PASSWORD: ${SMTP_PASSWORD}
          COMMENTO_SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS}
          COMMENTO_GITHUB_KEY: ${COMMENTO_GITHUB_KEY}
          COMMENTO_GITHUB_SECRET: ${COMMENTO_GITHUB_SECRET}
          COMMENTO_GITLAB_KEY: ${COMMENTO_GITLAB_KEY}
          COMMENTO_GITLAB_SECRET: ${COMMENTO_GITLAB_SECRET}
          COMMENTO_GOOGLE_KEY: ${COMMENTO_GOOGLE_KEY}
          COMMENTO_GOOGLE_SECRET: ${COMMENTO_GOOGLE_SECRET}
          COMMENTO_TWITTER_KEY: ${COMMENTO_TWITTER_KEY}
          COMMENTO_TWITTER_SECRET: ${COMMENTO_TWITTER_SECRET}
          VIRTUAL_HOST: ${COMMENTS_URL}
          VIRTUAL_PORT: 8080
          LETSENCRYPT_HOST: ${COMMENTS_URL}
          LETSENCRYPT_EMAIL: ${EMAIL}
        depends_on:

postgres
networks:
db_network
webproxy
postgres:
image: postgres
container_name: postgres
environment:
POSTGRES_DB: commento
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
networks:

db_network
volumes:
postgres_data_volume:/var/lib/postgresql/data
networks:
db_network:
webproxy:
external: true
volumes:
postgres_data_volume:


To set the environment variables, put them inside an .env file. Make sure the .env file is in the same directory as docker-compose.yml. When you run docker-compose up it will apply the variables set in the .env file. Nothing gets set if they're left blank.
Set the required COMMENTS_URL and EMAIL or you may run into problems. The best way to set these is by pacing them in the .env file. Here is an example:
    COMMENTS_URL=comments.your.url
    EMAIL=you@your.url
Getting OAuth Key & Secret
Commento works with most popular OAuth providers. Thus visitors can leave comments without making an account.
The instructions are similar for each. I've outlined the steps for all of them below.
Twitter

Login to Twitter.com and apply for a developer account: https://developer.twitter.com/en/application/use-case
 

Describe how you'll use the API. You can use what I wrote.
 

Double check your entry and click Looks Good!
 

Agree to the terms of service.
 
 

They'll tell you to check your email for a confirmation. Confirm your email and you should be able to create your first app!

Once approved to to Get started click Create an app.
 

Next screen, again click Create an app
 

Enter all the appropriate details. For the callback URL, use https:///api/oauth/github/callback where  is your Commento subdomain.
 

Finally, once you're done filling out the information to go the Keys and Tokens area. Save both the key and token. Enter them into the .env file. You can use COMMENTO_TWITTER_KEY and COMMENTO_TWITTER_SECRET
 


Gitlab

Login to Gitlab.com and go to to top right and click Settings
Then click on Applications
 

Enter a name for your app. I put Commento.

Set the Redirect URI to https:///api/oauth/gitlab/callback
Select the read_user scope.
 

Click the green Save Application button

Copy the Application ID and Secret and place them in your .env file using COMMENTO_GITLAB_KEY and COMMENTO_GITLAB_SECRET
 


Github

To get your OAuth key and secret, you'll need to go to this URL: https://github.com/settings/developers
Once there, click on New OAuth App
 

Enter your details. For the callback URL, use https:///api/oauth/github/callback where  is your Commento subdomain.
 
 Note: Make sure you include https in your URLs.

Grab the Client ID and Client secret and put that into your .env file using COMMENTO_GITHUB_KEY and COMMENTO_GITHUB_SECRET
 


Google
Setting up Google is just about as tedious to set up as Twitter. Despite how scary I just made it out to be, it's completely doable. Here are the steps.

Go to this URL: Google Developer Console
Create a new project
 

Click the GoogleAPIs logo in the top left corner to go back once you have a project. (Make sure the dropdown next to the GoogleAPIs logo is the same as your new project!)

Then, click Credentials on the left side.
Update the Application Name and Authorized Domains in the OAuth consent screen
 

Click Create credentials then OAuth client ID
 

On the Create OAuth client ID enter the subdomain associated with Commento to Authorized Javascript origins. Then, enter the full callback URL. For example https://comments.jaredwolff.com/api/oauth/google/callback. Make it yours by replacing comments.jaredwolff.com with your URL.
 
 Once entered, click the create button.

Grab the client ID and client secret
 

Update your .env file using COMMENTO_GOOGLE_KEY and COMMENTO_GOOGLE_SECRET


Install your application
You've entered your OAuth Credentials email, domain and SMTP credentials. It's time to wrap this show up!

Once you're done editing your .env file. Run docker-compose up (For files not named docker-compose.yml, use the -f flag. Example: docker-compose -f commento.yml up
Watch the output for errors. If it looks good you may want to kill it (CTRL+C) and run with the -d flag
On first start, Commento will prompt you with a login screen.
 

Create a new account by clicking Don't have an account yet? Sign up.

Enter your information and click Sign Up
Check your email and click the included link:
 

Log in with your freshly made account.

Then, click Add a New Domain.
 

Once created go to Installation Guide.  Copy the snippet and place it where ever you want your comments to live. In my case, I put the snippet in an area just after my 
 tag.
 

Re-compile your site and check for success!

Checkmark! Finally, I recommend you try logging in with each individual OAuth configuration. That way you know it working for your website visitors. ?


Alternatives
I spent a good chunk playing around with some of the alternatives. This is by no means a definitive guide on what will work best for your site. Here are some of the top ones as of this writing:
https://utteranc.es/#configuration
https://github.com/netlify/gotell
https://github.com/eduardoboucas/staticman
https://posativ.org/isso/
https://www.remarkbox.com
https://www.vis4.net/blog/2017/10/hello-schnack/
https://github.com/gka/schnack
There's also a huge thread over at the Hugo blog which has a ton more links and resources as well:
https://discourse.gohugo.io/t/alternative-to-disqus-needed-more-than-ever/5516
Conclusion
Congrats! You are now hosting your own comments server! ?
In this article you've learned how to harness the power of Docker and a Nginx Reverse Proxy. As an added bonus, you know how to  set up OAuth credentials! That way future setup will be easy peasy.
By the way, this is only the tip of the iceberg. You can set up the same server for analytics, data collection and more. All the example code including code for other applications can be found here.
Finally, if you're looking pay for Commento head to www.commento.io and sign up for the service. You'll be supporting awesome open source software!
If you have comments and questions let's hear em'. Start the conversation down below. ???



 Gatsby vs Hugo, a detailed comparison 
freeCodeCamp — Sat, 28 Jul 2018 00:00:00 +0000
 By David
In this article, I compare two static site generators, Gatsby and Hugo. I discuss framework familiarity, stability, security, tooling, build speed, performance and the community surrounding both. So let’s get started.
About a year ago, I changed my website from Wordpress to Hugo, which is a static site generator written in Go that uses Go’s template libraries for templating. I have recently done a viability assessment of Gatsby, another static site generator written in React that uses React for templating.
In this article, I compare the differences between Hugo v0.42 and Gatsby v1.93. For the comparison, I used this Hugo site and this Gatsby site. The code for each can be found on Github for the Hugo site and for the Gatsby site.
Framework familiarity
If you are not familiar with React and you don’t plan on learning React, then you should probably choose Hugo. If you know and like React, should you choose Gatsby? Well, not necessarily.
I would argue that you need a decent understanding of React (see Learn React with these Resources) if you want to use Gatsby. And in order to understand React, you need a decent understanding of JavaScript (see Learn JavaScript with these resources).
Even though I have been using Hugo for almost a year, it wasn’t necessary for me to understand Go. I also only had to learn a little bit about Go’s template libraries. However, I did find that I had to refer to the documentation more often with Hugo because of my lack of familiarity. Gatsby requires a deeper understanding of React than Hugo expects of Go. Nevertheless, if framework familiarity were the only criteria, I would choose Gatsby because it’s nice not to have to refer to the documentation while adding new features to my website.
Stability
One way of assessing stability would be to compare Hugo’s issues on GitHub with Gatsby’s issues on GitHub. You will see that Gatsby has more features, (which is exciting) but also has more bugs (which is not so exciting). I initially did not consider stability as a criteria until I found this bug and that made me realise the importance of stability in software. I may be taking this one personally because of the time and effort I expended, trying to find that bug, but I still think Hugo is more stable than Gatsby.
Security
Gatsby uses JavaScript, and JavaScript applications are notorious for requiring a lot of Node modules to run. There is even a Node module that sends Hot Pocket tweets and another that harvests credit card numbers :D. Static sites tend to be more secure by nature, but I still think it is worth mentioning that more dependencies result in more code that you might not trust.
Tooling
Gatsby has all the advantages of the JavaScript toolchain and all the disadvantages of JavaScript fatigue. On top of that, Gatsby has a really nice plugin library. In particular, gatsby-plugin-offline allowed me to easily add offline capabilities to my website, which I still haven’t figured out with Hugo.
On the other hand, some things that require a plugin with Gatsby just come out of the box with Hugo. For example, gatsby-plugin-react-helmet is needed to edit the head tag, whereas this can be done with simple HTML in Hugo. Since I enjoyed using the tooling that came with Gatsby, I give this one to Gatsby.
Build speed
Hugo is able to build my website without any additional tooling in less than 100ms. Gatsby is able to build my website in about 15 seconds, but this does include a lot of additional tooling. Adding PostCSS and Imagemin to the Hugo build bumps the build time up to about 5 seconds. Watching for changes during development was also faster using Hugo. I think Hugo is the winner here.
Documentation
Both Gatsby and Hugo have really nice documentation. Hugo has a Quick Start and Gatsby has a Getting Started section. Gatsby also has a really nice tutorial, which evens out the steeper learning curve. Personally, I found it easier to get started with Gatsby, but that is because I already understood React. I think it is fair to say that both Hugo and Gatsby have great documentation.
Performance
Using Lighthouse, the performance score was 100 for my site in Hugo and 95 for my site in Gatsby. The First Contentful Paint for a 3G connection was about 1 second for the Hugo site and 1.5 seconds for the Gatsby site. Using Web Page Test the load time on a 2G connection was 8.7 seconds in Hugo and 11.7 seconds in Gatsby.
However, doing a simple manual test to see which site loads first, Gatsby was noticeably faster, so I don’t really understand what Lighthouse or Web Page Test was measuring. Furthermore, as Gatsby is a Single Page App, navigating within the website does not require a request from the server. Pages are just re-rendered with JavaScript. Anyhow, I can say with certainty that both Hugo and Gatsby are fast. I would be interested to hear your thoughts in the comments below.
Community
Gatsby is gaining popularity quickly, which comes with a thriving community. That is not to say that Hugo’s community is boring. If GitHub stars are anything to go by, Hugo has more than 27 thousand and Gatsby has more than 23 thousand. On Twitter, Gatsby seems to be more active than Hugo.
Final thoughts
So which one should you choose? Gatsby uses React, which I am more familiar with, it has better tooling, and it has a thriving community. On the other hand, Hugo is more stable and spends less time building. For larger websites, build speeds become more important and some of you might not care for React at all. In my case, stability was the most important criteria, so I decided to stick with Hugo. I am very excited to see what the future brings in this space.

Before you go… Thanks for reading the article! I write about my professional and educational experiences as a self-taught software developer, so check out my blog or subscribe to my newsletter for more content.
You might also like:

How I release updates to my personal website
Learning material — software development (a list of learning resources, starting with Introduction to Computer Science)
Is full-stack web development worth learning?

Static Site Generators - freeCodeCamp.org

Lume SSG Handbook – How to Create a Static Blog with Lume

What is Deno?

Table of Contents

Lume + Markdown

Why is Lume special?

How Does Lume Compare to Other Static Site Generators?

How to Start a New Project with Lume

Follow these steps:

Lume Folder Structure

How to run the Lume server

Additional folders:

How to Create Global Data

How to create posts, pages, and author markdown files

How to create a dynamic page

How to create a home and pagination page

Posts is empty

How to Build an Articles Page

{{ title }}

Comment

How to Generate a Category Page

How to Generate a Tag Page

How to Enable Search Functionality

How to Install Page Find

How to configure the page find plugin

Lume SEO

How to install metas

How to configure metas

How to Use the Metas SEO Plugin in Lume

Lume Sitemap

How to install the sitemap plugin

How to configure the sitemap plugin

How to use the sitemap plugin in Lume

How to access the sitemap on the website

Lume Plugins

How to Enable Comments

How to Use Netlify CMS with Lume

How to Install the Netlify Plugin

How to Deploy Your Blog with Deno Deploy

Deployment Steps:

How to Deploy Your Blog with Github Pages

Deployment Steps

Conclusion

Learn the Eleventy Static Site Generator by Building and Deploying a Portfolio Website

What is Eleventy?

Table of Contents:

Prerequisite - Install Node.js

Initial Project Setup

How to Configure the Project

How to Add a Template

Optional Step – How to Create Custom Build Commands

How to Use Templates in Eleventy

Home Page

Home Page

About Page

Contact Page

How to Use Layouts in Eleventy

{{ title }} Home Page

How to Configure the CSS and Images

How to Use Partials in Eleventy

How to Use Collections in Eleventy

How to Use Directory Data Files

How to Use Collections in Templates

class="projects__heading">Recent projectsh2> <div class="project-list"> {% for project in collections.projects %} {% include "project-card.njk" %} {% endfor %} div>

How to Use Shortcodes

How to Use the Eleventy Image Plugin

How to a Build Contact Form with Netlify Forms

How to Deploy to Netlify

Option 1 – How to Deploy Manually

Option 2 – How to Import a Project from Git

Where to Take it from Here

From WordPress to Hugo – How I Migrated a 250+ Page Site and the Scripts I Used

How to Export WordPress Posts as Markdown

How to Use Hugo’s Built-in SEO Templates

Script 1 — Checking for Broken Links

Script 2 — Minifying Images

Script 3 — Managing Global Shortcodes

Script 4 — Converting .docx to Markdown

Wrapping Up

How to Create a Theme-able Static Website

`Home Page`

`class="projects__heading">Recent projectsh2> <div class="project-list"> {% for project in collections.projects %} {% include "project-card.njk" %} {% endfor %} div>`

Creating a top-level menu with the `pages` object