docs(readme): add Mac troubleshooting tips for yarn install errors

[pepelsbey]

Summary

I discovered a few problems while installing yarn dependencies on my Mac and collected the steps required to make it work. It’s hidden in the collapsible section by default: there might be no need for troubleshooting.

Problem

Build errors while running yarn install, specifically with gifsicle, pngquant-bin, and mozjpeg.

Solution

Install additional packages via brew.

[caugner]

@pepelsbey Can you share what errors you got when running yarn install? Did you run yarn install in mdn/content or in mdn/yari? I thought these dependencies are only required when running the filecheck.

Note that in yari, you'll need to setup commit signatures, see the failing test for instructions.

[pepelsbey]

Can you share what errors you got when running yarn install

I don’t have those anymore, but I’ll try to reproduce them tomorrow by uninstalling those packages :)

Note that in yari, you'll need to setup commit signatures, see the failing test for instructions.

Yes, I’m trying to set up the GPG thing, will update the commit once it’s done

[pepelsbey]

@caugner The errors happen when I run yarn install in yari. Right next to it, there’s content with all dependencies installed. To reproduce errors, I removed the mentioned brew packages and deleted node_modules:

yarn install
yarn install v1.22.19
[1/5] 🔍  Validating package.json...
[2/5] 🔍  Resolving packages...
[3/5] 🚚  Fetching packages...
…
[3/10] ⠄ mozjpeg
[4/10] ⠂ pngquant-bin
error /Users/vmakeev/Documents/yari/node_modules/pngquant-bin: Command failed.
Exit code: 1
Command: node lib/install.js
Arguments: 
Directory: /Users/make/Documents/yari/node_modules/pngquant-bin
Output:
spawn Unknown system error -86
pngquant pre-build test failed
compiling from source
Error: pngquant failed to build, make sure that libpng is installed

Once I install pkg-config, I get another error:

[4/10] ⠁ pngquant-bin
error /Users/vmakeev/Documents/yari/node_modules/mozjpeg: Command failed.
Exit code: 1
Command: node lib/install.js
Arguments: 
Directory: /Users/vmakeev/Documents/yari/node_modules/mozjpeg
Output:
spawn Unknown system error -86
mozjpeg pre-build test failed
compiling from source
Error: Command failed: /bin/sh -c autoreconf -fiv
/bin/sh: autoreconf: command not found

Only when I install all the mentioned packages and link the libpng, I get no errors after yarn install. This is what I’d like to share in the readme.

[caugner]

Also don't forget to update the markdownlint config.

[estelle]

Documenting this in case it can help someone:

I also had to run:

sudo chown -R 501:20 "/Users//.npm"
sudo npm install punycode --save
chown package-lock.json

yarn start was working for me, even though my yarn install was failing before the fixes listed in this PR. But after running the updated commands, yarn install exits with the error:

error Error: EACCES: permission denied, unlink '/Users//Documents/owd/content/node_modules/istanbul-lib-report/node_modules/semver/LICENSE'

and yarn start fails with

Error: Cannot find module './metrics/envelope.js'

I am not sure if this is a me issue or a general issue, but thought I would share just in case it's not just me.
Setting up on a brand new MBP with Apple M3 chip, which is causing issues everywhere, not just with yarn or MDN.

I did all the above, then deleted and reinstalled the repo. The yarn install caused this error again:

error Error: EACCES: permission denied, unlink '/Users//Documents/owd/content/node_modules/babel-plugin-istanbul/node_modules/semver/LICENSE'

but uninstalling and restarting enabled me to start the environment. I hope this helps someone.

[caugner]

I'm actually not sure we should mention this here:

Suggested change

	See the [troubleshooting](#troubleshooting) section below if you run into
	problems.

Do you know if there is a way to display a TOC in the GitHub README?

[estelle]

not automatically, but, in Readme markdown, each header creates an ID for itself, all lowercase, spaces converted to dash, so a TOC can be manually created (and then manually updated if a header is edited.

I believe Onkar may be creating a script / github bot that automatically notifies via a comment that links need to be updated if a header has been updated. See the minutes from #writingdocs meeting notes for Dec 19, section 1.e.xii (Action items from the previous meeting, starting with the 12th item in the flaw bot discussion)

[estelle]

Added note: one of the markdown VSCode plugins used for /content/ includes a setting that identifies and basically rewrites TOCs. This can be considered a feature or a bug. If you start creating a TOC, it will eventually identify it as such. It will then automatically generate a markdown TOC for you. That is what you were looking for... so there is an extension to VS code that you likely have installed that does that. I assume there may even be a way to ask it to create the TOC without first having to start typing it in.

The bug part: if you want to style it your own way, not include EVERYTHING in your TOC, or in any way alter it from the plugin's preference, it rewrites it to their preference. I used it for a TOC for content within an H2 on a long document and had to toggle the VS Code extension off to enable removing the subheadings from other sections.

As this is a TOC for a README file, the extension is probably good as is. If you alter the extension for /content/, where we use underscores instead of dashes between words in anchor links, you would then have to turn the extension off, after the TOC is created, to switch between underscores and dashes without having the plugin "fix" it for you.

I hope that helps.

[pepelsbey]

I'm actually not sure we should mention this here:

We have quite a long readme, I personally missed the troubleshooting while reading the installation instructions. TOC wouldn’t help, either. I’d keep this note for people like me 😄

[caugner]

Thanks @pepelsbey!