Make docsy a go module (with its own submodules) #520
Conversation
|
This is super interesting and would definitely potentially make dependencies more manageable. I am less keen on the idea of pulling the Fontawesome and Bootstrap stuff in directly, just because of the potential for maintenance awfulness. Thoughts from anyone else? One thing we'd need to look at would be whether we'd need to maintain the old non-Go-modules version to avoid breaking existing sites.... |
|
I started a thread in our discussions area too just to see if I can drive more discussion to this topic, as it's a tricky one. There are, as you say, some definite advantages, and this is something Hugo has really invested in. Some cons I'm thinking of
|
|
This should be fairly easy for users to try locally, right? (obviously it doesn't build in our Netlify preview as that assumes a submodule structure) I'm going to send a mail to the users list to try to drive some discussion/experimentation. :) |
Yes, correct. If they experience difficulties, I'm willing to help out here or elsewhere.
I just saw your post, I will follow the disussion which will hopefully arise. |
|
Couple of points... But more importantly modules also open up the possibilities of separation of code and content. Having done that with Antora, I have implemented that on my own personal site with hugo and my own theme that I am refactoring to be compatible with docsy. But the point being that using modules to completely remove your docs from the hugo site generation end has huge benefits. Users can edit and maintain their docs in a git repo and neither see nor think about site management. As pointed out above, not a lot of themes use modules (yet), and probably less use modules for content. But a documentation theme should really have this as an option if not (eventually) a default configuration. |
How can we get on this list? :) We are starting to use Hugo/Docsy to replace our Slate framework. We have a large team of writers working on different projects, and are implementing some of our common Hugo content (archetypes, layouts, etc.) and reusable content as Hugo modules. We would love to have Docsy be a Hugo module too. So maybe we can help with the testing? :) |
|
Hi Nathalie, our user email list is https://groups.google.com/g/docsy-users, though we largely use it for announcements now that we have discussion forums on this repo. It would be great if you want to try it and report back, either on this PR or in our discussion: #535 (which would people prefer for further discussion on this topic?)
|
This is a really good idea! It's a step towards potentially adopting Docsy-as-module, without the potential for breaking changes or maintenance overhead (yet), and a way to get more feedback. I suspect only people digging around in either the PRs or the repo discussion forum may even know that it's possible (given that it's not such a commonly used mechanism yet), so having it in the actual docs will possibly get more users trying to use the feature. We can add a link to this PR and/or the discussion forum.
|
I'll write a note in the other discussion, thanks! :) |
|
When I run No errors importing the modules. |
|
This patch is now outdated and was superseded by my new PR #801- Let's continue the discussion there. |
Making docsy a go module was discussed in issue 456 already. I'm citing from there:
I worked myself into hugo modules recently and ended up with this PR which turns docsy into a module —without the need of any refactoring of the existing codebase. The only change needed is to add a
modulesection (with severalimportsandmounts) toconfig.toml.With a new hugo site set up and a fresh copy of the docsy theme cloned to the
themesfolder, let's compare the proposedmodulesapproach with the currentsubmodulesapproach:Resolving dependencies with Submodules (current HEAD)
Pulling in dependencies with Docsy as Hugo module (this PR applied)
As you can see, the process is more than 4 times faster now.
Let's compare downloaded file sizes:
With Submodules (current HEAD)
With Docsy as Hugo module (this PR applied)
As you can see, the download size is drastically reduced now.
Requirements for using Hugo modules (this PR applied)
Having to deal with submodules when setup a new docsy theme doesn't account for a nice first time user experience IMHO. I even tend to say it scares users away from using dosy. I think this PR proposes a pretty neat alternative which is far superior to the existing solution IMHO, and I would like to put it up for discussion now.
I'm willing to follow up on currrent work and rework and/or extend the current documentation. However, prior to that, there are a few issues which should be clarified, like:
The discussion is open, looking forward to your input.
One last note: this blog post explains how to add a theme to an existing site using modules.