Constructing a Website

Jump to Examples

This site started as a few HTML files on my NAS, and it is still basically that – just more files. Along the way I learned that the hard part of a website is not making it look nice. The hard part is everything around it: the domain, DNS, certificates, and making sure that somebody (or Google) can actually find what you wrote. This note is about that part.

A Bit of Web History

In 1989 Tim Berners-Lee at CERN wrote a proposal for linking documents between computers. By the end of 1990 he had the three pieces that still run the web today: HTML to write a page, HTTP to send it, and URLs to say where it is. The first website, info.cern.ch, explained what the web is – and you can still open it.

Names on the Internet are older. Before 1983 every computer kept one file, HOSTS.TXT, with the names and addresses of all the others, and it was copied around by hand. Paul Mockapetris designed the Domain Name System in 1983 to replace it. A funny leftover: Windows and Linux still have a hosts file, and it still wins over DNS.

For a long time most of the web was not encrypted, because certificates cost money and were a pain to set up. That changed when Let's Encrypt started giving them away for free and automatically at the end of 2015. Today a page without HTTPS gets a warning in every browser.

What Happens When You Type an Address

Say you type jpnas.net and press Enter. In less than a second:

1. DNS: the browser asks "what is the IP address of jpnas.net?" The question goes to your router or your DNS server, and if they don't know, down the chain from the root servers to the servers responsible for .net and then for jpnas.net. The answer is cached so the next time is instant.
2. Connection: the browser opens a TCP connection to that address on port 443 (more about ports in Computer Networks).
3. TLS: the server shows its certificate, the browser checks that it is really for jpnas.net and signed by somebody it trusts, and both sides agree on a key. From here on everything is encrypted.
4. HTTP: the browser asks GET /, and the server answers with 200 OK and the HTML.
5. The page: the browser reads the HTML, finds the CSS, JavaScript and images, and asks for each of them the same way.

You can watch all of this: press F12 in the browser and open the Network tab before loading a page.

Static or Dynamic?

A dynamic site (WordPress, an e-shop) builds every page when somebody asks for it, from a database and PHP or similar. That is great for comments, users and shopping carts – and it also means a server program that has to be updated, a database to back up, and a login page that bots try to break into all day long.

A static site is just files. The server only sends them. Nothing to hack, nothing to update, it is very fast and can run on almost anything – a NAS, a Raspberry Pi or a free hosting service. For a personal site with notes it is usually all you need. Tools like Hugo make static sites from Markdown; I did it my own way (Example 2).

Making a Site Findable

This is the part I learned only recently. My Digital Garden draws the notes with JavaScript from .js files – nice for search and filters, but Google sees an almost empty page. What helps:

• Real HTML pages that contain the text without JavaScript.
• A good <title> and <meta name="description"> on every page – that's what you see in the search results.
• <link rel="canonical"> – tells Google which address is the "official" one when the same page can be opened in several ways.
• Open Graph tags (og:title, og:description) – they make the preview when somebody shares a link on WhatsApp, Viber or Facebook.
• robots.txt – rules for crawlers, invented by Martijn Koster in 1994. Mine just allows everything and points to the sitemap.
• sitemap.xml – a list of all pages with the date of the last change. Google introduced it in 2005, the other search engines joined soon after.
• Google Search Console – add the site, submit the sitemap, and see what Google found and what it didn't like.

Examples

Example 1: The Smallest Proper Page

<!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>
  <meta name="description" content="One sentence about what is on this page.">
  <link rel="canonical" href="https://example.com/">
</head>
<body>
  <h1>Hello</h1>
  <p>This is a real web page.</p>
</body>
</html>

Save it as index.html and open it in a browser – that's a website. The viewport line is the one people forget, and without it the page looks tiny on a phone.

Example 2: My Notes as Static Pages

I write every note as one .js file (this one too). A small Python script, build_static.py, reads all of them and writes:

• one HTML page per note in digital-garden/articles/, with title, description, canonical, Open Graph and structured data for Google,
• one page per resource section in digital-resources/topics/,
• a fresh sitemap.xml.

The script needs only Python, no extra packages, and it writes a file only when something really changed, so the NAS doesn't sync everything every time. I run it with a double-click on a .bat file after I change a note, then copy the changed files to the server. The interactive garden stays as it is; the static pages are for Google and for people with JavaScript turned off. Each of them has a button back to the interactive version.

Example 3: Domain, DNS and HTTPS on Your Own Server

Coming soon. How to point a domain to a home server (A and AAAA records, what to do with a changing home IP), and how to get a free certificate automatically with Caddy or the reverse proxy on a Synology NAS.

Keeping It Safe

• HTTPS everywhere, also for a "simple" site. It protects visitors from changed content on public Wi-Fi.
• Don't publish more than you mean to. Folders with backups, .git or old test files on a web server are found by bots within days.
• If you host at home, open only ports 80 and 443 to one machine, keep it updated, and keep it separate from the rest of the network if you can (see Security Considerations).
• Back up the source, not only the published site – in my case the .js notes and the scripts.

A Few More Thoughts

What I like about the web is that the basics haven't changed since 1991. A text file with some tags, put on a server, is still a web page that every browser in the world can open. You don't need a framework, a subscription or a platform to have your own place on the Internet – a few files and a domain are enough, and they will still work in twenty years.