Skip to content
Permalink
Browse files

Docs: Improvements and tweaks

* Mention x64 clearly
* Point users to troubleshoot guide in bug template
* Normalize `node` to `Node.js`

- - - - - - - - - - - - - - - - - - - - - - - - - -

Fix #1786
  • Loading branch information...
molant committed Mar 28, 2019
1 parent 695a61e commit 2abb707a3052b09a41ed07f8b5574bd909f65a7d
@@ -9,9 +9,12 @@ labels: "type:bug"
Hi there 👋
Thanks for taking the time to make webhint better! Before
opening a new issue please make sure to search in the existing
ones (even closed!) as they might contain information about
workarounds, resolution, or progress updates.
opening a new issue please take a look at the troubleshoot
guide:
https://webhint.io/docs/user-guide/troubleshoot/summary/
and make sure to search the existing ones (even closed!)
as they might contain information about workarounds,
resolution, or progress updates.
-->

@@ -4,7 +4,7 @@

If you want to have an idea of what `webhint` does and you
have an updated version of `npm` (v5.2.0) and [Node.js LTS (v8.9.2)
or later, x64 version recommended][https://nodejs.org/en/download/current/]
or later, x64 version recommended](https://nodejs.org/en/download/current/)
you can use the following command:

```bash
@@ -23,19 +23,18 @@ You can also install it as a `devDependency` if you prefer not to
have it globally (which is the team's preferred option).

**NOTE**: If you run into any issues during the install process
please check the [troubleshoot section](./troubleshoot/summary.md).

please check the [troubleshoot section](./docs/user-guide/troubleshoot/summary.md).

### Further reading

Now that you have `webhint` up and running, it is time to learn a bit
more about the different pieces:

* [Configurations](./concepts/configurations.md)
* [Hints](./concepts/hints.md)
* [Connectors](./concepts/connectors.md)
* [Formatters](./concepts/formatters.md)
* [Parsers](./concepts/parsers.md)
* [Configurations](./docs/user-guide/concepts/configurations.md)
* [Hints](./docs/user-guide/concepts/hints.md)
* [Connectors](./docs/user-guide/concepts/connectors.md)
* [Formatters](./docs/user-guide/concepts/formatters.md)
* [Parsers](./docs/user-guide/concepts/parsers.md)

## Contributing to webhint

@@ -3,14 +3,15 @@
## Getting started

If you want to have an idea of what `webhint` does and you
have an updated version of `npm` (v5.2.0) and [Node LTS (v8.9.2)
or later][nodejs] you can use the following command:
have an updated version of `npm` (v5.2.0) and [Node.js LTS (v8.9.2)
or later, x64 version recommended][nodejs] you can use the
following command:

```bash
npx hint https://example.com
```

Alternatively, you can install it locally with:
Alternatively, you can install it globally with:

```bash
npm install -g --engine-strict hint
@@ -105,4 +106,4 @@ about the different pieces:

[nodejs]: https://nodejs.org/en/download/current/
[web recommended]: https://github.com/webhintio/hint/blob/master/packages/configuration-web-recommended/index.json
[ssl labs]: https://webhint.io/docs/user-guide/hints/hint-ssllabs/
[ssl labs]: https://webhint.io/docs/user-guide/hints/hint-ssllabs/
@@ -6,7 +6,7 @@ the server configuration.

There are some assumptions though:

* The site is static. If you are using node with iisnode, ASP.NET, etc.
* The site is static. If you are using Node.js with iisnode, ASP.NET, etc.
you will have to add the required configuration (but most of this
configuration should still be valid).
* All the static assets are in the folder `dist/static`.
@@ -1,9 +1,11 @@
# Common issues when installing or running webhint

While the team has made progress in removing the possibilities of
running into issues while installing the project, you could still
run into some issues especially when dealing with binary packages
(`canvas` and `iltorb` are the currently used ones).
The team currently supports webhint on the latest 2 LTS and
current branch. While it is possible to run it on x86 version of
Node.js, it is recommended to use the x64 one. The reason is that
the project still uses some binary packages (`canvas` and `iltorb`)
and in most cases there are precompiled versions for x64 and thus
avoiding to compile anything.

This section contains the most commons issues reported by users with
potential fixes. If you run into something that is not documented
@@ -17,7 +19,7 @@ native modules:

> gyp ERR! stack Error: Can't find Python executable "python"
Newer versions of node (10+) on Windows ask users if they want the installer
Newer versions of Node.js (10+) on Windows ask users if they want the installer
to automatically install the required dependencies. You can use this method
or you can also install the [`windows-build-tools`][windows build tools].
From an **Elevated PowerShell** run the following:
@@ -31,14 +33,14 @@ npm install --global windows-build-tools
Starting on `connector-jsdom v1.1.0`, `canvas` was changed to be an optional
dependency so while you might see some issues during the installation if the
binary is not available for download, the overall process should finish and
you should be able to execute `webhint` using the `jsdom` connector. The only caveat
is that images will not be downloaded.
you should be able to execute `webhint` using the `jsdom` connector. The only
caveat is that images will not be downloaded.

This error happens more often:

* when there is a new release of node and precompiled binaries for `canvas`
* when there is a new release of Node.js and precompiled binaries for `canvas`
are not yet available.
* if you are running node x86 on Windows. The recommendation is to switch to
* if you are running Node.js x86 on Windows. The recommendation is to switch to
x64 as [it is unlikely there will be x86 binaries any time soon][canvas x86].

You can also compile it yourself by following the [instructions][canvas compile].
@@ -53,7 +55,7 @@ dependency `canvas` throws an `EACCES`. This [issue][permission
issue] was resolved adopting the recommended solution. You can find
detailed steps on how to change the npm default directory [here][npm
change default directory]. According to [npm’s documentation][npm use
package manager], if you have node installed using a package
package manager], if you have Node.js installed using a package
manager like [Homebrew][homebrew] or [nvm][nvm], you may be able to avoid
the trouble of messing with the directories and have the correct
permissions set up right out of the box. As a result, you will not

0 comments on commit 2abb707

Please sign in to comment.
You can’t perform that action at this time.