/cc @geriom @deining @LisaFC @emckean - as mentioned in the opening comment, let's discuss Hugo modules and this PR during the PSC meeting. Thanks.

I did a quick partial test and I don't believe that this will break #871.

All: The only extra step required on the part of existing users, if/once this is merged, would be this extra command after fetching the docsy submodule:

$ (cd themes/docsy && npm install)  

Or, for projects that are already using NPM, then can add the following script to run the docsy npm install at the same time as the project's:

  "scripts": {
    ...
    "postinstall": "cd themes/docsy && npm install",
    ...
  },

The cleanest approach might be to install docsy as an NPM package, which would be done something like this:

$ npm install github:chalin/docsy#chalin-bs+fa-via-npm-2022-02-14 --save-dev

And then project's wouldn't have to run any extra commands or NPM scripts. But this isn't an approach that I want to fully promote yet since I haven't worked out the details. (And I want to get the Hugo module PR in first.)

Tested it, and could make it work too, after some tweaking.

Experiences/thoughts:

1. I started off with:

git clone -b chalin-bs+fa-via-npm-2022-02-14 https://github.com/chalin/docsy.git docsy-npm

Since my checkout directory was docsy-npm, I had to adjust userguide/config.toml in that way: theme = "docsy-npm".

2. Currently, we do have two separate npm-related blocks in README.md:

$ npm install --save-dev autoprefixer
$ npm install --save-dev postcss-cli

and

$ git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
$ cd docsy/userguide/
$ npm install
$ npm run serve

I needed both to get the site up and running. Can we bring these together?

3. Question/Proposal: do we want the npm script to pull in the latest version of hugo as well? We are doing this already for the Netlify deploy, AFAICS. There are several choices for pulling in hugo, I tried out hugo-installer yesterday, and it worked great for me.

2. Currently, we do have two separate npm-related blocks in README.md:

$ npm install --save-dev autoprefixer
$ npm install --save-dev postcss-cli

and

$ git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
$ cd docsy/userguide/
$ npm install
$ npm run serve

I needed both to get the site up and running. Can we bring these together?

This is an alternative to those steps. I tried it on a clean linux VM with only node installed, nothing else.

Doing npm install and npm run serve gets the site up and running, no need to neither pull the submodules nor to install go or hugo. This is way more user friendly imo.

After we get this and #871 merged we should revisit our docs and make a decision about how we present the different alternatives.

Thank you both @deining and @geriom for your feedback.

Since my checkout directory was docsy-npm, I had to adjust userguide/config.toml in that way: theme = "docsy-npm".

Right, that's to be expected if checked out to another folder name.

2. Currently, we do have two separate npm-related blocks in README.md

Yes, but those two blocks serve different purposes and cater to two different audiences: the first is for docsy users and the second for docsy contributors.

I agree with @geriom that the README seems ok for now. (Note that I just pushed a commit to remove the --recurse-submodules flag even if it was a harmless noop).

3. Question/Proposal: do we want the npm script to pull in the latest version of hugo as well?

The project is already fetching the version of hugo we need via the hugo-extended package. I'm unsure what more you wanted. (Thanks for the reference to the hugo-installer, I didn't know about it.

@geriom wrote:

After we get this and #871 merged we should revisit our docs and make a decision about how we present the different alternatives.

Agreed.