public folder about docsy-example HOT 5 CLOSED

Hi @MAlexGR - It should just be "public" - Here's a really simple netlify.toml that i use with my example template https://github.com/gwatts/mostlydocs/blob/main/netlify.toml

from docsy-example.

Hi @gwatts! Thank you for your comment.

Sorry, I wasn't clear. I did follow the steps given here and created a locally working site. I then connected this local repo with a GitHub one. Then I tried to deploy the site throught the chain (my) PC - GitHub - Netlify, again following the steps given here.

From there nothing worked! Netlify was unable to create the site, giving me various errors. I tried to configure the building process either directly on Netlify or through a netlify.toml file (almost the same as the one you suggested and always according to the previous instructions). Nothing!

I remembered that Hugo creates a public folder and puts the html files it creates, in it. This folder did not exist on the example site. Also I can't find any html file at all. So, I guess, Netlify fails because it can't find neither a public folder nor html files. Am I right?

Does the creation process takes place at server site (Netlify) as in my laptop? To be honest, I don't understand how the "submodule" concept for Docsy works and I blindly followed the instructions. Can you give me an idea how this chain proccesses work? What sould I do (as I said, the netlify.toml you propose doesn't make the difference)?

Thank you.

Alex

from docsy-example.

I solved it!

The whole thing was about the PostCSS. According to user guide's "getting started" section, I had to install PostCSS in order to "... build or update your site’s CSS resources ...". I thought I had taken the necessary steps to install it but in the end it was not so.

What is not mentioned in the above section is that the installation of postcss includes the creation of a "package.json" file, a "package-lock.json" file and a "node_modules" folder with a set of subfolders in it. All this are created automatically and all this are required by Netlify to build the site! The fun part is when I looked carefully at the log of the failed version on Netlify, I came across warnings and errors that I just remembered were similar to what I encountered when I tried to install PostCSS (about a week ago). I spotted the problem by accident!

To be brief, I would suggest you fill in the following in the user guide, in the above mentioned section:

1. install NodeJS on your system
2. in the working directory:

   1. give the command npm init, this will create the "package.json" file. This simple step makes the difference!

   2. install autoprefixer with

      sudo npm install -D --save autoprefixer

      If you see warnings like

      '[email protected] requires a peer of (some package) but none is installed. You must install peer dependencies yourself",

      use the command npm install --save-dev "some package". Do not forget quotes and repeat for every dependency!

   3. install postcss-cli with

      sudo npm install -D --save postcss-cli.

      Here you will probably face warnings like:

      npm WARN deprecated [email protected]: Please update to v 2.2.x

      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 [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

      From a quick search I made, I found that these are related with MacOS and you can safely ignore them (again, if you are using Linux).

   4. The last two steps will create the rest of files. Now, rebuild the site with hugo server (I'm not sure if this step is necessary but I made it).

   5. Continue your work

I hope these help other users!

Alex.

from docsy-example.

@MAlexGR Oh great! So glad you got it figured out and thanks for updating the issue - That's a great observations about the docs - I think the docs assume that you're starting from this template that already includes the package.json file, in which case npm install should be all you need (though the docs don't make that clear as linked above)

The "Use the Docsy theme in your own site " doesn't mention the npm steps at all though, so i that's probably a good spot to focus on too

@LisaFC is the docs (and Docsy) guru; any thoughts?

from docsy-example.

So there's a general prereqs section at the top that does say that you need to do the npm steps for any of the usage options (and will soon also include our new exciting Docker container option for people who don't want to have to install postCSS, hugo, etc.), but yes, the Docsy theme section doesn't mention the npm init step - that's a really good spot! I'll try to clarify the docs a bit to make it clear which prereqs are necessary if you're using the template site versus just using the theme.

from docsy-example.