github/html5-boilerplate
1
1
Fork 0
mirror of https://github.com/h5bp/html5-boilerplate.git synced 2026-01-08 22:28:10 -05:00
Code Issues Packages Projects Releases Wiki Activity

Closes #2716 (#2723)

Browse Source
This commit is contained in:
Rob Larsen
2022-03-09 15:05:20 -05:00
committed by GitHub
parent 5df2aee315
commit 770a2b5fff
8 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/TOC.md Normal file
View File

@@ -0,0 +1,37 @@
[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

44
docs/css.md Normal file
View File

@@ -0,0 +1,44 @@
[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)
# The CSS
HTML5 Boilerplate's CSS includes:
* [Normalize.css](#normalizecss)
* [style.css](#stylecss)
## Normalize.css
In order to make browsers render all elements more consistently and in line with
modern standards, we include Normalize.css — a modern, HTML5-ready alternative
to CSS resets.
As opposed to CSS resets, Normalize.css:
* targets only the styles that need normalizing
* preserves useful browser defaults rather than erasing them
* corrects bugs and common browser inconsistencies
* improves usability with subtle improvements
* doesn't clutter the debugging tools
* has better documentation
For more information about Normalize.css, please refer to its [project
page](https://necolas.github.io/normalize.css/).
## style.css
Several base styles are included that build upon `Normalize.css`. 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)
using [main.css](https://github.com/h5bp/main.css) project.
See the main.css [documentation](https://github.com/h5bp/main.css/blob/main/README.md#features)
for a full discussion of these styles.

480
docs/extend.md Normal file
View File

@@ -0,0 +1,480 @@
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
table of contents](TOC.md)
# Extend and customise HTML5 Boilerplate
Here is some useful advice for how you can make your project with HTML5
Boilerplate even better. We don't want to include it all by default, as not
everything fits with everyone's needs.
* [App Stores](#app-stores)
* [DNS prefetching](#dns-prefetching)
* [Internet Explorer](#internet-explorer)
* [Miscellaneous](#miscellaneous)
* [News Feeds](#news-feeds)
* [Search](#search)
* [Social Networks](#social-networks)
* [URLs](#urls)
* [Web Apps](#web-apps)
* [humans.txt](#humanstxt)
* [security.txt](#security.txt)
## App Stores
### Smart App Banners in iOS 6+ Safari
Stop bothering everyone with gross modals advertising your entry in the App
Store. Including the following [meta
tag](https://developer.apple.com/documentation/webkit/promoting_apps_with_smart_app_banners)
will unobtrusively give the user the option to download your iOS app, or open it
with some data about the user's current state on the website.
```html
<meta name="apple-itunes-app" content="app-id=APP_ID,app-argument=SOME_TEXT">
```
## DNS prefetching
In short, DNS Prefetching is a method of informing the browser of domain names
referenced on a site so that the client can resolve the DNS for those hosts,
cache them, and when it comes time to use them, have a faster turn around on the
request.
### Implicit prefetches
There is a lot of prefetching done for you automatically by the browser. When
the browser encounters an anchor in your html that does not share the same
domain name as the current location the browser requests, from the client OS,
the IP address for this new domain. The client first checks its cache and then,
lacking a cached copy, makes a request from a DNS server. These requests happen
in the background and are not meant to block the rendering of the page.
The goal of this is that when the foreign IP address is finally needed it will
already be in the client cache and will not block the loading of the foreign
content. Fewer requests result in faster page load times. The perception of this
is increased on a mobile platform where DNS latency can be greater.
### Explicit prefetches
Typically the browser only scans the HTML for foreign domains. If you have
resources that are outside of your HTML (a javascript request to a remote server
or a CDN that hosts content that may not be present on every page of your site,
for example) then you can queue up a domain name to be prefetched.
```html
<link rel="dns-prefetch" href="//example.com">
<link rel="dns-prefetch" href="https://ajax.googleapis.com">
```
You can use as many of these as you need, but it's best if they are all
immediately after the [Meta
Charset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-charset)
element (which should go right at the top of the `head`), so the browser can act
on them ASAP.
### Further reading about DNS prefetching
* https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control
* https://dev.chromium.org/developers/design-documents/dns-prefetching
## Internet Explorer
### IE Pinned Sites
Enabling your application for pinning will allow IE users to add it to their
Windows Taskbar and Start Menu. This comes with a range of new tools that you
can easily configure with the elements below. See more [documentation on IE
Pinned
Sites](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/samples/gg491731(v%3dvs.85)).
### Name the Pinned Site for Windows
Without this rule, Windows will use the page title as the name for your
application.
```html
<meta name="application-name" content="Sample Title">
```
### Give your Pinned Site a tooltip
You know — a tooltip. A little textbox that appears when the user holds their
mouse over your Pinned Site's icon.
```html
<meta name="msapplication-tooltip" content="A description of what this site does.">
```
### Set a default page for your Pinned Site
If the site should go to a specific URL when it is pinned (such as the
homepage), enter it here. One idea is to send it to a special URL so you can
track the number of pinned users, like so:
`https://www.example.com/index.html?pinned=true`
```html
<meta name="msapplication-starturl" content="https://www.example.com/index.html?pinned=true">
```
### Recolor IE's controls manually for a Pinned Site
IE will automatically use the overall color of your Pinned Site's favicon to
shade its browser buttons. UNLESS you give it another color here. Only use named
colors (`red`) or hex colors (`#ff0000`).
```html
<meta name="msapplication-navbutton-color" content="#ff0000">
```
### Manually set the window size of a Pinned Site
If the site should open at a certain window size once pinned, you can specify
the dimensions here. It only supports static pixel dimensions. 800x600 minimum.
```html
<meta name="msapplication-window" content="width=800;height=600">
```
### Jump List "Tasks" for Pinned Sites
Add Jump List Tasks that will appear when the Pinned Site's icon gets a
right-click. Each Task goes to the specified URL, and gets its own mini icon
(essentially a favicon, a 16x16 .ICO). You can add as many of these as you need.
```html
<meta name="msapplication-task" content="name=Task 1;action-uri=http://host/Page1.html;icon-uri=http://host/icon1.ico">
<meta name="msapplication-task" content="name=Task 2;action-uri=http://microsoft.com/Page2.html;icon-uri=http://host/icon2.ico">
```
### (Windows 8) High quality visuals for Pinned Sites
Windows 8 adds the ability for you to provide a PNG tile image and specify the
tile's background color. [Full details on the IE
blog](https://docs.microsoft.com/en-us/archive/blogs/ie/high-quality-visuals-for-pinned-sites-in-windows-8).
* Create a 144x144 image of your site icon, filling all of the canvas, and using
a transparent background.
* Save this image as a 32-bit PNG and optimize it without reducing colour-depth.
It can be named whatever you want (e.g. `metro-tile.png`).
* To reference the tile and its color, add the HTML `meta` elements described in
the IE Blog post.
### (Windows 8) Badges for Pinned Sites
IE will poll an XML document for badge information to display on your app's tile
in the Start screen. The user will be able to receive these badge updates even
when your app isn't actively running. The badge's value can be a number, or one
of a predefined list of glyphs.
* [Tutorial on IEBlog with link to badge XML
schema](https://docs.microsoft.com/en-us/archive/blogs/ie/pinned-sites-in-windows-8)
* [Available badge
values](https://docs.microsoft.com/en-us/uwp/schemas/tiles/badgeschema/element-badge)
```html
<meta name="msapplication-badge" value="frequency=NUMBER_IN_MINUTES;polling-uri=https://www.example.com/path/to/file.xml">
```
## Search
### Direct search spiders to your sitemap
After creating a [sitemap](https://www.sitemaps.org/protocol.html)
Submit it to search engine tool:
* [Google](https://www.google.com/webmasters/tools/sitemap-list)
* [Bing](https://www.bing.com/toolbox/webmaster)
* [Yandex](https://webmaster.yandex.com/)
* [Baidu](https://zhanzhang.baidu.com/) OR Insert the following line anywhere in
your robots.txt file, specifying the path to your sitemap:
```
Sitemap: https://example.com/sitemap_location.xml
```
### Hide pages from search engines
According to Heather Champ, former community manager at Flickr, you should not
allow search engines to index your "Contact Us" or "Complaints" page if you
value your sanity. This is an HTML-centric way of achieving that.
```html
<meta name="robots" content="noindex">
```
**_WARNING:_** DO NOT INCLUDE ON PAGES THAT SHOULD APPEAR IN SEARCH ENGINES.
### Firefox and IE Search Plugins
Sites with in-site search functionality should be strongly considered for a
browser search plugin. A "search plugin" is an XML file which defines how your
plugin behaves in the browser. [How to make a browser search
plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plugin).
```html
<link rel="search" title="" type="application/opensearchdescription+xml" href="">
```
## Miscellaneous
* Use
[polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills).
* Use [Microformats](http://microformats.org/wiki/Main_Page) (via
[microdata](http://microformats.org/wiki/microdata)) for optimum search
results
[visibility](https://webmasters.googleblog.com/2009/05/introducing-rich-snippets.html).
* If you want to disable the translation prompt in Chrome or block Google
Translate from translating your web page, use [`<meta name="google"
content="notranslate">`](https://support.google.com/webmasters/answer/79812).
To disable translation for a particular section of the web page, add
[`class="notranslate"`](https://support.google.com/translate/?hl=en#2641276).
* If you want to disable the automatic detection and formatting of possible
phone numbers in Safari on iOS, use [`<meta name="format-detection"
content="telephone=no">`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html).
* Avoid development/stage websites "leaking" into SERPs (search engine results
page) by [implementing X-Robots-tag
headers](https://github.com/h5bp/html5-boilerplate/issues/804).
## News Feeds
### RSS
Have an RSS feed? Link to it here. Want to [learn how to write an RSS feed from
scratch](https://www.rssboard.org/rss-specification)?
```html
<link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml">
```
### Atom
Atom is similar to RSS, and you might prefer to use it instead of or in addition
to it. [See what Atom's all
about](https://en.wikipedia.org/wiki/Atom_(Web_standard)).
```html
<link rel="alternate" type="application/atom+xml" title="Atom" href="/atom.xml">
```
### Pingbacks
Your server may be notified when another site links to yours. The href attribute
should contain the location of your pingback service.
```html
<link rel="pingback" href="">
```
* High-level explanation:
https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
* Step-by-step example case:
https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
* PHP pingback service:
https://web.archive.org/web/20131211032834/http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/
## Social Networks
### Facebook Open Graph data
You can control the information that Facebook and others display when users
share your site. Below are just the most basic data points you might need. For
specific content types (including "website"), see [Facebook's built-in Open
Graph content
templates](https://developers.facebook.com/docs/sharing/opengraph/using-objects).
Take full advantage of Facebook's support for complex data and activity by
following the [Open Graph
tutorial](https://developers.facebook.com/docs/sharing/webmasters/getting-started).
For a reference of Open Graph's markup and properties, you may check [Facebook's
Open Graph Protocol reference](https://ogp.me). Finally, you can validate your
markup with the [Facebook Object
Debugger](https://developers.facebook.com/tools/debug/) (needs registration to
Facebook).
```html
<meta property="fb:app_id" content="123456789">
<meta property="og:url" content="https://www.example.com/path/to/page.html">
<meta property="og:type" content="website">
<meta property="og:title" content="">
<meta property="og:image" content="https://www.example.com/path/to/image.jpg">
<meta property="og:description" content="">
<meta property="og:site_name" content="">
<meta property="article:author" content="">
```
### Twitter Cards
Twitter provides a snippet specification that serves a similar purpose to Open
Graph. In fact, Twitter will use Open Graph when Cards is not available. You can
read more about the various snippet formats in the
[official Twitter Cards
documentation](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
and you can validate your markup with the [Card
validator](https://cards-dev.twitter.com/validator) (needs registration to
Twitter).
```html
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@site_account">
<meta name="twitter:creator" content="@individual_account">
<meta name="twitter:url" content="https://www.example.com/path/to/page.html">
<meta name="twitter:title" content="">
<meta name="twitter:description" content="">
<meta name="twitter:image" content="https://www.example.com/path/to/image.jpg">
```
### Schema.org
Google also provides a snippet specification that serves a similar purpose to
Facebook's Open Graph or Twitter Cards. This metadata is a subset of
[schema.org's microdata vocabulary](https://schema.org/), which covers many
other schemas that can describe the content of your pages to search engines. For
this reason, this metadata is more generic for SEO, notably for Google's
search-engine, although this vocabulary is also used by Microsoft, Pinterest and
Yandex.
You can validate your markup with the [Structured Data Testing
Tool](https://search.google.com/structured-data/testing-tool). Also, please
note that this markup requires to add attributes to your top `html` tag.
```html
<html class="no-js" lang="" itemscope itemtype="https://schema.org/Article">
<head>
<link rel="author" href="">
<link rel="publisher" href="">
<meta itemprop="name" content="">
<meta itemprop="description" content="">
<meta itemprop="image" content="">
```
## URLs
### Canonical URL
Signal to search engines and others "Use this URL for this page!" Useful when
parameters after a `#` or `?` is used to control the display state of a page.
`https://www.example.com/cart.html?shopping-cart-open=true` can be indexed as
the cleaner, more accurate `https://www.example.com/cart.html`.
```html
<link rel="canonical" href="">
```
## Web Apps
There are a couple of meta tags that provide information about a web app when
added to the Home Screen on iOS:
* Adding `apple-mobile-web-app-capable` will make your web app chrome-less and
provide the default iOS app view. You can control the color scheme of the
default view by adding `apple-mobile-web-app-status-bar-style`.
```html
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
```
* You can use `apple-mobile-web-app-title` to add a specific sites name for the
Home Screen icon.
```html
<meta name="apple-mobile-web-app-title" content="">
```
For further information please read the [official
documentation](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html)
on Apple's site.
### Apple Touch Icons
Apple touch icons are used as icons when a user adds your webapp to the home
screen of an iOS devices.
Though the dimensions of the icon can vary between iOS devices and versions one
`180×180px` touch icon named `icon.png` and including the following in the
`<head>` of the page is enough:
```html
<link rel="apple-touch-icon" href="icon.png">
```
For a more comprehensive overview, please refer to Mathias' [article on Touch
Icons](https://mathiasbynens.be/notes/touch-icons).
### Apple Touch Startup Image
Apart from that it is possible to add start-up screens for web apps on iOS. This
basically works by defining `apple-touch-startup-image` with an according link
to the image. Since iOS devices have different screen resolutions it maybe
necessary to add media queries to detect which image to load. Here is an example
for an iPhone:
```html
<link rel="apple-touch-startup-image" media="(max-device-width: 480px) and (-webkit-min-device-pixel-ratio: 2)" href="img/startup.png">
```
### Chrome Mobile web apps
Chrome Mobile has a specific meta tag for making apps [installable to the
homescreen](https://developer.chrome.com/multidevice/android/installtohomescreen)
which tries to be a more generic replacement to Apple's proprietary meta tag:
```html
<meta name="mobile-web-app-capable" content="yes">
```
Same applies to the touch icons:
```html
<link rel="icon" sizes="192x192" href="highres-icon.png">
```
### Theme Color
You can add the [`theme-color` meta
extension](https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color)
in the `<head>` of your pages to suggest the color that browsers and OSes should
use if they customize the display of individual pages in their UIs with varying
colors.
```html
<meta name="theme-color" content="#ff69b4">
```
The `content` attribute extension can take any valid CSS color.
Currently, the `theme-color` meta extension is supported by [Chrome 39+ for
Android
Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
### humans.txt
You can include a `humans.txt` file in the root of your site which can be used
to provide information about people involved with the website.
For more information about `humans.txt`, please see: https://humanstxt.org/
### security.txt
When security risks in web services are discovered by users they often lack the
channels to disclose them properly. As a result, security issues may be left
unreported.
Security.txt defines a standard to help organizations define the process for
users to disclose security vulnerabilities securely. Include a text file on your
server at `.well-known/security.txt` with the relevant contact details.
Check [https://securitytxt.org/](https://securitytxt.org/) for more details.

20
docs/faq.md Normal file
View File

@@ -0,0 +1,20 @@
[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?](#do-i-need-to-upgrade-my-site-each-time-a-new-version-of-html5-boilerplate-is-released)
* [Where can I get help with support
questions?](#where-can-i-get-help-with-support-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
[StackOverflow](https://stackoverflow.com/questions/tagged/html5boilerplate).

207
docs/html.md Normal file
View File

@@ -0,0 +1,207 @@
[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)
# The HTML
By default, HTML5 Boilerplate provides two `html` pages:
* [`index.html`](#indexhtml) - a default HTML skeleton that should form the
basis of all pages on your website
* `404.html` - a placeholder 404 error page
## `index.html`
### The `no-js` Class
The `no-js` class is provided in order to allow you to more easily and
explicitly add custom styles based on whether JavaScript is disabled (`.no-js`)
or enabled (`.js`). Using this technique also helps [avoid the
FOUC](https://www.paulirish.com/2009/avoiding-the-fouc-v3/).
### Language Attribute
Please consider specifying the language of your content by adding a
[value](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
to the `lang` attribute in the `<html>` as in this example:
```html
<html class="no-js" lang="en">
```
### The order of the `<title>` and `<meta>` tags
The charset declaration (`<meta charset="utf-8">`) must be included completely
within the
[first 1024 bytes of the document](https://html.spec.whatwg.org/multipage/semantics.html#charset)
and should be specified as early as possible (before any content that could be
controlled by an attacker, such as a `<title>` element) in order to avoid a
potential
[encoding-related security issue](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
in Internet Explorer.
### Meta Description
The `description` meta tag provides a short description of the page. In some
situations this description is used as a part of the snippet shown in the search
results.
```html
<meta name="description" content="This is a description">
```
Google's
[Create good meta descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
documentation has useful tips on creating an effective description.
### Mobile Viewport
There are a few different options that you can use with the
[`viewport` meta tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4
"Viewport and Media Queries - The Complete Idiot's Guide").
You can find out more in [
the MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag).
HTML5 Boilerplate comes with a simple setup that strikes a good balance for general use cases.
```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you
can do so with additional viewport parameters.
[Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) for
details.
### Open Graph Metadata
The [Open Graph Protocol](https://ogp.me/) allows you to define the way your
site is presented when referenced on third party sites and applications
(Facebook, Twitter, LinkedIn). The protocol provides a series of meta elements
that define the details of your site. The required attributes define the title,
preview image, URL, and [type](https://ogp.me/#types) (e.g., video, music,
website, article).
```html
<meta property="og:title" content="">
<meta property="og:type" content="">
<meta property="og:url" content="">
<meta property="og:image" content="">
```
In addition to these four attributes there are many more attributes you can use
to add more richness to the description of your site. This just represents the
most basic implementation.
To see a working example, the following is the open graph metadata for the HTML5
Boilerplate site. In addition to the required fields we add `og:description` to
describe the site in more detail.
```html
<meta property="og:url" content="https://html5boilerplate.com/">
<meta property="og:title" content="HTML5 ★ BOILERPLATE">
<meta property="og:type" content="website">
<meta property="og:description" content="The web’s most popular front-end template which helps you build fast, robust, and adaptable web apps or sites.">
<meta property="og:image" content="https://html5boilerplate.com/icon.png">
```
### Web App Manifest
HTML5 Boilerplate includes a simple web app manifest file.
The web app manifest is a simple JSON file that allows you to control how your
app appears on a device's home screen, what it looks like when it launches in
that context and what happens when it is launched. This allows for much greater
control over the UI of a saved site or web app on a mobile device.
It's linked to from the HTML as follows:
```html
<link rel="manifest" href="site.webmanifest">
```
Our
[site.webmanifest](https://github.com/h5bp/html5-boilerplate/blob/main/src/site.webmanifest)
contains a very skeletal "app" definition, just to show the basic usage. You
should fill this file out with
[more information about your site or application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
### Favicons and Touch Icon
The shortcut icons should be put in the root directory of your site.
`favicon.ico` is automatically picked up by browsers if it's placed in the root.
HTML5 Boilerplate comes with a default set of icons (include favicon and one
Apple Touch Icon) that you can use as a baseline to create your own.
Please refer to the more detailed description in the [Extend section](extend.md)
of these docs.
### The Content Area
The central part of the boilerplate template is pretty much empty. This is
intentional, in order to make the boilerplate suitable for both web page and web
app development.
### Modernizr
HTML5 Boilerplate uses a custom build of Modernizr.
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes
to the `html` element based on the results of feature test and which ensures
that all browsers can make use of HTML5 elements (as it includes the HTML5
Shiv). This allows you to target parts of your CSS and JavaScript based on the
features supported by a browser.
Starting with version 3 Modernizr can be customized using the
[modernizr-config.json](https://github.com/h5bp/html5-boilerplate/blob/main/modernizr-config.json)
and the
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).
### What About Polyfills?
If you need to include
[polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill) in your
project, you must make sure those load before any other JavaScript. If you're
using a polyfill CDN service, like [polyfill.io](https://polyfill.io/v3/), just put
it before the other scripts in the bottom of the page:
```html
<script src="js/vendor/modernizr-3.11.7.min.js"></script>
<script src="https://polyfill.io/v3/polyfill.min.js"></script>
<script src="js/app.js"></script>
</body>
```
When you have a bunch of polyfills to load in, you could also
create a `polyfills.js` file in the `js/vendor` directory or include the files
individually and combine them using a build tool. Always ensure that the
polyfills are all loaded before any other JavaScript.
There are some misconceptions about Modernizr and polyfills. It's important to
understand that Modernizr just handles feature checking, not polyfilling itself.
The only thing Modernizr does regarding polyfills is that the team maintains
[a huge list of cross Browser polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
### jQuery
As of v8.0.0 we no longer include jQuery by default. Web development has
changed a lot since we started this project and while many millions of sites
still use jQuery there are many sites and applications that don't. 10 years ago
jQuery _was_ JavaScript for most developers. That's not the case any more so
we've made the decision to remove jQuery from the project.
If you're interested in including it, you can easily install jQuery using the
following command:
```
npm install jquery
```
You can then copy the minified file into the `vendor` folder and add jQuery
to the `index.html` manually.
To load jQuery from a CDN with a local fallback you can use the following:
```html
<script src="https://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-3.6.0.min.js"><\/script>')</script>
```

21
docs/js.md Normal file
View File

@@ -0,0 +1,21 @@
[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 3rd party library code.
Our custom build of the Modernizr library is included by
default. You may wish to create your own [custom Modernizr build with the online
builder](https://modernizr.com/download/) or [command line
tool](https://modernizr.com/docs#command-line-config).

185
docs/misc.md Normal file
View File

@@ -0,0 +1,185 @@
[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
table of contents](TOC.md)
# Miscellaneous
* [.gitignore](#gitignore)
* [.editorconfig](#editorconfig)
* [Server Configuration](#server-configuration)
* [robots.txt](#robotstxt)
* [browserconfig.xml](#browserconfigxml)
* [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/).
## Server Configuration
H5BP includes a [`.htaccess`](#htaccess) file for the [Apache HTTP
server](https://httpd.apache.org/docs/). If you are not using Apache
as your web server, then you are encouraged to download a
[server configuration](https://github.com/h5bp/server-configs) that
corresponds to your web server and environment.
A `.htaccess` (hypertext access) file is an [Apache HTTP server
configuration file](https://github.com/h5bp/server-configs-apache).
The `.htaccess` file is mostly used for:
* Rewriting URLs
* Controlling cache
* Authentication
* Server-side includes
* Redirects
* Gzipping
If you have access to the main server configuration file (usually called
`httpd.conf`), you should add the logic from the `.htaccess` file in, for
example, a `<Directory>` section in the main configuration file. This is usually
the recommended way, as using .htaccess files slows down Apache!
To enable Apache modules locally, please see [the Apache modules documentation](https://github.com/h5bp/server-configs-apache#enable-apache-httpd-modules)
In the repo the `.htaccess` is used for:
* Allowing cross-origin access to web fonts
* CORS header for images when browsers request it
* Enable `404.html` as 404 error document
* Making the website experience better for IE users better
* Media UTF-8 as character encoding for `text/html` and `text/plain`
* Enabling the rewrite URLs engine
* Forcing or removing the `www.` at the begin of a URL
* It blocks access to directories without a default document
* It blocks access to files that can expose sensitive information.
* It reduces MIME type security risks
* It forces compressing (gzipping)
* It tells the browser whether they should request a specific file from the
server or whether they should grab it from the browser's cache
When using `.htaccess` we recommend reading all inline comments (the rules after
a `#`) in the file once. There is a bunch of optional stuff in it.
If you want to know more about the `.htaccess` file check out the
[Apache HTTP server docs](https://httpd.apache.org/docs/) or more
specifically the [htaccess
section](https://httpd.apache.org/docs/current/howto/htaccess.html).
Notice that the original repo for the `.htaccess` file is [this
one](https://github.com/h5bp/server-configs-apache).
## 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)
## browserconfig.xml
The `browserconfig.xml` file is used to customize the tile displayed when users
pin your site to the Windows 8.1 start screen. In there you can define custom
tile colors, custom images or even [live tiles](https://docs.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/samples/dn455106(v=vs.85)).
By default, the file points to 2 placeholder tile images:
* `tile.png` (558x558px): used for `Small`, `Medium` and `Large` tiles.
This image resizes automatically when necessary.
* `tile-wide.png` (558x270px): user for `Wide` tiles.
Notice that IE11 uses the same images when adding a site to the `favorites`.
For more in-depth information about the `browserconfig.xml` file, please
see [MSDN](https://docs.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
## 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://docs.npmjs.com/misc/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](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.

134
docs/usage.md Normal file
View File

@@ -0,0 +1,134 @@
[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
│ ├── normalize.css
│ └── style.css
├── doc
├── img
├── js
│ ├── app.js
│ └── vendor
│ └── modernizr.min.js
├── .editorconfig
├── .htaccess
├── 404.html
├── browserconfig.xml
├── favicon.ico
├── humans.txt
├── icon.png
├── icon.svg
├── index.html
├── package.json
├── robots.txt
├── site.webmanifest
├── tile.png
├── tile-wide.png
└── webpack.config.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).
### .htaccess
The default web server configs are for Apache. For more information, please
refer to the [Apache Server Configs
repository](https://github.com/h5bp/server-configs-apache).
Host your site on a server other than Apache? You're likely to find the
corresponding server configs project listed in our [Server
Configs](https://github.com/h5bp/server-configs/blob/master/README.md)
repository.
### 404.html
A helpful custom 404 to get you started.
### browserconfig.xml
This file contains all settings regarding custom tiles for IE11 and Edge.
For more info on this topic, please refer to [Microsoft's
Docs](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
### .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.
### humans.txt
Edit this file to include the team that worked on your site/app, and the
technology powering it.
### 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`, `tile.png`, `tile-wide.png` 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).