## File: README.md

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

[](https://github.com/h5bp/html5-boilerplate/actions?query=workflow%3A%22Build+status%22+branch%3Amain)
[](https://github.com/h5bp/html5-boilerplate/blob/main/LICENSE.txt)
[](https://www.npmjs.com/package/html5-boilerplate)
[](https://github.com/h5bp/html5-boilerplate)

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.

- [Homepage](https://html5boilerplate.com/)
- [Source Code](https://github.com/h5bp/html5-boilerplate)

## 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](https://github.com/h5bp/html5-boilerplate/blob/main/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](https://github.com/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](https://github.com/h5bp/html5-boilerplate#quick-start) section of this document.

If you want to help us _improve_ HTML5 Boilerplate then you can start with the documentation [here](.github/CONTRIBUTING.md), 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](https://github.com/h5bp/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](https://github.com/h5bp/html5-boilerplate-template)
  create a new GitHub repository based on the latest code from the main branch of HTML5
  Boilerplate.

- Install with [npm](https://www.npmjs.com/): `npm install html5-boilerplate`
  or [yarn](https://yarnpkg.com/): `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](https://github.com/h5bp/html5-boilerplate/releases/download/v9.0.0/html5-boilerplate_v9.0.0.zip). 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](https://webpack.js.org/) 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](https://browsersl.ist/#q=defaults)
for more details on browsers and versions covered.

## Documentation

Take a look at the [documentation table of contents](docs/TOC.md). 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](.github/CONTRIBUTING.md). However, if you decide to get
involved, please take a moment to review the [guidelines](.github/CONTRIBUTING.md):

- [Bug reports](.github/CONTRIBUTING.md#bugs)
- [Feature requests](.github/CONTRIBUTING.md#features)
- [Pull requests](.github/CONTRIBUTING.md#pull-requests)

## License

The code is available under the [MIT license](LICENSE.txt).

---

## 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](https://github.com/h5bp/html5-boilerplate-template)

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.](https://www.contributor-covenant.org/)
- `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](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)

# The CSS

HTML5 Boilerplate's CSS includes:

- [style.css](#stylecss)

## 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](https://github.com/h5bp/html5-boilerplate/blob/main/dist/css/style.css).

---

## File: docs/faq.md

[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)

# 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](https://stackoverflow.com/questions/tagged/html5boilerplate).

---

## File: docs/js.md

[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)

# 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](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)

# Miscellaneous

- [.gitignore](#gitignore)
- [.editorconfig](#editorconfig)
- [robots.txt](#robotstxt)
- [package.json](#packagejson)

--

## .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
```

- More on global ignores: [https://help.github.com/articles/ignoring-files/](https://help.github.com/en/github/using-git/ignoring-files)
- Comprehensive set of ignores on GitHub: https://github.com/github/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](https://editorconfig.org/#supported-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](https://editorconfig.org/#supported-properties) from the
`.editorconfig` file, you may need to [install a
plugin](https://editorconfig.org/#download).

**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](https://editorconfig.org/).

## 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:

- [robotstxt.org](https://www.robotstxt.org/)
- [How Google handles the `robots.txt` file](https://developers.google.com/search/reference/robots_txt)

## 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](https://docs.npmjs.com/files/package.json)
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](https://docs.npmjs.com/files/package.json#name)
  and be unique.
- `version` - indicates the version of your site application using semantic
  versioning ([SemVer](https://semver.org/))
- `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](https://docs.npmjs.com/misc/scripts)
  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](https://docs.npmjs.com/files/package.json#people-fields-author-contributors)
  field if there's more than one author.
- `license` - the license for your application. Must conform to
  [specific rules](https://docs.npmjs.com/files/package.json#license)
- `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](https://html5boilerplate.com/)

## Getting started

- [Usage](usage.md) — Overview of the project contents.
- [FAQ](faq.md) — Frequently asked questions along with their answers.

## HTML5 Boilerplate core

- [HTML](html.md) — Guide to the default HTML.
- [CSS](css.md) — Guide to the default CSS.
- [JavaScript](js.md) — Guide to the default JavaScript.
- [Everything else](misc.md).

## Development

- [Extending and customizing HTML5 Boilerplate](extend.md) — Going further with
  the boilerplate.

## Related projects

The [H5BP organization](https://github.com/h5bp) 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.).

- [Server Configs](https://github.com/h5bp/server-configs) — Fast and smart
  configurations for web servers such as Apache and Nginx.
  - [Apache](https://github.com/h5bp/server-configs-apache)
  - [Google App Engine (GAE)](https://github.com/h5bp/server-configs-gae)
  - [Internet Information Services
    (IIS)](https://github.com/h5bp/server-configs-iis)
  - [lighttpd](https://github.com/h5bp/server-configs-lighttpd)
  - [Nginx](https://github.com/h5bp/server-configs-nginx)
  - [Node.js](https://github.com/h5bp/server-configs-node)
- [Front-end Developer Interview Questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions)
- [create-html5-boilerplate](https://github.com/h5bp/create-html5-boilerplate) — Quick start HTML5 Boilerplate development.
- [main.css](https://github.com/h5bp/main.css) — the main.css file included (as style.css) with HTML5 Boilerplate.

---

## File: docs/usage.md

[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)

# 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:

```
.
├── 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](css.md).

### 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](js.md).

### 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](misc.md#editorconfig).

### 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](extend.md#apple-touch-icons).

### Webpack

The project contains a simple [webpack](https://webpack.js.org/) 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](https://github.com/h5bp/create-html5-boilerplate)

```
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

```
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.`