'blog for project site

[Symbolics]

How are folks handling a 'blog associated with a project site? There are dedicated 'blog themes out there that look a bit nicer than the one included with Docsy, but incorporating sub-themes seems impossible without using Hugo modules. Other suggestions were to put the blog on a different domain, e.g. http://blog.project.dev with a different Hugo theme. I know that the existing 'blog can be tweaked, but this project doesn't have the skills for that, so we're looking for something more or less 'out of the box'.

Anyone else run into this problem and, if so, how did you solve it? The goal is to have nice looking 'blog to accompany the project site. Alternatively, are there any plans to have Docsy use modules?

[narrenfrei]

What are 'nicer looking' Hugo themes in your opinion? Any example?
Do you need also more functionality or is it only the layout?

[Symbolics]

Logbook is an example that I like. If we compare that to the Docsy example 'blog, there are a few things that could be better:

• Remove any editing links. No one except the authors should update the 'blog
• Remove page navigation links on the right side of 'blog posts. 'blogs should be short enough that they don't need navigation
• Add a tags and/or categories on the right
• Add a word cloud, if possible
• Add 'latest articles' section
• Add RSS feed subscription

Possibly the entire left hand navigation could be done away with for a 'blog section. Top level nav could remain for people to get back to the project website. LisaFC mentioned taxonomies in an earlier thread; perhaps those could be used to build the tag/categories functionality.

[narrenfrei]

Yeah, Logbook is a really well designed theme. Some comments from my side:

• Remove any editing links. No one except the authors should update the 'blog
  • Technically no problem, but perhaps not desired by all users.
• Remove page navigation links on the right side of 'blog posts. 'blogs should be short enough that they don't need navigation
  • Technically no problem, but perhaps not desired by all users.
• Add a tags and/or categories on the right
  • There is already a suggestion Issue #272 Add tagging support #324 for better support for taxonomies in Docsy and I also have already implemented at my productive site taxonomies. So this should be technically no problem.
• Add a word cloud, if possible
  • I have also implemented a simple word cloud with the tags at my productive site. So this should also be no technically problem.
• Add 'latest articles' section
  • I'll will take a look
• Add RSS feed subscription
  • RSS feeds should be already possible: https://www.docsy.dev/docs/adding-content/content/#rss-feeds

So what's really the challange?

• Are these developments in the sense of the project management. @LisaFC
• This would be quiet big changes for the layout (and maybe also HTML structure) for blogs out of Docsy. So there will be Docsy users out there, which maybe would be not so amused about the changes.
• Docsy, as I understand, should be out of the box a quiet flexible Hugo theme specialized on documentation. And many special user requests, even if they are understandable in principle for the respective situation, cannot be generalized for all users. Therefore, some adjustments will probably always have to be made directly in the respective installation.
  • @LisaFC Are there any guidelines or a roadmap for further development?

[LisaFC]

Thanks, @narrenfrei, that's a good summary. And yes, we are definitely a docs-focused theme! We included a blog section because a lot of projects I'd worked on (like Istio and gRPC - now a Docsy site!) had a blog and it's something many users like to add to their sites, but the key focus of the project was always technical documentation. As you've found (and I found when I started researching OSS docs themes for my own projects), a lot of templates do "blog" very well, but don't do the other bits that we've found more useful for docs. The idea was always that Docsy should work "out of the box" for most users but be flexible enough for users to add their own site-specific look and feel and desired functionality.

@emckean is driving some work on a roadmap (hopefully available soon when we're less snowed under by other projects), nothing finalized yet but the aim is to prioritize broadly applicable changes/requests (eg navigation improvements), and to avoid breaking changes for existing users unless absolutely necessary. (for example we've had to make breaking changes when, eg, Hugo changed their default Markdown processor, and we might consider them if it involved making a major improvement to something widely used)

That said, if someone wanted to try blog improvements for their own site or broader use they're obviously welcome to do so, and we could ask the community (via the mailing list, which I believe we're planning on porting to GitHub Discussions) if they're using the blog templates much and if they'd like/dislike us to update the theme accordingly. But it wouldn't be a high priority for the project as a whole.

[Symbolics]

I thought that there would be a set of design trade-offs in a 'blog that are sufficiently different from a doc site so as to make it a bit of work to integrate a good 'blog into the site. I suspect then that placing a 'blog on a separate sub-domain is going to be the best short-term solution. This brings me back to one of the original questions then:

Is there any plans to make Docsy a Hugo module? If I'm reading the Hugo docs correctly, this will allow multiple themes to co-exist in a site, meaning that users can cherry pick what they want, say Docsy for docs and Logbook for the blog.

[narrenfrei]

I can't say anything about the use of Docsy as a Hugo module, because I'm not so firm with this Hugo feature.

But I'm planning to make some tweaks to the layout for blog pages without changes to the HTML markup structure (if possible).

[LisaFC]

I think we looked at making Docsy into a module (with its own modules - it currently has Git submodules) and it would have required a fair bit of refactoring, also it's a not-yet-widely-used Hugo feature so there aren't many examples (so even if Docsy was a module/theme component, Logbook isn't, it also doesn't appear to be open source). It's definitely something to revisit though.

I don't think from the Hugo docs that modules would let you literally have entirely different styles in different sections (one style will basically "win" if there's conflict), though you could use eg shortcodes and layouts from both.

@narrenfrei, thanks for looking at blog improvements!

[emckean]

This blog post seemed helpful! https://chrisshort.net/from-git-submodule-to-hugo-modules-using-netlify/

[emckean]

Closing this now as it's not really an issue, but please feel free to create a Discussion if more discussion is needed!