Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Jan 23, 2024
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ceb2b68
docs: add troubleshooting for yarn installation
pepelsbey Nov 8, 2023
e28420c
Move tips to troubleshooting section
pepelsbey Dec 15, 2023
76f0dac
Please MD linter
pepelsbey Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ app locally. Do this like so:
cd yari
yarn install

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

Comment on lines +44 to +46
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

@estelle estelle Dec 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@pepelsbey pepelsbey Jan 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 😄

Now copy the `.env-dist` file to `.env`:

cp .env-dist .env
Expand Down Expand Up @@ -294,3 +297,27 @@ The default server port `:5042` might be in use by another process. To resolve
this, you can pick any unused port (e.g., 6000) and run the following:

echo SERVER_PORT=6000 >> .env

### Yarn install errors

If you get errors while installing dependencies via yarn on a Mac, you may need
to install some additional packages. Check the error message for the package
name causing the problem.

1. First, install [brew](https://brew.sh/) if you haven’t already

1. To fix problems with `gifsicle`:

brew install automake autoconf libtool

1. To fix problems with `pngquant-bin`:

brew install pkg-config

1. To fix problems with `mozjpeg`:

brew install libpng sudo ln -s
/opt/homebrew/Cellar/libpng/1.6.40/lib/libpng16.a /usr/local/lib/libpng16.a

You may need to adjust the path to `libpng16.a` depending on the version of
`libpng` you have installed.