Notes on writing modern HTML/CSS

Modern web development has become very complex. I think it's nice to know how to write decent HTML and CSS using nothing but a text editor.

An HTML template

<!DOCTYPE html>  <!-- This file is an HTML document... -->
<html lang="en"> <!-- in English. -->
  <head>
    <!-- This line helps characters like π and é show up correctly: -->
    <meta charset="UTF-8">
    <!-- This line tells phone browsers to render the site at phone size: -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!-- This sentence shows up as a summary of your page in search engines: -->
    <meta name="description" content="Lorem ipsum...">
    <!-- This sentence shows up in a Discord/Slack/etc. link preview: -->
    <meta property="og:description" content="Dolor sit amet...">
    <!-- This shows up as the name of the tab/bookmark: -->
    <title>Writing modern HTML by hand</title>
    <!-- This links a CSS stylesheet to use: -->
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <article>
      <h1>Writing modern HTML by hand</h1>
      ...
    </article>
  </body>
</html>

Set a maximum width

I think one of the easiest ways to make a website more readable on desktop is to set a maximum width on the main content. Otherwise, you end up with paragraphs that are so long on a wide monitor that it's hard to scan with your eyes from the end of one line to the start of the next. You can add some code like this to your CSS:

* { box-sizing: border-box; }

article > *:not(.full) {
  max-width: 40rem;
  margin-left: auto;
  margin-right: auto;
}

Specifying the max-width in this slightly unusual way allows us to still have full page width content like this <hr class="full" /> below:

Accessibility

There are some little things you can do to make your page more accessible (for example, to visually impaired readers).

Provide alt text

When adding an image, don't forget to set the alt attribute. Just write how you'd describe the image to your friend over the phone.

A black-and-white photo of three pinecones. — An example image from picsum.photos to demonstrate the idea.
(This caption isn't the alt text!)

Use semantic elements

For example, use <h2> to mark a second-level heading, not just to "make big text". This way, software like search engines and screen readers can make sense of the structure of your site.

Support dark mode

I wrote a tutorial about this, but if you don't want to bother with JavaScript, there's an even simpler CSS-only solution:

:root {
  color-scheme: light dark;
  --text:   light-dark(#222222, #eeeeee);
  --bg:     light-dark(#f6f6f6, #333333);
  --accent: light-dark(#ff6600, #ff9955);
}

body {
  font-family: system-ui;
  color: var(--text);
  background: var(--bg);
}