Add a troubleshooting section.

[gauravgahlot]

Description

The PR adds a troubleshooting section to the README.

It also adds a solution for the following commonly faced error:

Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache

I also logged an issue for the same problem: #100

Signed-off-by: Gaurav Gahlot [email protected]

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[gauravgahlot]

@googlebot I signed it!

[LisaFC]

This is great but I think the solution is a little too specific in terms of the approach - both in terms of how to install and how to run Hugo (I think being able to install the extended version hugo via npm is extremely new, and I think most users run hugo directly). I'll add some suggestions.

I will definitely add installing Hugo via npm to the user guide, thanks for letting me know about that!

[LisaFC]

I think from this line down we've moved out of the realm of troubleshooting (or even anything Docsy-specific) and just telling users how to run hugo using npm and their package.json file, which may not be the preferred approach of all our users.

[LisaFC]

This is still very useful content though so I'm going to add it to our user guide rather than having it here.

[LisaFC]

This error occurs if you have not installed the extended version of Hugo. See our user guide for instructions on how to install Hugo.

[LisaFC]

See google/docsy#434

[gauravgahlot]

See google/docsy#434

I see the PR merged. What happens to this one now?

[LisaFC]

See google/docsy#434

I see the PR merged. What happens to this one now?

So the PR is in to the actual user guide for Docsy - I still think it's useful to have the troubleshooting info in the example site README as well, we can just cut it down a bit. So if you change line 111 as I suggested, then delete everything from there onwards, we can merge this in to the README.

Sorry if that was confusing!

[gauravgahlot]

@LisaFC I think I messed up. I forgot to pull your commit and force pushed the branch.
Can you please apply your changes again?

Sorry for the trouble.

[LisaFC]

No problem!