Suggestions for web coding in 2017

Posted: , Updated: Category: Computers

I wanted to write a theme for Hugo. There weren’t any themes suitable for a large, thousand-page software documentation website.

Good news! I’ve fixed that: LiaungYip/plain-docs.

To write plain-docs, I had to re-learn the modern versions of HTML, CSS, and Javascript. The situation is much better than the last time I did serious web design!

The following are some best practices / suggestions for starting a simple web design project.

HTML5 starting point

Start your HTML with a basic skeleton (modified from The Real HTML 5 Boilerplate by Harry Roberts):

<!DOCTYPE html>
<!-- ^ Tells the browser this is HTML5.
Avoids triggering quirks mode, which breaks everything. -->
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>HTML5 boilerplate – all you really need…</title>
    <!-- html5shiv makes HTML5 work in old Internet Explorers -->
    <!--[if IE]>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
    <![endif]-->
</head>

<body>
    <h1>HTML5 boilerplate</h1>
</body>
</html>

Don’t use the html5-boilerplate project. As Harry Roberts comments, it includes a lot of things you don’t necessarily need.

Pure CSS

Yahoo’s Pure CSS is a great little module.

  • It’s a “CSS reset”, which makes your website look (mostly) the same in all browsers.
  • It applies a sensible set of default styles.
  • It gives you easy ways to solve common problems like “lay out my content into three columns”, or “make a horizontal menu”. (Back in 2006, these were topics for entire articles on A List Apart!)
  • It’s tiny (4 kB).

The Pure CSS: Get Started page covers what you need to know.

Javascript tricks

jQuery is all the rage these days.

You don’t necessarily need it - especially if you only need to do one or two simple things.

See: Pure Javascript Show/Hide Toggle for something you can do in 233 bytes of pure JS, without pulling in the 80kB jQuery library.

Use CDNs

If you need external resources like Pure CSS or jQuery, it’s better to link to a copy on a content delivery network, rather than hosting a copy yourself.

  • CDNs are faster than your web hosting.
  • You don’t have to pay for bandwidth from a CDN.
  • If a visitor already has https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js in their cache, from visiting some other website that also used it, they won’t need to download it again.

The most popular libraries are available from Google’s CDN. The rest are available from cdnjs or unpkg.

Footnotes

2006 was a hard time to be a web designer. Fire hadn’t been invented, dinosaurs roamed the earth, and:

  • Internet Explorer 6 stalked the land.
  • XHTML 1.0 Strict and CSS2 were the new hotness.
  • Making a box with rounded corners required -moz-border-radius or -webkit-border-radius or awful hacks with background images, or all three of those at once.
  • Internet Explorer 8’s compliance with the CSS Acid Test (or lack thereof) was still a matter of interest.
  • There were no CSS frameworks. You had to read A List Apart and implement your own multi-column layout from scratch.
  • GitHub didn’t exist.
  • CDNs didn’t exist.
  • http:// was the default, https:// was only for people who could afford certificates. (Praise unto Cloudflare and Let’s Encrypt!)
  • I’d never written Javascript ever.