Lesson 2 - Hello world

Course
Learn Eleventy From Scratch
Module
Let’s build a website

Time to get your site up and running in the browser with a good old-fashioned “Hello, world”.


Now we have a better idea of what Eleventy is and have the tools we need to get started, let’s make something that we can see in the browser.

Remember dotfiles from the last lesson? Well now we’re going to add the most important dotfile of this entire project: .eleventy.js.

Create a new file in your eleventy-from-scratch folder called .eleventy.js and add the following to it:

Code language
JavaScript
module.exports = config => {
  return {
    dir: {
      input: 'src',
      output: 'dist'
    }
  };
};

This is our Eleventy Config file. It's the beating heart of your Eleventy site. It delegates and instructs everything that makes up the final output.

What we've just added is the core, most basic config. We've exported a function which returns some settings. These settings tell Eleventy to look in the src folder for all of our content, templates and other source code, and tell it to use dist as the output folder.

Remember: the output will be folders and HTML pages (at the moment).

Adding some dependencies permalink

We’ve chatted a lot about Eleventy so far, but still haven’t even installed it!

First, though, we need to get ourselves a package.json file. This contains metadata about the project and lets npm identify the project and handle its dependencies.

Because you already have Node.js installed, setting up your package.json file is really straightforward.

Make sure you're in your eleventy-from-scratch folder and run the following in your terminal:

Code language
bash
npm init -y

You should see an output that looks like this:

Code language
text
{
  "name": "eleventy-from-scratch",
  "version": "1.0.0",
  "description": "",
  "main": ".eleventy.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

What's happened here is that npm has generated a package.json file for us, and by using the -y flag, we told it to answer yes to all of the questions it would normally ask.

Now that’s sorted, we can install Eleventy. In the terminal, run the following command:

Code language
bash
npm install @11ty/eleventy

We’ve installed a local version of Eleventy in our project. Let’s make it do something!

The eagle-eyed amongst you might have noticed that we didn’t install Eleventy globally. This is indeed what the quick start suggests on the Eleventy site, but running packages locally, via npx is something I prefer to do, as a symptom of other, more complex projects in the past.

When you work in a team, running packages that are local to the project means that everyone is running off the same setup. This is especially important if you are using webpack.

In the context of this course, it doesn’t really matter which way you choose to do it. Just bear in mind that the commands throughout the rest of this course will be related to using a local version of Eleventy.

Hello, world permalink

In your eleventy-from-scratch/src folder, add a new file called index.md and add the following to it:

Code language
markdown
Hello, world

Yes, that’s pretty uneventful, but let’s now put Eleventy to work. Make sure you've saved your changes in your text editor. Then, in your terminal, in the eleventy-from-scratch folder, run the following command:

Code language
bash
npx eleventy --serve

If you go to http://localhost:8080 in your browser, it should look like this:

Hello, world in a Google Chrome browser window

Pretty cool, right?

By running npx we use the local Eleventy dependency. You can also use npx to run other packages, like Eleventy, locally.

The --serve flag in our terminal command instructs Eleventy to serve the dist folder with a local web server and also watch for any file changes. This means that if you change the content of index.md and refresh your browser: you should see the new content.

Setting up our scripts permalink

Running npx eleventy --serve in the terminal is easy enough, but it would be even easier to just run npm start instead. To do this, we use npm scripts.

Open up eleventy-from-scratch/package.json and find the "scripts" element. Find the line that says "test": "echo \"Error: no test specified\" && exit 1" and replace it with the following:

Code language
json
"start": "npx eleventy --serve"

Your package.json file should now look like this:

Code language
Diff - don’t copy
{
  "name": "eleventy-from-scratch",
  "version": "1.0.0",
  "description": "",
  "main": ".eleventy.js",
  "scripts": {
    "start": "npx eleventy --serve"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@11ty/eleventy": "^0.11.0"
  }
}

Open your terminal again. Press ctrl and c at the same time to stop it, then run npm start. It should fire up that same “Hello, world” page at http://localhost:8080.

Wrapping up permalink

We’ve achieved a lot in this lesson. We’ve installed Eleventy and got it up and running in an npm script. We’ve also added our first piece of content to the site which will become our home page.

Next up: we’re going to start digging into HTML and Nunjucks, which will suddenly start to make things really interesting.

Next up: Lesson 3 - Nunjucks basics

Now that we have Eleventy up and running with a “Hello, world” example, let’s add some HTML and Nunjucks.

Get started

Help! My version of this lesson isn’t working.

Don’t panic, you can download the working project here! Once they are downloaded: replace your project with these files and run npm install. You can read more information here.

Download project files

Hello, I’m Andy and I’ll help you build fast, accessible websites & design systems.

I’m a freelance CSS and design systems consultant, based in the UK. I specialise in design systems and creative web design, such as landing pages and campaign work.

I’m currently helping Google by refactoring the CSS and creating a design system for web.dev, but I have availability for projects such as small websites, landing pages and consultancy. I will have full availability for larger projects in January 2022.

Hire me