mirror of
https://github.com/h5bp/html5-boilerplate.git
synced 2026-01-08 22:28:10 -05:00
Add Prettier (#3011)
Consistent code formatting! (it fixed a few minor bugs too)
This commit is contained in:
Christian Oliff
34
docs/TOC.md
34
docs/TOC.md
@@ -2,19 +2,19 @@
|
||||
|
||||
## Getting started
|
||||
|
||||
* [Usage](usage.md) — Overview of the project contents.
|
||||
* [FAQ](faq.md) — Frequently asked questions along with their answers.
|
||||
- [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).
|
||||
- [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
|
||||
- [Extending and customizing HTML5 Boilerplate](extend.md) — Going further with
|
||||
the boilerplate.
|
||||
|
||||
## Related projects
|
||||
@@ -23,15 +23,15 @@ 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
|
||||
- [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
|
||||
- [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.
|
||||
- [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.
|
||||
|
||||
@@ -8,34 +8,34 @@ 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
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
- 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
|
||||
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.
|
||||
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.
|
||||
Let's take a look at how we configure our `main` branch.
|
||||
|
||||
#### `main`
|
||||
|
||||
@@ -45,73 +45,71 @@ 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 three status checks
|
||||
to pass before code can be merged
|
||||
* Build with Node 18
|
||||
* Build with Node 16
|
||||
* LGTM analysis: JavaScript
|
||||
* 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.
|
||||
- We require a pull request (PR) with one approving reviewer to merge code
|
||||
- In addition to the PR and approving reviewer, we require three status checks
|
||||
to pass before code can be merged
|
||||
_ Build with Node 18
|
||||
_ Build with Node 16 \* LGTM analysis: JavaScript
|
||||
- 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 16 and 18.
|
||||
* 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.
|
||||
* Since we're fan of the "belt and suspenders" approach to security, we also
|
||||
run a *LGTM.com* scan as well as the CodeQL scans. This tool, built on top of
|
||||
CodeQl can shake out different issues so it's nice to have the pair.
|
||||
* We push any changes to `main` to our [HTML5\-Boilerplate Template Repo](https://github.com/h5bp/html5-boilerplate-template)
|
||||
- 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 16 and 18.
|
||||
- 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.
|
||||
- Since we're fan of the "belt and suspenders" approach to security, we also
|
||||
run a _LGTM.com_ scan as well as the CodeQL scans. This tool, built on top of
|
||||
CodeQl can shake out different issues so it's nice to have the pair.
|
||||
- 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.
|
||||
of our `.github` folder.
|
||||
|
||||
### .github Folder
|
||||
|
||||
* workflows
|
||||
* `build-dist.yaml` is currently broken. We can't push to `main` without a
|
||||
- workflows
|
||||
- `build-dist.yaml` 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
|
||||
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
|
||||
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
|
||||
the settings for this job.
|
||||
- `dependency-review.yml` does what it says on the tin- it tests newly
|
||||
introduced dependencies for vulnerabilities.
|
||||
* `publish.yaml` is the action that publishes all the various versions of
|
||||
- `publish.yaml` 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.yaml` pushes the `HEAD` of `main` to our template repo
|
||||
* `spellcheck.yml` automatically checks markdown files for typos with cSpell.
|
||||
* `test.yaml` runs our test suite.
|
||||
* `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.
|
||||
- `push-to-template.yaml` pushes the `HEAD` of `main` to our template repo
|
||||
- `spellcheck.yml` automatically checks markdown files for typos with cSpell.
|
||||
- `test.yaml` runs our test suite.
|
||||
- `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
|
||||
use. We're going to continue to keep this document up to date as we change
|
||||
things or new GitHub features.
|
||||
|
||||
26
docs/css.md
26
docs/css.md
@@ -5,8 +5,8 @@ table of contents](TOC.md)
|
||||
|
||||
HTML5 Boilerplate's CSS includes:
|
||||
|
||||
* [Normalize.css](#normalizecss)
|
||||
* [style.css](#stylecss)
|
||||
- [Normalize.css](#normalizecss)
|
||||
- [style.css](#stylecss)
|
||||
|
||||
## Normalize.css
|
||||
|
||||
@@ -16,12 +16,12 @@ 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
|
||||
- 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/).
|
||||
@@ -30,12 +30,12 @@ page](https://necolas.github.io/normalize.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`,
|
||||
- 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...
|
||||
- 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)
|
||||
|
||||
@@ -7,17 +7,16 @@ 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.
|
||||
|
||||
* [Server Configuration](#server-configuration)
|
||||
* [App Stores](#app-stores)
|
||||
* [DNS prefetching](#dns-prefetching)
|
||||
* [Miscellaneous](#miscellaneous)
|
||||
* [News Feeds](#news-feeds)
|
||||
* [Search](#search)
|
||||
* [Social Networks](#social-networks)
|
||||
* [URLs](#urls)
|
||||
* [Web Apps](#web-apps)
|
||||
* [security.txt](#security.txt)
|
||||
|
||||
- [Server Configuration](#server-configuration)
|
||||
- [App Stores](#app-stores)
|
||||
- [DNS prefetching](#dns-prefetching)
|
||||
- [Miscellaneous](#miscellaneous)
|
||||
- [News Feeds](#news-feeds)
|
||||
- [Search](#search)
|
||||
- [Social Networks](#social-networks)
|
||||
- [URLs](#urls)
|
||||
- [Web Apps](#web-apps)
|
||||
- [security.txt](#security.txt)
|
||||
|
||||
## Server Configuration
|
||||
|
||||
@@ -83,12 +82,10 @@ Charset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-cha
|
||||
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
|
||||
|
||||
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control
|
||||
- https://dev.chromium.org/developers/design-documents/dns-prefetching
|
||||
|
||||
## Search
|
||||
|
||||
@@ -97,11 +94,13 @@ on them ASAP.
|
||||
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
|
||||
|
||||
- [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
|
||||
```
|
||||
@@ -129,29 +128,27 @@ plugin](https://developer.mozilla.org/en-US/docs/Web/OpenSearch).
|
||||
<link rel="search" title="" type="application/opensearchdescription+xml" href="">
|
||||
```
|
||||
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
* Use [Microformats](http://microformats.org/wiki/Main_Page) (via
|
||||
- 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
|
||||
- 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).
|
||||
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
|
||||
- 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).
|
||||
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
|
||||
- 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
|
||||
@@ -167,7 +164,7 @@ scratch](https://www.rssboard.org/rss-specification)?
|
||||
|
||||
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)).
|
||||
about](<https://en.wikipedia.org/wiki/Atom_(Web_standard)>).
|
||||
|
||||
```html
|
||||
<link rel="alternate" type="application/atom+xml" title="Atom" href="/atom.xml">
|
||||
@@ -182,15 +179,13 @@ should contain the location of your pingback service.
|
||||
<link rel="pingback" href="">
|
||||
```
|
||||
|
||||
* High-level explanation:
|
||||
- High-level explanation:
|
||||
https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
|
||||
* Step-by-step example case:
|
||||
- Step-by-step example case:
|
||||
https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
|
||||
* PHP pingback service:
|
||||
- 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
|
||||
@@ -285,7 +280,7 @@ the cleaner, more accurate `https://www.example.com/cart.html`.
|
||||
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
|
||||
- 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`.
|
||||
|
||||
@@ -294,7 +289,7 @@ added to the Home Screen on iOS:
|
||||
<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
|
||||
- You can use `apple-mobile-web-app-title` to add a specific sites name for the
|
||||
Home Screen icon.
|
||||
|
||||
```html
|
||||
@@ -305,7 +300,6 @@ 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
|
||||
@@ -322,7 +316,6 @@ Though the dimensions of the icon can vary between iOS devices and versions one
|
||||
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
|
||||
@@ -335,7 +328,6 @@ for an iPhone:
|
||||
<link rel="apple-touch-startup-image" media="(max-device-width: 480px) and (-webkit-min-device-pixel-ratio: 2)" href="img/startup.png">
|
||||
```
|
||||
|
||||
|
||||
### Theme Color
|
||||
|
||||
You can add the [`theme-color` meta
|
||||
|
||||
@@ -3,9 +3,9 @@ table of contents](TOC.md)
|
||||
|
||||
# Frequently asked questions
|
||||
|
||||
* [Do I need to upgrade my site each time a new version of HTML5 Boilerplate is
|
||||
- [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
|
||||
- [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?
|
||||
|
||||
@@ -5,9 +5,9 @@ table of contents](TOC.md)
|
||||
|
||||
By default, HTML5 Boilerplate provides two `html` pages:
|
||||
|
||||
* [`index.html`](#indexhtml) - a default HTML skeleton that should form the
|
||||
- [`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
|
||||
- `404.html` - a placeholder 404 error page
|
||||
|
||||
## `index.html`
|
||||
|
||||
@@ -52,8 +52,7 @@ 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").
|
||||
[`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.
|
||||
@@ -135,5 +134,3 @@ of these docs.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
46
docs/misc.md
46
docs/misc.md
@@ -3,11 +3,11 @@ table of contents](TOC.md)
|
||||
|
||||
# Miscellaneous
|
||||
|
||||
* [.gitignore](#gitignore)
|
||||
* [.editorconfig](#editorconfig)
|
||||
* [Server Configuration](#server-configuration)
|
||||
* [robots.txt](#robotstxt)
|
||||
* [package.json](#packagejson)
|
||||
- [.gitignore](#gitignore)
|
||||
- [.editorconfig](#editorconfig)
|
||||
- [Server Configuration](#server-configuration)
|
||||
- [robots.txt](#robotstxt)
|
||||
- [package.json](#packagejson)
|
||||
|
||||
--
|
||||
|
||||
@@ -30,8 +30,8 @@ globally ignore:
|
||||
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
|
||||
- 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
|
||||
|
||||
@@ -47,9 +47,9 @@ 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).
|
||||
plugin](https://editorconfig.org/#download).
|
||||
|
||||
__N.B.__ If you aren't using the server configurations provided by HTML5
|
||||
**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!
|
||||
|
||||
@@ -63,8 +63,8 @@ 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
|
||||
- `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
|
||||
@@ -79,8 +79,8 @@ 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)
|
||||
- [robotstxt.org](https://www.robotstxt.org/)
|
||||
- [How Google handles the `robots.txt` file](https://developers.google.com/search/reference/robots_txt)
|
||||
|
||||
## package.json
|
||||
|
||||
@@ -88,27 +88,27 @@ For more information about `robots.txt`, please see:
|
||||
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
|
||||
- `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
|
||||
- `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
|
||||
- `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
|
||||
- `start` serves your `index.html` with a simple development server
|
||||
|
||||
* `keywords` - an array of keywords used to discover your app in the npm
|
||||
- `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
|
||||
- `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
|
||||
- `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.
|
||||
- `devDependencies` - development dependencies for your package. In our case
|
||||
we have several dependencies used by webpack, which we use as a simple development server.
|
||||
|
||||
@@ -110,29 +110,28 @@ refer to the [according documentation](extend.md#apple-touch-icons).
|
||||
|
||||
### Webpack
|
||||
|
||||
The project contains a simple [webpack](https://webpack.js.org/) configuration.
|
||||
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
|
||||
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)
|
||||
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.
|
||||
This will start a Webpack development server with hot reloading of edited files.
|
||||
|
||||
To package a site for production run
|
||||
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.
|
||||
|
||||
This command will bundle up the site's JavaScript and copy over static assets to
|
||||
the newly created `dist` folder.
|
||||
|
||||
There are three files:
|
||||
|
||||
@@ -146,22 +145,22 @@ This development configuration defines the behavior of development server.
|
||||
|
||||
#### webpack.config.prod.js
|
||||
|
||||
This production configuration defines the behavior of the production build.
|
||||
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
|
||||
* tile.png
|
||||
* tile-wide.png
|
||||
- css
|
||||
- img
|
||||
- js/vendor
|
||||
- 404.html
|
||||
- favicon.ico
|
||||
- icon.png
|
||||
- icon.svg
|
||||
- index.html
|
||||
- robots.txt
|
||||
- site.webmanifest
|
||||
- tile.png
|
||||
- tile-wide.png
|
||||
|
||||
`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.`
|
||||
`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.`
|
||||
|
||||
Reference in New Issue
Block a user