User guide: adding instructions on how to use and update docsy as hugo module

[deining]

Instructions on how to make use of Docsy as hugo module, as submitted via #801.
More or less a complete rewrite of the chapters Getting started (now: Installation) and Updating Docsy (now: Update or Conversion of Docsy Theme) from the user guide. Given links point to the preview of the chapters on Netlify. Enjoy reading!

[LisaFC]

Oh wow, this is amazing work!!! I like that we give users all the possible setup options so they can get started using their preferred workflow. I'll need to do a detailed review but will try to get to that over the next week or so.

[LisaFC]

@emckean @chalin @geriom PTAL as well - I think we may need to add a setup overview and rephrase some bits but overall this is looking good.

@deining am I reading it correctly - can users just choose between the Hugo module setup and our existing setup flows without breaking anything?

[deining]

@deining am I reading it correctly - can users just choose between the Hugo module setup and our existing setup flows without breaking anything?

Yes, absolutely.

I just made a test to verify: I cloned the docsy example, updated the submodule and ran hugo server for a site preview. Then I turned both the example site and the docsy theme into a hugo module and fetched the dependencies bootstrap and Font-Awesome. Afterwards I still could run the site preview successfully. This makes me very confident, that for existing sites, we won't break anything. That also means that no one is forced to to turn his installation into a module to be able to get docsy updates. Even with modules in place, existing sites can pull in latest changes from docsy and continue using their sites as before.

That said, I wouldn't recommend (though it is certainly doable) switching back and forth between hugo module and git submodule appraoch. To be clear here: I envision that the hugo module approach becomes the de facto standard for new installations. Existing sites can convert their sites (which is really easy IMHO) but they don't have to.

Another thought: too many installation options might be overwhelming for first time docsy, so if we agree that the module approach is the new standard, I ask myself, whether we shouldn't discard the sub section Cloning GitHub Repo (Traditional) completely. That said, if you decide to leave it in place, I can live with that.

[deining]

Oh wow, this is amazing work!!!

Glad to hear you like it.

I like that we give users all the possible setup options so they can get started using their preferred workflow.

Having a lot of options is good, but might be overwhelming for novices. I'm open for discussion here.

I'll need to do a detailed review but will try to get to that over the next week or so.

Great!

As mentioned in #801, my PR is not ready for testing, I wish it were, I guess this would help you with your review, too.
Therefore, you could do me a favour by taking the folllowing actions:

• create a new branch feature-hugo-module in the docsy repo, branching from HEAD at master.
• merge Bump docsy theme to latest version docsy-example#155

I will then resubmit #801 on the newly created feature-hugo-module branch and bring it in a testable state. All further work could then happen on this feature branch and once we are done, you could merge this branch into master.

[LisaFC]

Another thought: too many installation options might be overwhelming for first time docsy, so if we agree that the module approach is the new standard, I ask myself, whether we shouldn't discard the sub section Cloning GitHub Repo (Traditional) completely. That said, if you decide to leave it in place, I can live with that.

I think we can definitely reorganize your suggested docs a bit so that there's a default "happy path" set up to "get started" (so as not to confuse people) and then alternatives for those who want them.

Would like to get feedback from the rest of the community on this! (particularly what we think most users will want as the default)

[LisaFC]

As mentioned in #801, my PR is not ready for testing, I wish it were, I guess this would help you with your review, too. Therefore, you could do me a favour by taking the folllowing actions:

• create a new branch feature-hugo-module in the docsy repo, branching from HEAD at master.
• merge Bumped docsy theme to latest version docsy-example#155

I will then resubmit #801 on the newly created feature-hugo-module branch and bring it in a testable state. All further work could then happen on this feature branch and once we are done, you could merge this branch into master.

Done and done!

[chalin]

If use of Hugo modules is the way to go, then this seems great! Thanks @deining! I'll take a closer look as soon as I can.

[huehnerlady]

Hi, what is the update here? We are using dependabot for git submodules but since this change our build fails with the message Error: module "github.com/FortAwesome/Font-Awesome" not found; either add it as a Hugo Module or store it in "[...]/hugo/themes".: module does not exist

I found the documentation about the switch here in this Pull Request, but I feel this should be released ASAP as maybe there are other people having the same problem

Edit: Also I have quite a few problems using the migration guide, all of a sudden a page cannot be found and the known bug in the explanation is there, too. Is there a way to work without this workaround?

[deining]

This documentation is now fully in sync with #871 and ready to be reviewed.

[chalin]

Ok, thanks, I'll have a look as soon as I can (starting tomorrow).

[LisaFC]

Similarly, I'll take a look ASAP when I have a chance (probably tomorrow)

[LisaFC]

OK, I'll merge in the "Docsy Example with Hugo Modules" PR and then merge this one.

[chalin]

LGTM 🚀

[LisaFC]

Done! Shall we commence making Glorious Announcements?

[chalin]

Wonderful! Well done @deining and @LisaFC! I think that we can make announcements after the release is created?