[docs] improve experience for users who aren't on Mac OS

[marcysutton]

Summary

Some of the docs aren't effectively serving users who aren't on Mac platforms, such as Windows or Ubuntu (Linux). Here are some pages in particular that could use an audit:

• https://www.gatsbyjs.org/tutorial/part-zero/
• https://www.gatsbyjs.org/docs/preparing-your-environment/
• https://www.gatsbyjs.org/docs/gatsby-on-windows/
• https://www.gatsbyjs.org/docs/gatsby-on-linux/ (stub with "TODO" should be removed since it has content)

There was also a suggestion from @KyleAMathews:

We could pair this with some error recovery testing that we’ve been discussing in @gatsbyjs/core

Related issues

• Issue with setting up Gatsby, VS code, and ubuntu  #15473
• run Gatsby through WSL2 #15163
• GraphQL Error There was an error while compiling your site's GraphQL queries. Error: RelayParser: Encountered duplicate defintitions for one or more documents: each document must have a unique name. Duplicated documents: - mntDUbuntuDevGatsbyTestGatsbyTutorialFourSrcPagesAboutJs1097489062 #15530

Motivation

We want all Gatsby users to feel supported and successful when they go through Gatsby docs and tutorials!

cc @amberleyromo

[marcysutton]

Additional related feedback was given for Tutorial Part Zero through the feedback widget on Gatsbyjs.org. Specifically:

"The entire part zero assumes mac and there is no steps for Windows users."

"Not great for Windows users since Homebrew is for a mac. Looks like it can be done by installing Win Subsystem for Linux and then Linux. However that's a lot of installing to do just for one program. Is it possible to use Gatsby without Homebrew? Thanks"

"node install created a lot of errors, was easier to install via the node.js website than using the Homebrew instructions."

"Under the point "0. Set Up Your Developement Environment > Install Homebrew for Node.js" you write that homebrew could be set up for windows (although there are no further instructions, everything seems to be tailored to macOS only) - but that's not the case. That's unfortunately rather discouraging, when the first step is already not applicable to my operating system :(."

The homebrew instructions were added with #10398, based on a recommendation. We could consider backing out of that decision and going back to the Node.js install instructions.

[narration-sd]

@marcysutton By my experience, you'd be ok to go with the 'install nodejs' instructions, just taking care if the lts or 'current' = beta version is ok or required for present Gatsby.

Actually, this should/would have been done to install npm itself...

[marcysutton]

Thanks @narration-sd! That's what I'm finding too–but we want to start at absolute step 0 in case someone doesn't already have Node or npm installed. The Nodejs.org instructions are definitely easier so far than WSL/homebrew.

[eclectic-coding]

I recently switched from Mac to Ubuntu and am available for any testing related to that platform.

[ghost]

@marcysutton Happy to audit and improve the gatsby-on-windows page. I come from mac environments but recently setup a windows environment very easily that is playing nicely with no issues. Let me know if you'd like me to write up a zero to hero windows setup guide for review. 😃

Additionally I think we could rewrite the part-zero page to be more inclusive of non mac environments from the start and have an obvious content path to each of the Mac, Windows, Linux specific environment setup guides. Could take a stab at that as well!

[marcysutton]

@grantmoran that sounds amazing! It's been on my list but I haven't gotten to it yet, so we'd love any contributions. There's also some info on writing tutorials in the Gatsby Style Guide that might be useful. Thanks so much!

[ghost]

@marcysutton Great, I'll make a submission sometime over the weekend then. Happy Friday!

[ghost]

I've got a guide almost wrapped up. Was a little delayed due to work. Anyone have a windows box/setup that wants to run through it? Should I just create a PR with it?

[marcysutton]

I use Parallels and the free VMs from Microsoft. I used to use VirtualBox which is also free, but it stopped working for me a few months ago so I got a Parallels license. I'd be happy to help you test it, but I'll be on vacation until August 16th. Maybe someone else could help in the meantime?

[eclectic-coding]

I have Windows 10 pro in VMWARE VM on a Ubuntu/System76 laptop ... If a dedicated Windows user doesn't volunteer I would be willing to run it through the paces if need be.

[kushthedude]

@marcysutton @JohnAlbin I would like to help in it

[marcysutton]

@grantmoran how's that guide coming? I'm back from vacation now so happy to review it: thanks for your patience. We have lots of interest on this which is fantastic! @kushthedude i'd say let's wait to hear back from Grant first, so your efforts and time are well spent.

[kushthedude]

👍

[marcysutton]

It's been a while and we haven't heard back from @grantmoran, so it's time for us to keep moving forward. Consider this issue open for anyone to work on; thanks for all the interest!

[1qk1]

Hi! I will be happy to take this on, I'm both a windows and linux user, I can update/write the instructions for both OSes!

[marcysutton]

That sounds amazing, @1qk1! Let us know if you have any questions. Here are some resources that may help:

• https://www.gatsbyjs.org/contributing/gatsby-style-guide/
• https://www.gatsbyjs.org/contributing/docs-templates/#tutorials

[1qk1]

Thanks @marcysutton!

I have a question, on "Gatsby on Windows" and "Gatsby on Linux" pages, there are instructions about installing build-essential and windows-build-tools. I have set up gatsby a couple times on each OS and never have to go through these steps, just install Node, git, Gatsby and I'm done, are these necessary or were they needed for an older gatsby version and never got removed?

Also I have finished the part-zero page with instructions for all Mac, Windows and Linux. If you (or anyone) have any thoughts or have seen something that can be improved in the docs I would appreciate hearing it.

[mi-na-bot]

Using homebrew on Linux is not great. I strongly prefer using nvm for development machines, and whatever package manager instruction that is appropriate from this list for environments that should be updated automatically:
https://nodejs.org/en/download/package-manager/

[eclectic-coding]

Actually, Homebrew is MacOS only. I totally agree, using NVM on Linux is the best way to manage Node versions

[mi-na-bot]

Homebrew has (had?) aspirations to be useful in Linux as well and definitely can be installed there. The instructions to use homebrew are probably guiding some Linux users to install it however ill advised.

https://docs.brew.sh/Homebrew-on-Linux

[rahsheen]

Good day, folks.

I'm just curious if work is still continuing on this. Specifically, I was helping someone who was using WSL on Windows and the docs led him to believe he needed Homebrew to install Node, which he likely already had. He's still trying to figure out how to disentangle himself, unfortunately.

In short, the current instructions are a bit misleading and seem to indicate Homebrew as a requirement.

I'd be willing to help if needed.

Thanks.

[LorenAmelang]

I just installed Gatsby from scratch on Win 10, trying to follow https://www.gatsbyjs.org/tutorial/part-zero/ and have more comments than seem appropriate for the feedback box.

Install Homebrew for Node.js

This led down a rabbit hole of searching for how to do it in Windows, which seemed to involve installing a virtual environment just to run the node.js installer. I've had node.js on other machines and knew I could just go to https://nodejs.org/en/download/ and use the installer from there. It installs Chocolatey to do the node install in one automated step.

PS C:\Users\loren> node --version
v12.13.1
PS C:\Users\loren> npm --version
6.12.1

Using the Gatsby CLI

"npm install -g gatsby-cli" seemed to complete successfully.

It did produce some warnings I don't understand, since I'd just installed the latest node. Maybe these are Gatsby issues?

npm WARN deprecated core-js@2.6.10: core-js@<3.0 is no longer maintained and not recommended for usage due to the number of issues. Please, upgrade your dependencies to the actual version of core-js@3.

npm WARN ink@2.6.0 requires a peer of @types/react@>=16.8.0 but none is installed. You must install peer dependencies yourself.
npm WARN auto-bind@3.0.0 requires a peer of @types/react@>=16.8.0 but none is installed. You must install peer dependencies yourself.

This part of the process led to another rabbit hole of searching:

Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at
https:/go.microsoft.com/fwlink/?LinkID=135170.
Do you want to change the execution policy?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): y

Telling me I needed to change policy was good, but how to do it was not obvious! I eventually found the solution here:
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-6

One simple CLI command, once you know what to type:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
(That may be specific to PowerShell, Command Prompt may behave differently!)

Create a Gatsby site

Here is where a single clue could have saved me from the deepest rabbit hole yet. Before you type:
PS C:\WINDOWS\system32> gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world

BE SURE TO CD TO A USER DIRECTORY WHERE YOU WANT YOUR PROJECT SAVED!

The command above put the hello-world project in C:\WINDOWS\system32, where it is subject to lots of arcane "security" limitations.

It also displayed these warnings:

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.9 (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.9: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.1.2 (node_modules\chokidar\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.1.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

I suspect "darwin" means it is intended for MacOS. That did not seem to be the real problem, though... The problem was that PowerShell could not see the hello-world folder with any command, whether run as Administrator or User. Command Prompt saw it normally, but could not create new folders or files in the system folder.

I did not want the project stuck there in any case. I quit Git, Explorer-moved the hello-world folder to my intended user folder, and things then worked well!

The gatsby develop command stops at:

success Building development bundle - 5.204s

And my site is live!

But apparently it knows if you have the site open in your browser - Ctrl+C is ignored...

Once I thought to close the browser page, Ctrl+C worked:

Terminate batch job (Y/N)? y

It would be nice if the gatsby develop command paused with something like:
"Paused. Close your browser window to continue, then use Ctrl+C to quit."

At least for the newbie hello-world site!

1qk1 commented on Oct 5

I have a question, on "Gatsby on Windows" and "Gatsby on Linux" pages, there are instructions about installing build-essential and windows-build-tools. I have set up gatsby a couple times on each OS and never have to go through these steps, just install Node, git, Gatsby and I'm done, are these necessary or were they needed for an older gatsby version and never got removed?

As part of the standard Node install:

Chocolatey upgraded 15/15 packages.
See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).
Upgraded:

• visualstudio2017buildtools v15.9.17.0
• dotnetfx v4.8.0.20190930
• visualstudio2017-workload-vctools v1.3.2
• visualstudio-installer v2.0.1
• vcredist140 v14.23.27820
  ...

A reboot was recommended.

I'd be happy to work with someone more knowledgeable on integrating this into the tutorial, but I'm unsure of some parts of it and don't want to just go hack the source...

[narration-sd]

Just a quick comment here as too tied in other things, but it seems very worthwhile to recommend NOT to involve the mentioned Chocolatey in any of this. Chocolatey is a real mess, and leaves messes. You end up with quite questionable things on your Windows machine, at least I thought so, in order to use it. The documentation is odd. Uninstalling and getting rid of the parts is particularly questionable, as I remember it. I've just used npm in normal ways for anything with Gatsby. You get that, and node, by installing a current version of Node itself, from their webpage. That's it, and it works...

…

------ Original Message ------ From: "LorenAmelang" <notifications@github.com> To: "gatsbyjs/gatsby" <gatsby@noreply.github.com> Cc: "Narration SD" <narrationsd@gmail.com>; "Mention" <mention@noreply.github.com> Sent: 12/1/2019 2:10:56 PM Subject: Re: [gatsbyjs/gatsby] [docs] improve experience for users who aren't on Mac OS (#15529)

I just installed Gatsby from scratch on Win 10, trying to follow https://www.gatsbyjs.org/tutorial/part-zero/ and have more comments than seem appropriate for the feedback box. Install Homebrew for Node.js This led down a rabbit hole of searching for how to do it in Windows, which seemed to involve installing a virtual environment just to run the node.js installer. I've had node.js on other machines and knew I could just go to https://nodejs.org/en/download/ and use the installer from there. It installs Chocolatey to do the node install in one automated step. PS C:\Users\loren> node --version v12.13.1 PS C:\Users\loren> npm --version 6.12.1 Using the Gatsby CLI "npm install -g gatsby-cli" seemed to complete successfully. It did produce some warnings I don't understand, since I'd just installed the latest node. Maybe these are Gatsby issues? >npm WARN deprecated ***@***.***: core-js@<3.0 is no longer >maintained and not recommended for usage due to the number of issues. >Please, upgrade your dependencies to the actual version of ***@***.*** > >npm WARN ***@***.*** requires a peer of @types/react@>=16.8.0 but none >is installed. You must install peer dependencies yourself. >npm WARN ***@***.*** requires a peer of @types/react@>=16.8.0 but >none is installed. You must install peer dependencies yourself. > This part of the process led to another rabbit hole of searching: >Execution Policy Change >The execution policy helps protect you from scripts that you do not >trust. Changing the execution policy might expose you to the security >risks described in the about_Execution_Policies help topic at >https:/go.microsoft.com/fwlink/?LinkID=135170. >Do you want to change the execution policy? >[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help >(default is "N"): y > Telling me I needed to change policy was good, but how to do it was not obvious! I eventually found the solution here: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-6 One simple CLI command, once you know what to type: >Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser >(That may be specific to PowerShell, Command Prompt may behave >differently!) > Create a Gatsby site Here is where a single clue could have saved me from the deepest rabbit hole yet. Before you type: PS C:\WINDOWS\system32> gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world BE SURE TO CD TO A USER DIRECTORY WHERE YOU WANT YOUR PROJECT SAVED! The command above put the hello-world project in C:\WINDOWS\system32, where it is subject to lots of arcane "security" limitations. It also displayed these warnings: >npm WARN optional SKIPPING OPTIONAL DEPENDENCY: ***@***.*** >(node_modules\fsevents): >npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for ***@***.***: wanted {"os":"darwin","arch":"any"} (current: >{"os":"win32","arch":"x64"}) >npm WARN optional SKIPPING OPTIONAL DEPENDENCY: ***@***.*** >(node_modules\chokidar\node_modules\fsevents): >npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for ***@***.***: wanted {"os":"darwin","arch":"any"} (current: >{"os":"win32","arch":"x64"}) > I suspect "darwin" means it is intended for MacOS. That did not seem to be the real problem, though... The problem was that PowerShell could not see the hello-world folder with any command, whether run as Administrator or User. Command Prompt saw it normally, but could not create new folders or files in the system folder. I did not want the project stuck there in any case. I quit Git, Explorer-moved the hello-world folder to my intended user folder, and things then worked well! The gatsby develop command stops at: >success Building development bundle - 5.204s > And my site is live! But apparently it knows if you have the site open in your browser - Ctrl+C is ignored... Once I thought to close the browser page, Ctrl+C worked: >Terminate batch job (Y/N)? y > It would be nice if the gatsby develop command paused with something like: "Paused. Close your browser window to continue, then use Ctrl+C to quit." At least for the newbie hello-world site! 1qk1 commented on Oct 5 >I have a question, on "Gatsby on Windows" and "Gatsby on Linux" pages, >there are instructions about installing build-essential and >windows-build-tools. I have set up gatsby a couple times on each OS >and never have to go through these steps, just install Node, git, >Gatsby and I'm done, are these necessary or were they needed for an >older gatsby version and never got removed? > As part of the standard Node install: >Chocolatey upgraded 15/15 packages. >See the log for details >(C:\ProgramData\chocolatey\logs\chocolatey.log). >Upgraded: > >visualstudio2017buildtools v15.9.17.0dotnetfx >v4.8.0.20190930visualstudio2017-workload-vctools >v1.3.2visualstudio-installer v2.0.1vcredist140 v14.23.27820 >... A reboot was recommended. I'd be happy to work with someone more knowledgeable on integrating this into the tutorial, but I'm unsure of some parts of it and don't want to just go hack the source... — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#15529?email_source=notifications&email_token=AAB4RCLKEBQT3CBFVCOLPXTQWQY7BA5CNFSM4H66TXSKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEFRXI2I#issuecomment-560165993>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAB4RCOGUS5BQW7SVPSMOC3QWQY7BANCNFSM4H66TXSA>.

[LorenAmelang]

@narration-sd

it seems very worthwhile to recommend NOT to involve the mentioned Chocolatey in any of this.

Your thoughts match mine well. I definitely didn't want to install a VM just to install Homebrew so it could install Node. I saw Chocolatey recommended as the alternative, but I didn't want that either. I know I've installed Node on other machines in the past without any of this complication. So I went directly to https://nodejs.org/en/download/ and used the Windows Installer from there.

I was quite surprised to see Chocolatey pop up to do most of the installation. I guess somebody has to install all those build tools... Maybe I should have downloaded just the individual binaries instead of the Installer? But in the past the Windows Installer didn't identify itself as Chocolatey...

Interesting to see
https://chocolatey.org/packages/nodejs.install

chocolatey
Software Author(s):
Node.js Foundation

Maybe it was the installer all along, and they have just given it a public identity?

What really makes a mess is if you install a Gatsby project with npm and then try to use yarn to add plugins! Multiple screenfulls of versioning errors! The Gatsby web community seems to use them interchangeably, without explaining this issue even in the tutorial/part-zero.

[LorenAmelang]

To continue my newbie rant:

I installed the starter blog:
gatsby new tagtest https://github.com/gatsbyjs/gatsby-starter-blog

Your new Gatsby site has been successfully bootstrapped. Start developing it by running:
cd tagtest
gatsby develop

That much worked as expected.

I tried to install tags:
https://github.com/rmcfadzean/gatsby-pantry/tree/master/packages/gatsby-plugin-tags

Gatsby plugin to automatically create index pages for tagged content
Install
yarn add gatsby-plugin-tags

That failed with hundreds of version errors. I learned you can't intermix npm with yarn! So I tried again:

npm install gatsby-plugin-tags

npm WARN rm not removing C:\Users\loren\Documents\Psychoros\Gatsby Test\tagtest\node_modules.bin\rimraf.cmd as it wasn't installed by C:\Users\loren\Documents\Psychoros\Gatsby Test\tagtest\node_modules\rimraf
(Plus 13 more WARN instances.)

But it said it was installed. Most plugins say you need to edit the gatsby-config.js file in the website’s root directory, but this one didn't offer an example.
So I improvised this from the instructions for a different plugin:

` {
  resolve: "gatsby-plugin-tags",
  options: {
    template: `${__dirname}/src/templates/post.jsx`
  },

ERROR #85901 GRAPHQL
ERROR #11321 PLUGIN
TypeError: Cannot read property 'allMarkdownRemark' of undefined
--> failed createPages - 0.231s

boundActionCreators is deprecated. Please use actions instead. For migration instructions, see https://gatsby.dev/boundActionCreators
Check the following files:
tagtest/node_modules/gatsby-plugin-sharp/gatsby-node.js
(and 19 more, none of them the plugin I'm trying to install.)

pathContext is deprecated. Please use pageContext instead. For migration instructions, see https://gatsby.dev/pathContext
Check the following files:⠀
tagtest/node_modules/gatsby/cache-dir/commonjs/page-renderer.js
(and 4 more, none of them mine.)
⠀
success Building development bundle - 34.004s

The original starter pages still appear, but obviously the tags part is broken. Maybe my yarn disaster left something bad in the project? Maybe some of those version warnings really matter? Maybe I'm doing something newbily stupid?

I continually see warnings like:

npm WARN deprecated core-js@2.6.10: core-js@<3.0 is no longer maintained and not recommended for usage due to the number of issues. Please, upgrade your dependencies to the actual version of core-js@3.

I've found these, but no clue how to see what core-js version I really have:

npm view gatsby version
2.18.5
gatsby -v
Gatsby CLI version: 2.8.14

Some of these may be actual bugs, not just documentation insufficiencies. Is there some other place I should be sharing them?

[laurieontech]

The first of these pages is updated! This is a guide for setting up with Linux and WSL. https://www.gatsbyjs.org/docs/gatsby-on-linux/

[laurieontech]

With the updates to step zero and gatsby windows and linux pages I'm going to close this issue.
Other issues can be more targeted surrounding the documentation necessary.

[LorenAmelang]

With the updates to step zero and gatsby windows and linux pages I'm going to close this issue.
Other issues can be more targeted surrounding the documentation necessary.

Thank You Laurie! Much good information:
https://www.gatsbyjs.org/docs/gatsby-on-windows/

But Python 2.7 still???

[laurieontech]

@LorenAmelang Would love you to open an issue to update that specifically! Thanks for catching it.