How a site is built | HAP's Learning Lab: How Sites Get Built

The Ways Files Reach A Browser

Every website on the internet gets its HTML to your browser in one of three ways. The fastest way to understand where a build fits is by separating these three approaches.

Hand-written files

Someone writes text and markup into a file, usually named 'index.html', then uploads it along with some CSS for styling and a handful of images. The folder structure has to match exactly how it worked on their own machine, since a link like <img src="images/logo.png"> only finds that image if the images folder sits in the same place relative to the HTML file. When a visitor arrives, the server hands out those exact files, unchanged. No program sits in between to generate or alter anything. This is how the web began, and for small, straightforward sites, it still works beautifully.

Assembled per request

The page is dynamically generated for a specific visitor at the exact moment that visitor is on that page. The server runs a program, and that program produces the HTML on the spot, usually from a database. When you click a link on a dynamic site, the browser sends an HTTP request. The request wakes up the server, which then pulls user data from a database, drops that data into an HTML skeleton file (a process called templating), and hands the completed HTML back to the browser. Most sites with logins and shopping carts work this way.

Built ahead of time

A developer edits source files. A program on their computer reads those source files and writes a finished set of HTML, CSS, and JavaScript. Those finished files get uploaded. The server hands out exactly those. This is a static site, and it is what this course builds. The static site builder called Eleventy, often written 11ty and being rebranded as Build Awesome, is the example we use because it does not force unnecessary JavaScript onto the user's browser. This frees us to explore the other parts of web development: HTML, CSS, semantic structure, accessibility, and standard browser features, without getting bogged down by heavy front-end frameworks.

A Mix

The hybrid option combines both worlds by pre-building as much of the site as possible while leaving small "islands" of the page ready to run live programs. Instead of choosing between a purely static site or a fully live server, a hybrid system builds your standard text and images ahead of time so they load instantly. Then, it only runs a live program on the specific parts of the page that actually require it, like a dynamic shopping cart. This approach gives you the speed of a static site for most of your layout, while still providing the interactive use where you need it.

What A Build Step Is Made Of

A build step has three parts.

Input. The files a person edits. Templates, stylesheets, images, content, configuration.
A program. Something that reads the input and decides what the output should be.
Output. A folder of finished files, usually called dist or _site or build.

That is the whole idea. The reason it looks intimidating is that the program in the middle is usually assembled out of several smaller programs, installed from the internet, and wired together in a configuration file. Underneath all of that, the shape is still those three parts.

A typical project on disk:

my-project/
├── src/            ← the files a person edits
├── package.json    ← what the project needs and how to run it
└── dist/           ← the files a browser receives (generated)

HAP pointing upward with one finger, smiling encouragingly

🟠 The output folder is disposable

Whatever the output folder is called, deleting it costs nothing. A new build recreates the folder from your source files. That gives you a test for whether a file belongs there: if losing it would hurt, it was source all along.

This is also why the output folder is almost always in .gitignore. If you commit generated files, every teammate's build will produce a different diff of files nobody wrote.

What A Build Buys You

Hand-written HTML works fine, so a build step has to be worth the extra complexity. Here is what you get for it.

One change, many pages

If you change the navigation bar in one template, forty pages get the update automatically. Without a build, that is forty files edited by hand and one of them silently missed.

Work in a nicer format than the browser accepts

Markdown content becomes HTML. Modern CSS compiles into code that older browsers can read. The build translates between what is pleasant to write and what browsers actually run.

Automatic optimization

Image optimization, whitespace cleanup, and file bundling are tedious to do by hand. A build handles them every time without being asked.

Repeatability

Because the output is produced by a program, it comes out the same way on your laptop, on a teammate's laptop, and on the machine that publishes the site. Hand-editing has no such guarantee.

The Vocabulary

These words show up constantly in tool documentation and error messages. They mean specific things.

Source

These are the files a person writes and owns. They are committed to git, and losing them is a real loss. Developers often create a folder called src to hold them.

Build

This is both a noun and a verb, representing the act of running the build program and the resulting folder of files.

Artifact

This is any file produced by the build process. It is generated, disposable, and recreatable.

Dependency

This is external code the project needs but did not write. You download it rather than typing it yourself.

Deploy

This refers to moving the output to a server where the public can access it. It is separate from the build step and happens afterward.

Pipeline

A pipeline is a build process with several stages running in order, where each stage feeds the next.

Why This Course Builds Static Sites

A static site is a legitimate production choice, not a beginner's substitute for a real website. Plenty of large sites run this way, because the files are already finished before anyone asks for them, which makes them fast and hard to break.

They are also a good place to learn from, because a static site build contains every piece of a modern toolchain: a runtime that is not the browser, a package manager, dependencies, scripts, a local server, and a deploy. None of it is hidden behind a framework doing five of those things at once. Once you understand these pieces here, larger tools will make sense as the same components with more features.

The next page starts with the runtime, because none of the rest can happen without it.