mirror of
https://github.com/h5bp/html5-boilerplate.git
synced 2026-01-08 22:28:10 -05:00
161 lines
4.7 KiB
Markdown
161 lines
4.7 KiB
Markdown
[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.`
|