HTML Project Structure and Formatting

Introduction

A small static site stays maintainable when files are organized predictably and markup stays consistent. This chapter covers folder layout, naming conventions, relative paths, Prettier formatting, and team habits that keep HTML readable as projects grow beyond a single index.html.

Prerequisites

• Project: small static site
• HTML development environment
• HTML syntax basics

A Sensible Static Site Layout

Start simple, then grow only when needed:

For learning projects, css/, js/, and images/ are enough. Add assets/ when you have non-image files to serve.

File Naming Rules

Use:

• lowercase letters
• hyphens between words
• no spaces
• no special characters

Good:

about.html
contact-form.html
team-photo.webp
main-nav.css

Avoid:

About.HTML
Contact Form.html
IMG_0001.JPG
final_v2_REAL.html

Consistent names reduce broken links when deploying to case-sensitive servers (Linux).

Default Home Page

Most servers look for index.html when a directory is requested:

https://example.com/          -> index.html
https://example.com/about/    -> about/index.html (if configured)

For this course, keep pages as sibling files:

index.html
about.html
contact.html

That is the easiest model for beginners.

Relative Paths in Subfolders

If you later organize pages:

site/
├── index.html
├── pages/
│   ├── about.html
│   └── contact.html
└── images/
    └── logo.svg

From pages/about.html:

<a href="../index.html">Home</a>
<img src="../images/logo.svg" alt="Site logo">

Rules:

• ../ goes up one folder
• ./ means current folder (often omitted)
• paths are case-sensitive on many servers

Test every link after moving files.

Shared Components Without a Framework

Plain HTML repeats headers and footers on each page. That is normal for learning.

Options later:

• copy a snippet template manually
• use a static site generator (Eleventy, Hugo, etc.)
• use server-side includes or a framework

For now, keep a snippet file in your notes or a partials/ folder for copy-paste:

partials/
├── header.html
└── footer.html

These are not loaded automatically unless your host supports includes. They are documentation for you.

Prettier for HTML

Prettier formats HTML consistently.

VS Code:

1. Install the Prettier extension.
2. Enable Format On Save.
3. Set Prettier as the default formatter for HTML.

Example before:

<main><section><h2>Features</h2><p>Fast and accessible.</p></section></main>

After format:

<main>
  <section>
    <h2>Features</h2>
    <p>Fast and accessible.</p>
  </section>
</main>

Formatting does not change meaning. It makes diffs and reviews easier.

Formatting Conventions

Agree on basics:

Long attributes wrap cleanly:

<img
  src="images/hero.webp"
  alt="Team collaborating on a website wireframe"
  width="1200"
  height="675"
  loading="lazy"
>

Semantic Markup Conventions

Team rules that age well:

• one visible <h1> per page in most cases
• headings describe sections, not font size
• use <button> for actions, <a> for navigation
• every form control has a <label>
• images have meaningful alt or empty alt=""
• prefer semantic elements over extra <div> wrappers
• validate important pages before deploy

Document these in a short CONTRIBUTING.md or team wiki if you collaborate.

Comments

Good comments:

<!-- Site header: logo and main navigation -->
<header>...</header>
 
<!-- Pricing comparison table -->
<section id="comparison">...</section>

Bad comments:

<!-- div -->
<div class="wrapper">...</div>

Do not put secrets in comments. HTML is public.

.gitignore for Static Projects

Typical ignores:

.DS_Store
Thumbs.db
node_modules/
dist/
.env

If you add Node for Prettier or a build step, ignore node_modules/. Never commit .env with API keys.

Mini Exercise

Take your small static site from chapter 35:

1. Rename files to lowercase hyphen style if needed.
2. Move CSS, JS, and images into folders.
3. Fix all relative paths.
4. Run Prettier on every HTML file.
5. Validate one page with the W3C validator.

FAQ

Should I use one CSS file or many?

Start with one styles.css. Split when the project grows or pages need very different styles.

Is assets/ required?

No. It is a useful convention for PDFs, fonts, and downloads separate from page images.

Can HTML files live only in subfolders?

Yes, but root index.html is the usual entry point for hosts and users.

Does Prettier fix invalid HTML?

No. It formats valid or mostly valid markup. Run a validator for correctness.

What comes next?

Static site deployment — serve files over HTTP and publish to a host.