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.
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.
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.
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.
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.jsin their cache, from visiting some other website that also used it, they won’t need to download it again.
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
-webkit-border-radiusor 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!)