HTML Basics

Writing and Running Your First HTML Page

Set up a folder, save a real .html file, open it in a browser and understand the difference between opening a file and serving it. The workflow every later note assumes.

On this page (12)

Concept

HTML needs no compiler, no build tool and no installation. A plain text file with an .html extension and a browser are the whole toolchain. What does need attention is the folder layout and the difference between opening a file from disk and serving it over HTTP, because a few features fail silently in the first case.

Set up the folder

Start with a structure you will not have to rearrange later:

first-site/
  index.html
  about.html
  styles/
    site.css
  scripts/
    site.js
  images/
    portrait.jpg

index.html is special by convention: web servers serve it automatically when a visitor requests a directory, so example.com/ and example.com/index.html are the same page. Every home page should carry that name.

File naming rules

Lower case only. Many servers are case sensitive, so About.html and about.html are different files there and identical on your Windows machine. This is a classic first deployment failure.
Hyphens instead of spaces. contact-us.html, never contact us.html, because a space becomes %20 in the URL.
No accented characters, and nothing outside letters, digits and hyphens.
Keep the .html extension. Windows hides known extensions by default, which is how people end up with index.html.txt and a browser that shows them source code.

Example

Save this as index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My first page</title>
</head>
<body>
  <h1>Hello from a file on my own machine</h1>
  <p>This page took no tools to build. It is text in a file.</p>
  <p>Next stop: <a href="about.html">the about page</a>.</p>
</body>
</html>

Opening it

Two ways, and they are not equivalent.

Straight from disk

Double click the file, or press Ctrl and O in the browser. The address bar shows a file:// URL. This is enough for markup, CSS, images and links between local pages.

Through a local server

The address bar shows http://localhost and something behaves correctly that did not before. Several things only work over HTTP:

Root relative paths such as /styles/site.css. Over file:// the leading slash means the root of your hard disk.
JavaScript modules, fetch and anything else governed by cross origin rules.
Service workers, the clipboard API, geolocation and any other feature that requires a secure context.
The directory index, so / resolves to index.html.

Any of these will start a server in the current folder:

# Python, already present on most systems
python -m http.server 8000

# Node
npx serve

# PHP
php -S localhost:8000

Then open http://localhost:8000. In an editor, a live preview extension does the same thing and reloads on save.

Explanation

The browser reads the file, meets the doctype and switches to standards mode, reads the encoding, builds the DOM from the tags, applies its own default stylesheet, and paints. The title becomes the tab label. The link to about.html is a relative path, so the browser resolves it against the folder the current page came from - which is why the two files must sit side by side.

Important rules

Save as plain text with UTF-8 encoding. A word processor will insert formatting and produce a file the browser cannot parse.
Reload after every save. The change is on disk, not in the open tab.
If a change refuses to appear, force a reload with Ctrl Shift R; the browser is serving a cached copy.
Relative paths are resolved against the current document, so moving a file breaks every link into and out of it.

Common mistakes

Saving as .txt and seeing raw markup in the browser instead of a page.
Writing the page in a word processor. Straight quotes become curly quotes, and <p class="x"> stops working.
Using a backslash in a path. URLs use forward slashes on every platform, including Windows.
Mixing case between the file name and the link. It works locally and fails on the server.
Testing only from file://, then finding half the page broken once it is deployed.

Best practices

Work through a local server from day one. It removes a whole class of problems that only appear at deployment.
Create the folders before the files. Retrofitting a structure means rewriting every path.
Put the project under version control immediately, even for a single page.
Keep a starter file with the head already filled in and copy it for each new page.
Test in two browsers regularly rather than once at the end.

Practice

Build the folder above, write index.html and about.html, and link them in both directions.
Link the stylesheet as /styles/site.css and open the page from disk. Does it apply? Now serve it over HTTP and try again. Explain the difference.
Rename about.html to About.html, leave the link lower case, and note that it still works locally. Why is that dangerous?
Start a local server, open the folder as http://localhost:8000/ and confirm which file the browser chose without being told.

Topics #Beginner #HTML #Projects

Written by Lorens Mishra

Software Engineer Notes Management System Administrator

Continue reading

All HTML notes →

HTML

Discussion

0 comments

No comments yet. Be the first to say something.