html5-boilerplate Documentation

A professional front-end template for building fast, robust, and adaptable web apps or sites.

57,584 stars JavaScript JavaScript 1 file · ~6,054 tokens #best-practices#css#html#html5#html5-boilerplate#javascript#robust
RAW Doc

File: README.md

[HTML5 Boilerplate](https://html5boilerplate.com/)




HTML5 Boilerplate is a professional front-end template for building
fast, robust, and adaptable web apps or sites.

This project is the product of over 10 years of iterative development and
community knowledge. It does not impose a specific development
philosophy or framework, so you're free to architect your code in the
way that you want.

About This Repository

This repository is where HTML5-Boilerplate is authored. Some of the tools,
files and processes that you see here are solely for the production of
HTML5 Boilerplate and are not part of HTML5 Boilerplate. For one example, the
gulpfile.mjs
script is used to build the project. It's not part of the project itself.

The project we publish is represented by the contents of the /dist/
folder. Everything else in this repository is used to author the project.

Think of it this way, in the same way that you don't clone vuejs/core
to create a Vue.js app, you don't need to clone this repository to start a new
site or app based on HTML5 Boilerplate.

So, if you're looking for a quick start template to build a website or
application, look at the options in the
Quick Start section of this document.

If you want to help us improve HTML5 Boilerplate then you can start with the documentation here, which includes steps to clone this repo in order to get it set up for development.

Quick Start

Choose one of the following options:

  • Using the create-html5-boilerplate
    script, instantly fetch the latest npm published package (or any version
    available on npm) with npx, npm init or yarn create without having to
    install any dependencies. Running the following npx command installs the
    latest version into a folder called new-site

    bash
    npx create-html5-boilerplate new-site
cd new-site
npm install
npm run start

  • Using our new Template Repository
    create a new GitHub repository based on the latest code from the main branch of HTML5
    Boilerplate.

  • Install with npm: npm install html5-boilerplate
    or yarn: yarn add html5-boilerplate. The resulting
    node_modules/html5-boilerplate/dist folder represents the latest version of
    the project for end users. Depending on what you want to use and how you want
    to use it, you may have to copy and paste the contents of that folder into
    your project directory.

  • Download the latest stable release from
    here. This zip file is a
    snapshot of the dist folder. On Windows, Mac and from the file manager on
    Linux unzipping this folder will output to a folder named something like
    html5-boilerplate_v9.0.0. From the command-line, you will need to create a
    folder and unzip the contents into that folder.

    bash
    mkdir html5-boilerplate
unzip html5-boilerplate*.zip -d html5-boilerplate

Features

  • A finely-tuned starter template: Reap the benefits of 10 years of analysis,
    research and experimentation by over 200 contributors.
  • Designed with progressive enhancement in mind.
  • Includes:
    • Placeholder Open Graph elements and attributes.
    • An example package.json file with WebPack commands
      built in to jumpstart application development.
    • Placeholder CSS Media Queries.
    • Useful CSS helper classes.
    • Default print styles, performance optimized.
    • "Delete-key friendly." Easy to strip out parts you don't need.
    • Extensive documentation.

Browser Support

HTML5-Boilerplate supports the latest, stable releases of all major browsers.

Check the default configuration from Browserslist
for more details on browsers and versions covered.

Documentation

Take a look at the documentation table of contents. This
documentation is bundled with the project which makes it available for offline
reading and provides a useful starting point for any documentation you want to
write about your project.

Contributing

Hundreds of developers have helped to make the HTML5 Boilerplate. Anyone is
welcome to contribute. However, if you decide to get
involved, please take a moment to review the guidelines:

License

The code is available under the MIT license.

File: docs/about-this-repo.md

About This Repo

This document outlines the configuration of this repo as well as the basic
process we use to manage the project. As GitHub has matured as a platform
and HTML5 Boilerplate has matured as a project there are a lot of lessons
to be learned from the way we run the show here.

GitHub configuration

This section will go through the way we configure the repo in GitHub.
Open source projects get the full power of the platform and as a project
we like to experiment with new GitHub features. Our current configuration
might help you figure out some things you want to do in your own projects.

General Configuration

This section outlines the basic configuration options we use.

  • We have a stub of a Wiki still, so we have wikis turned on. The most
    interesting page that remains is a history of the project written several
    years ago.
  • We use the Issues feature heavily. We don't yet have Issue Templates set
    up, but we do have adding them as an issue, so we'll take advantage of them
    at some point.
  • Discussions are enabled, but they haven't been very useful so far.

Pull Requests

The most visible portion of our configuration is the way we handle pull
requests. At the most basic level, we require pull requests to add code
to the repo and require a review to merge code. In addition we run several
code quality checks on every pull request to make sure we're not introducing
anything we don't want into the codebase.

We take advantage of the "draft" feature for PRs. This way we have visibility
throughout the life of the PR.

Let's take a look at how we configure our main branch.

`main`

main is the default branch and is our only protected branch. We use feature
branches to add features and/or fix issues in the codebase. Other project
configurations might require a long-running, similarly protected, development
branch but for us the single protected main branch is enough for our
purposes.

Our branch protection rules are as follows:

  • We require a pull request (PR) with one approving reviewer to merge code
  • In addition to the PR and approving reviewer, we require two status checks
    to pass before code can be merged
    _ Build with Node 22
    _ Build with Node 24
  • We allow force pushes for project admins. While force pushes can create
    some head scratching moments for people who have cloned the repo and update
    before and after the force push, the ability to clean up the HEAD of a
    public branch like this in an emergency is useful.

GitHub Actions and Other Checks That Run on `main`

  • We run a simple build status check. This is the most basic test you can run
    and is absolutely vital. If you can't build your project you're in trouble.
    Currently we're testing against Node 22 and 24.
  • We take advantage of our access to CodeQL analysis Free for research and
    open source don't you know :) We don't have a ton of surface area to cover,
    but it's nice to have this powerful code scanning tool available to us.
  • We run a dependency review scan to see if any newly added dependencies add
    known security flaws. This is important for even us, but for a project that
    uses a larger number of third party dependencies, this sort of check is vital.
  • We also run a CodeQL scans to check for security issues and problems.
  • We push any changes to main to our HTML5-Boilerplate Template Repo

Since we've talked about some of our Actions, let's look at the full configuration
of our .github folder.

.github Folder

  • workflows
    • build-dist.yml is currently broken. We can't push to main without a
      code review, so this task is blocked. What I would like, (are you there,
      GitHub, it's me, Rob) is to allow Actions to bypass branch protection
      rules. I think we'll have to basically write a mini-bot that opens a PR
      whenever there are changes to main and then pushes to the same branch
      until the PR is closed. In some ways that will be better as it will be less
      noisy in terms of bot pushes to main.
    • codeql-analysis.yml controls our CodeQL action. We use the defaults. If
      you're building something with more JavaScript footprint, you can tweak
      the settings for this job.
    • dependency-review.yml does what it says on the tin- it tests newly
      introduced dependencies for vulnerabilities.
    • publish.yml is the action that publishes all the various versions of
      the project. When we create a new tag and push it to GitHub, this script
      publishes our npm package and creates a GitHub release and attaches a zip
      file of our dist folder.
    • push-to-template.yml pushes the HEAD of main to our template repo
    • spellcheck.yml automatically checks markdown files for typos with cSpell.
    • test.yml runs our test suite on Ubuntu.
    • test-windows.yml runs our test suite on Windows.
  • CODE_OF_CONDUCT.md is our Code of Conduct, based on
    Contributor Covenant.
  • CONTRIBUTING.md contains our contribution guidelines.
  • ISSUE_TEMPLATE.md is our new issue boilerplate.
  • PULL_REQUEST_TEMPLATE.md is our new PR boilerplate.
  • SUPPORT.md points people to different (non-HTML5-Boilerplate) support
    resources
  • dependabot.yml is our Dependabot configuration. We do npm, monthly on
    two separate package.json files, one in src and one in project root.

That covers most of the interesting GitHub features and functionality that we
use. We're going to continue to keep this document up to date as we change
things or new GitHub features.

File: docs/css.md

HTML5 Boilerplate homepage | Documentation
table of contents

The CSS

HTML5 Boilerplate's CSS includes:

style.css

Several base styles are included. These styles:

  • provide basic typography settings that improve text readability
  • protect against unwanted text-shadow during text highlighting
  • tweak the default alignment of some elements (e.g.: img, video,
    fieldset, textarea)
  • style the prompt that is displayed to users using an outdated browser
  • and more...

These styles are included in
style.css.

File: docs/faq.md

HTML5 Boilerplate homepage | Documentation
table of contents

Frequently asked questions

Do I need to upgrade my site each time a new version of HTML5 Boilerplate is released?

No, just as you don't normally replace the foundation of a house once it was
built. However, there is nothing stopping you from trying to work in the latest
changes, but you'll have to assess the costs/benefits of doing so.

Where can I get help with support questions?

Please ask for help on
Stack Overflow.

File: docs/js.md

HTML5 Boilerplate homepage | Documentation
table of contents

The JavaScript

Information about the default JavaScript included in the project.

app.js

This file can be used to contain or reference your site/app JavaScript code. If
you're working on something more advanced you might replace this file entirely.
That's cool.

vendor

This directory can be used to contain all third-party library code.

File: docs/misc.md

HTML5 Boilerplate homepage | Documentation
table of contents

Miscellaneous

--

.gitignore

HTML5 Boilerplate includes a basic project-level .gitignore. This should
primarily be used to avoid certain project-level files and directories from
being kept under source control. Different development-environments will
benefit from different collections of ignores.

OS-specific and editor-specific files should be ignored using a "global
ignore" that applies to all repositories on your system.

For example, add the following to your ~/.gitconfig, where the .gitignore
in your HOME directory contains the files and directories you'd like to
globally ignore:

gitignore
[core]
    excludesfile = ~/.gitignore

.editorconfig

The .editorconfig file is provided in order to encourage and help you and
your team define and maintain consistent coding styles between different
editors and IDEs.

By default, .editorconfig includes some basic
properties that reflect the
coding styles from the files provided by default, but you can easily change
them to better suit your needs.

In order for your editor/IDE to apply the
properties from the
.editorconfig file, you may need to install a
plugin.

N.B. If you aren't using the server configurations provided by HTML5
Boilerplate, we highly encourage you to configure your server to block
access to .editorconfig files, as they can disclose sensitive information!

For more details, please refer to the EditorConfig
project.

robots.txt

The robots.txt file is used to give instructions to web robots on what can
be crawled from the website.

By default, the file provided by this project includes the next two lines:

  • User-agent: * - the following rules apply to all web robots
  • Disallow: - everything on the website is allowed to be crawled

If you want to disallow certain pages you will need to specify the path in a
Disallow directive (e.g.: Disallow: /path) or, if you want to disallow
crawling of all content, use Disallow: /.

The /robots.txt file is not intended for access control, so don't try to
use it as such. Think of it as a "No Entry" sign, rather than a locked door.
URLs disallowed by the robots.txt file might still be indexed without being
crawled, and the content from within the robots.txt file can be viewed by
anyone, potentially disclosing the location of your private content! So, if
you want to block access to private content, use proper authentication instead.

For more information about robots.txt, please see:

package.json

package.json is used to define attributes of your site or application for
use in modern JavaScript development. The full documentation is available
if you're interested. The fields we provide are as follows:

  • title - the title of your project. If you expect to publish your application
    to npm, then the name needs to follow certain guidelines
    and be unique.

  • version - indicates the version of your site application using semantic
    versioning (SemVer)

  • description - describes your site.

  • scripts - is a JavaScript object containing commands that can be run in a
    node environment. There are many built-in keys
    related to the package lifecycle that node understands automatically. You can
    also define custom scripts for use with your application development. We
    provide three custom scripts that work with webpack to get you up and running
    quickly with a bundler for your assets and a simple development server.

    • start serves your index.html with a simple development server

  • keywords - an array of keywords used to discover your app in the npm
    registry

  • author - defines the author of a package. There is also an alternative
    contributors
    field if there's more than one author.

  • license - the license for your application. Must conform to
    specific rules

  • devDependencies - development dependencies for your package. In our case
    we have several dependencies used by webpack, which we use as a simple development server.

File: docs/TOC.md

HTML5 Boilerplate homepage

Getting started

  • Usage — Overview of the project contents.
  • FAQ — Frequently asked questions along with their answers.

HTML5 Boilerplate core

Development

The H5BP organization maintains several projects that
complement HTML5 Boilerplate, projects that can help you improve different
aspects of your website/web app (e.g.: the performance, security, etc.).

File: docs/usage.md

HTML5 Boilerplate homepage | Documentation
table of contents

Usage

The most basic usage of HTML5 Boilerplate is to create a static site or simple
app. Once you've downloaded or cloned the project, that process looks something
like this:

  1. Set up the basic structure of the site.
  2. Add some content, style, and functionality.
  3. Run your site locally to see how it looks.
  4. Deploy your site.

Cool, right? It is. That said, the smart defaults, baseline elements, default
attribute values and various other utilities that HTML5 Boilerplate offers can
serve as the foundation for whatever you're interested in building.

Even the basic use-case of a simple static site can be enhanced by manipulating
the code through an automated build process. Moving up in complexity HTML5
Boilerplate can be integrated with whatever front-end framework, CMS or
e-commerce platform you're working with. Mix-and-match to your heart's content.
Use what you need (toss it in a blender if you need to) and discard the rest.
HTML5 Boilerplate is a starting point, not a destination.

Basic structure

A basic HTML5 Boilerplate site initially looks something like this:

text
.
├── css
│   └── style.css
├── doc
├── img
├── js
│   ├── app.js
    └── vendor
├── .editorconfig
├── 404.html
├── favicon.ico
├── icon.png
├── icon.svg
├── index.html
├── package.json
├── robots.txt
├── site.webmanifest
└── webpack.common.js
└── webpack.config.dev.js
└── webpack.config.prod.js

What follows is a general overview of each major part and how to use them.

css

This directory should contain all your project's CSS files. It includes some
initial CSS to help get you started from a solid foundation. About the
CSS.

doc

This directory contains all the HTML5 Boilerplate documentation. You can use it
as the location and basis for your own project's documentation.

js

This directory should contain all your project's JS files. Libraries, plugins,
and custom code can all be included here. It includes some initial JS to help
get you started. About the JavaScript.

404.html

A helpful custom 404 to get you started.

.editorconfig

The .editorconfig file is provided in order to encourage and help you and your
team to maintain consistent coding styles between different editors and IDEs.
Read more about the .editorconfig file.

index.html

This is the default HTML skeleton that should form the basis of all pages on
your site. If you are using a server-side templating framework, then you will
need to integrate this starting HTML with your setup.

Make sure that you update the URLs for the referenced CSS and JavaScript if you
modify the directory structure at all.

package.json

Edit this file to describe your application, add dependencies, scripts and
other properties related to node based development and the npm registry

robots.txt

Edit this file to include any pages you need hidden from search engines.

Icons

Replace the default favicon.ico and Apple Touch Icon with your own.

If you want to use different Apple Touch Icons for different resolutions please
refer to the according documentation.

Webpack

The project contains a simple webpack configuration.

To get started developing a site with a development server, run the following
commands from within the /dist/ folder in the project's repo or within the
root folder of the dowloaded project files, the folder created by npm install
or the project folder created by running create-html5-boilerplate

text
npm install
npm run start

This will start a Webpack development server with hot reloading of edited files.

To package a site for production run

text
npm run build

This command will bundle up the site's JavaScript and copy over static assets to
the newly created dist folder.

There are three files:

webpack.common.js

Both the production and development scripts inherit from this common script.

webpack.config.dev.js

This development configuration defines the behavior of development server.

webpack.config.prod.js

This production configuration defines the behavior of the production build.

It copies the following files and folders to the dist folder:

  • css
  • img
  • js/vendor
  • 404.html
  • favicon.ico
  • icon.png
  • icon.svg
  • index.html
  • robots.txt
  • site.webmanifest

js/vendor is copied over in order to allow you to use unprocessed JS files
in addition to the files bundled based on the project's entry point app.js.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#best-practices Browse best-practices catalog → #css Browse css catalog → #html Browse html catalog → #html5 Browse html5 catalog → #html5-boilerplate Browse html5-boilerplate catalog → #javascript Browse javascript catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →