html5-boilerplate

17 January 2015

前言

最近，主攻前端开发，研究前端开发框架，看《HTML5和CSS3实例教程》。涉及了这样的项目: sass, compass, bootstrap/ratchet, html5-boilerplate。 我的目的是搞懂这些坑爹的东西，理清其间的关系，提高自己的能力，最终，组合这些能力，用来干点别的有趣的事情。

以下，是对其的官方站点的介绍的翻译。

简介

HTML5 Boilerplate(样板库)是一个专业的前端模板，可以用来构建快速的，健壮的，适应性强的web app或者站点。

该项目是多年迭代开发的产物，并组合了很多的社区经验。其中并未体现特定的开发哲学或框架，所以你爱咋折腾就咋折腾。

特性

  • 设置好HTML5. 可以自信的使用新的元素.
  • 检查浏览器兼容(Chrome, Firefox, IE8+, Opera, Safari).
  • 以渐进增强的方式设计Designed with progressive enhancement in mind.
  • 包含了Normalize.css 以及一些公共bug的消除
  • 最新jQuery的cdn源
  • 用作特定探测的最新Modernizr
  • Placeholder样式以及媒体查询
  • 有用的css辅助方法
  • 默认的优化过的打印css样式
  • 避免任何旧浏览器中的console引起js错误
  • 优化过的Google分析脚本
  • Apache服务器缓存，压缩，以及其他的默认A级性能的默认配置
  • “友好删除 .” 可以很容易的剥离不需要的部分.
  • 广泛的内联和附赠的文件。

HTML5 Boilerplate v4提供了遗留浏览器的支持 (IE 6+, Firefox 3.6+, Safari 4+), 但不再继续开发了。

目录

  • Usage — 项目内容的概述
  • FAQ — 频繁提及的问题及其相关答案

HTML5 Boilerplate core

Development

H5BP组织 维护了一些与HTML5 Boilerplate互为补充的项目，这些项目可以 帮助你改善web站点/app的不同方面(例如: 性能，安全性等)。

这些项目是:

使用

Once you have cloned or downloaded HTML5 Boilerplate, creating a site or app usually involves the following:

下载或克隆HTML5 Boilerplate，然后，按照如下的步骤创建站点或app:

  1. 设置站点的基本结构
  2. 添加一些内容，样式和功能
  3. 本地运行站点，并进行预览Run your site locally to see how it looks.
  4. (可选的，运行构建脚本，从而自动优化站点 - 例如: ant build script)
  5. 部署站点

基本结构

基本的HTML5代码库初始化的结构如下:

.
├── css
│   ├── main.css  
│   └── normalize.css  重置浏览器样式
├── doc
├── img
├── js
│   ├── main.js
│   ├── plugins.js
│   └── vendor
│       ├── jquery.min.js
│       └── modernizr.min.js
├── .editorconfig
├── .htaccess
├── 404.html
├── apple-touch-icon.png
├── browserconfig.xml
├── index.html
├── humans.txt
├── robots.txt
├── crossdomain.xml
├── favicon.ico
├── tile-wide.png
└── tile.png

下面将逐个的介绍每个主要的部件，以及如何使用这些组件。

css目录

包含了项目中所有的css文件。其中包含了一些初始化的css。更多内容，参考下面的css章节。

doc

该目录包含了所有HTML5的代码库的文档。可以将其用作为个人项目的文档的位置。

js

该目录包含项目中所有的js文件。库，插件，以及定制化的代码都因该放置这里。这里同样包含一些 基础的js文件。更多内容参考js章节。

.htaccess

Apache服务器的默认配置。更多信息，参考Apache Server Configs repository。

将站点放置在其他的服务器上，而不是Apache？ 可以在Server Configs 中找到对应的服务器配置。

404.html

404辅助页面。备注: 404页面中，样式内联了，这算是一个重最佳实践！！

browserconfig.xml

包含了所有关于IE11配置文件。更多关于该话题的讨论，参考MSDN.

.editorconfig

.editorconfig提供并鼓励团队在不同的编辑器和IDE之间，维护一致性的代码风格 更多阅读并参考misc文件.

index.html

针对网站所有页面的默认HTML结构。如果使用服务器端模板框架，可将HTML作为起步的布局模板。

在修改目录结构时，确保更新所有引用的css和js的URL。

如果，想要使用Google的通用分析，确保将底部的代码片段，修改为自己的分析ID。

humans.txt

编辑该文件，告知团队，其中所使用的技术。

robots.txt

编辑该文件，使其包含不想被搜索引擎找到的页面。

crossdomain.xml

关于如何处理跨域请求的问题的模板。更多参考misc章节。

Icons

将默认的favicon.ico, tile.png, tile-wide.png 以及Apple Touch Icon 替换成自己站点的。

如果针对不同的分辨率使用不同的Apple Touch Icons，可以参考extend章节。

html

默认情况下， HTML5 Boilerplate提供两个html页面:

  • index.html - 默认的HTML骨架，可以用作站点所有页面的基准
  • 404.html - 一个预占位的404错误页面

index.html

no-js类

no-js类基于js是否被禁用，从而更加容易且显式的添加特定的样式。使用该技术，可以帮助避免FOUC

注: FOUC, 是Flash of unstyled content, 翻译过来，就是未样式化的内容的崩溃。

语言属性

通过给<html>元素添加lang属性，从而考虑为内容指定语言属性。

<html class="no-js" lang="en">

<title>和<meta>标签的顺序

<title>和<meta>标签的顺序非常的重要，这是因为:

1) 字符集申明(<meta charset="utf-8">):

  • 必须完整的包含在文档的前1024个字节前
  • 需要尽可能早的指定(在任何可能被攻击者控制的内容之前，比如<title>元素)，从而避免IE中潜在的编码相关的问题

2) 兼容模式meta标签(<meta http-equiv="X-UA-Compatible" content="IE=edge">):

X-UA-Compatible

IE 8/9/10 支持文档兼容模式，该模式影响页面的解释和显示。 由于这个原因，即使站点的访问者使用了IE，但他可能不使用最新的渲染引擎。而且，有可能决定使用IE 5.5的渲染引擎渲染页面。

指定X-UA-Compatible的meta标签:

<meta http-equiv="X-UA-Compatible" content="IE=edge">

或者，发送页面时，包含如下的HTTP响应头:

X-UA-Compatible: IE=edge

这样，将强迫IE 8/9/10在大多数情况下以最高可用的模式渲染页面， 从而迫使每个人浏览器页面时，使用浏览器可提供的最佳用户体验。

如果有可能，推荐使用HTTP响应头，而不是meta标签。这是因为meta标签在站点不是通过标准接口提供时， IE的在内部网络中使用兼容模式选项将会被勾选。

如果，使用Apache作为web服务器，.htaccess文件 将接管HTTP头部。如果使用了其他的服务器，参考其他服务器配置。

自从IE11，文档模式被遗弃了。如果业务 依然依赖为老版本的IE开发设计的web app和服务，可能需要考虑使用企业模式

Mobile viewport

使用viewport元标签具有多个不同的选项。更多关于viewport的， 参考Apple的开发者文档。 HTML5 Boilerplate使用了一个相对简单的设置，作为针对理论和使用的较好权衡。

<meta name="viewport" content="width=device-width, initial-scale=1">

Favicons和Touch Icon

快捷图标可以放置在站点的根目录处。HTML5 Boilerplate自带了一系列默认的图标(包括favicon以及Apple Touch Icon)，可以以此作为基准，从而创建自己的。

更多细节描述参考扩展章节。

Modernizr

HTML5 Boilerplate使用了定制化构建的Modernizr。

Modernizr是一个Javascirpt类库，其基于特性测试的结果给html元素添加类， 并通过使用HTML5 Shiv确保所有的浏览器都可以使用HTML5的元素。该类库允许基于浏览器支持的特性，从而 使用特定的css或js。

一般而言，为了保证加载时间最小化，最好在页面结束时调用javascript。这是因为从外部服务器加载 脚本，会导致页面加载阻塞。但是，Modernizr必须要在浏览器开始渲染页面之前运行，从而，使得缺乏 HTML5元素支持的浏览器可以正常工作。所以，Modernizr的是必须要在文档顶部同步加载的js文件。

需要放在文档顶部的原因，其实和HTML5 Shiv有莫大的关系。HTML5的支持也是Shiv的效果。

polyfills如何？

如果需要在项目中使用polyfills，确保其在 其他js加载之前加载。如果使用诸如cdn.polyfill.io这样的cdn服务，只需要 在页面底部，将polyfill的应用放在其他js之前。

<script src="//cdn.polyfill.io/v1/polyfill.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-1.11.2.min.js"><\/script>')</script>
<script src="js/plugins.js"></script>
<script src="js/main.js"></script>

如果，想要包含polyfills，需要在js/plugins.js中添加。当你有一打polyfills需要加载时，可在js/vendor 创建一个polyfills.js，然后在js/plugins.js中包含。注意，确保polyfills在其他js之前加载。

关于Modernizr和polyfills，存在一些误解。有一点很重要，Modernizr只处理特性检查，而不提供填充特性(polyfilling)的功能。 Modernizr所做的唯一关于polyfills的是，其团队维护了跨浏览器的polyfills列表。

内容区域

代码库的模板的主要部分都是空白。这是故意的，为了使得代码库适合web页面和web appd的开发。

浏览器升级提示

代码库的主要区域包含了包含了提示IE6/7的用户安装新的浏览器的弹出提示框。如果，你想要支持IE 6/7, 你就需要移除这段代码。

Google CDN for jQuery

Google的CDN源在国内不能访问，就不必讨论了。

可以使用如下的工具对站点进行测试:

注： 在无网络时，可以使用本地jQuery库。

Google全局分析追踪代码

Finally, an optimized version of the Google Universal Analytics tracking code is included. Google recommends that this script be placed at the top of the page. Factors to consider: if you place this script at the top of the page, you’ll be able to count users who don’t fully load the page, and you’ll incur the max number of simultaneous connections of the browser.

Further information:

N.B. The Google Universal Analytics snippet is included by default mainly because Google Analytics is currently one of the most popular tracking solutions out there. However, its usage isn’t set in stone, and you SHOULD consider exploring the alternatives and use whatever suits your needs best!

css

HTML5 Boilerplate的CSS包含了:

This starting CSS does not rely on the presence of conditional class names, conditional style sheets, or Modernizr, and it is ready to use no matter what your development preferences happen to be.

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, as well as this blog post.

Useful defaults

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

You are free and even encouraged to modify or add to these base styles as your project requires.

Common helpers

Along with the base styles, we also provide some commonly used helper classes.

.hidden

The hidden class can be added to any element that you want to hide visually and from screen readers. It could be an element that will be populated and displayed later, or an element you will hide with JavaScript.

.visuallyhidden

The visuallyhidden class can be added to any element that you want to hide visually, while still have its content accessible to screen readers.

See also:

.invisible

The invisible class can be added to any element that you want to hide visually and from screen readers, but without affecting the layout.

As opposed to the hidden class that effectively removes the element from the layout, the invisible class will simply make the element invisible while keeping it in the flow and not affecting the positioning of the surrounding content.

N.B. Try to stay away from, and don’t use the classes specified above for keyword stuffing as you will harm your site’s ranking!

.clearfix

The clearfix class can be added to any element to ensure that it always fully contains its floated children.

Over the years there have been many variants of the clearfix hack, but currently, we use the micro clearfix.

Media Queries

HTML5 Boilerplate makes it easy for you to get started with a mobile first and responsive web design approach to development. But it’s worth remembering that there are no silver bullets.

We include placeholder media queries to help you build up your mobile styles for wider viewports and high-resolution displays. It’s recommended that you adapt these media queries based on the content of your site rather than mirroring the fixed dimensions of specific devices.

If you do not want to take the mobile first approach, you can simply edit or remove these placeholder media queries. One possibility would be to work from wide viewports down, and use max-width media queries instead (e.g.: @media only screen and (max-width: 480px)).

For more features that can help you in your mobile web development, take a look into our Mobile Boilerplate.

Print styles

Lastly, we provide some useful print styles that will optimize the printing process, as well as make the printed pages easier to read.

At printing time, these styles will:

The print styles are included along with the other css to avoid the additional HTTP request. Also, they should always be included last, so that the other styles can be overwritten.

js

Information about the default JavaScript included in the project.

main.js

This file can be used to contain or reference your site/app JavaScript code. For larger projects, you can make use of a JavaScript module loader, like Require.js, to load any other scripts you need to run.

plugins.js

This file can be used to contain all your plugins, such as jQuery plugins and other 3rd party scripts.

One approach is to put jQuery plugins inside of a (function($){ ... })(jQuery); closure to make sure they’re in the jQuery namespace safety blanket. Read more about jQuery plugin authoring

By default the plugins.js file contains a small script to avoid console errors in browsers that lack a console. The script will make sure that, if a console method isn’t available, that method will have the value of empty function, thus, preventing the browser from throwing an error.

vendor

This directory can be used to contain all 3rd party library code.

Minified versions of the latest jQuery and Modernizr libraries are included by default. You may wish to create your own custom Modernizr build.

其他

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

[core]
    excludesfile = ~/.gitignore
  • More on global ignores: https://help.github.com/articles/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 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 will 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.

Server Configuration

H5BP includes a .htaccess file for the Apache HTTP server. If you are not using Apache as your web server, then you are encouraged to download a server configuration that corresponds to your web server and environment.

Servers and Stacks

A comprehensive list of web servers and stacks are beyond the scope of this documentation, but some common ones include:

.htaccess

A .htaccess (hypertext access) file is a Apache HTTP server configuration file. 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 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: https://github.com/h5bp/server-configs-apache/wiki/How-to-enable-Apache-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 https://httpd.apache.org/docs/current/howto/htaccess.html.

Notice that the original repo for the .htaccess file is this one.

crossdomain.xml

The cross-domain policy file is an XML document that gives a web client — such as Adobe Flash Player, Adobe Reader, etc. — permission to handle data across multiple domains, by:

  • granting read access to data
  • permitting the client to include custom headers in cross-domain requests
  • granting permissions for socket-based connections

e.g. If a client hosts content from a particular source domain and that content makes requests directed towards a domain other than its own, the remote domain would need to host a cross-domain policy file in order to grant access to the source domain and allow the client to continue with the transaction.

For more in-depth information, please see Adobe’s cross-domain policy file specification.

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:

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.

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.

后记

发现h5bp好像是相当厉害的开源团队，此外，也发现一些知名的有趣的项目和网站，感觉，干前端还是挺有趣的。



傲娇的使用Disqus