theme without an exampleSite?

[LisaFC]

Hi Hugo theme gallery people!

At the moment our theme has a separate Example Site (current draft served at https://goldydocs.netlify.com/) that has a lot of guidance and structure rather than just lorem ipsum type neutral content, with its own repo for users to clone to get a site with the same structure. We also have some user docs that I'd like to serve from a subdirectory of our theme repo, but given that we already have an example site in its own repo, I don't want to put them in an exampleSite subdir as I think that might confuse our users.

We want to be able to add our theme to the gallery when it's ready but aren't sure how to deal with the demo requirement - can we specify that we don't want the Demo button or do we need to do something to show users that our theme works with the latest Hugo?

[digitalcraftsman]

Hello @LisaFC,

thank you for sharing this nice looking documentation theme with us.

It is possible to disable the demo of a theme altogether. Instead you can use the preamble to your theme's README to link to your own demo instead. Just make this link visible for users when browsing your theme's README on www.themes.gohugo.io.

do something to show users that our theme works with the latest Hugo?

The min_version attribute from the theme.toml file will be displayed and should be enough to inform users that your theme works with version xyz or greater.

We also have some user docs that I'd like to serve from a subdirectory of our theme repo, but given that we already have an example site in its own repo, I don't want to put them in an exampleSite subdir as I think that might confuse our users.

Does this problem still exists if you're hosting your own demo?

[LisaFC]

Ah thanks, that's very helpful!

Does this problem still exists if you're hosting your own demo?

Alas yes, as we essentially have two websites associated with the theme - one the demo that I linked to above (designed for users to copy and edit if they want a comprehensive documentation site for a tech product with a blog, reference docs, etc.), and then some instructions for the theme itself (how to use the shortcodes, config details, etc.) which are less substantial.

Here are our draft user docs (currently being served from one of my personal repos): https://serene-roentgen-10fbaa.netlify.com/docs/

(obviously users can copy this site instead if they like)

[digitalcraftsman]

Dear Lisa,

excuse the delays in the review process of your theme. Right now, I'm in the final phase of finishing my bachelor thesis. Hence I'm want to ask for a little patience.

Thank you.

[LisaFC]

No problem at all, there's no huge rush as I'm on vacation for the next couple of weeks - I'll have the theme.toml and screenshots in as soon as possible. Good luck with your thesis!

[digitalcraftsman]

Hi Lisa,

I've found two repositories that seem to be related to your docsy theme:

1. https://github.com/google/docsy which is the actual theme
2. https://github.com/google/docsy-example contains a comprehensive documentation for the theme

Is my assumption correct that you would like to showcase the first repository on www.gohugo.io? If this is the case you would have to add an exampleSite folder to the this repository.

One way to "hide" the exampleSite folder is to use a separate branch, e.g. hugo-themes-demo. We can tell the build script for the Hugo theme site to use the hugo-themes-demo branch rather than master. This way users of your theme will unlikely encounter the exampleSite directory. A disadvantage of this approach might be the added maintenance due to the new branch.

Please let me know if this approach would work for you.

[LisaFC]

Hi there,

I've found two repositories that seem to be related to your docsy theme:

https://github.com/google/docsy which is the actual theme https://github.com/google/docsy-example contains a comprehensive documentation for the theme

So that's almost right - /google/docsy is the actual theme, /google/docsy-example/ is an example site repo using the theme for users to copy and edit with some instructions (it's published at https://example.docsy.dev). The comprehensive docs for the theme are actually served from the theme's userguide/ directory at https://docsy.dev (we didn't use an exampleSite/ folder because we didn't want users to get confused between it and docsy-example)

Is my assumption correct that you would like to showcase the first repository on www.gohugo.io? If this is the case you would have to add an exampleSite folder to the this repository.

Yes, the first repository is the one I'd like to showcase, I'm just wondering what I'd put in the exampleSite folder given that I already have an example site in a different repo, plus a smaller example site in userguide/?

Thanks for your help and sorry for having such a complicated project!

[digitalcraftsman]

I'm just wondering what I'd put in the exampleSite folder given that I already have an example site in a different repo, plus a smaller example site in userguide/?

If you already have a complete Hugo website in a different repository, you could add this one as Git submodule to the google/docsy under a folder named exampleSite. This way you keep the theme and the documentation / user guide in dedicated repositories and you're still able to re-use the content.

[LisaFC]

Ah, that's a great idea! That should work, thanks! I'll get that set up.

I'll probably still do it in a separate branch as the theme has existing submodules that users need to recurse into to use it locally, and they probably don't want to pull in an entire other website in the process....

[digitalcraftsman]

Let me know when you're ready to continue the review.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. Feel free to ask questions. We're glad to help. This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[LisaFC]

I have just managed to finish a bunch of other high priority work, so should have something for you later this week. Thanks for your patience and looking forward to seeing my theme in the theme gallery!

[LisaFC]

https://github.com/google/docsy/tree/hugo-themes-demo

Quick question: does the example site demo run with hugo server --themesDir ../..

If it does, I'm going to need to add a couple of params to the actual example site config.toml

time_format_blog = "Monday, January 02, 2006" time_format_default = "January 2, 2006"

as for some reason (that I figured out the last time I ran into this and have since forgotten :) ) Hugo doesn't get them from the theme config.toml if you run it from inside the theme.

[LisaFC]

Also let me know if there's anything else I need to do for your review! Thanks.

[LisaFC]

Just checking in!

[onedrawingperday]

Hello @LisaFC

I am the other maintainer of the Hugo Themes showcase and I had a look at the Docsy theme and noted the issues raised in the above discussion with @digitalcraftsman

Accommodating the Docsy theme would require refactoring in the ThemeSite Build Script if we are going to generate a demo served from the hugo-themes-demo branch.

As things look like at the moment, whenever the Build Script is executed it will need to look in the Docsy themeDir to fetch the exampleSite submodule as well as the other ones that are required by the theme by running git submodule update --init --recursive docsy

Instead of doing all that, I propose that we add the Docsy theme in the repo and add it to the noDemo array, so that a demo is not generated. The homepage button will point to the external demo located at https://docsy.dev

Maintenance will be easier since the hugo-themes-demo branch will not be needed.

So if @digitalcraftsman is OK with my proposal and we go ahead with this approach there are a couple of things that still need to be done:

• Add an images directory with screenshots of the theme as described in the theme submission guidelines

• A theme featured in the Hugo Showcase needs to work with the basic version of Hugo, so you will need to generate the theme's resources and commit them in the theme repo and always keep them up-to-date whenever there is a change as described in the theme submission guidelines.

[LisaFC]

Ok, happy to go with the "no demo" approach and I can do some screenshots for the images directory.

If I'm not doing an automatic demo, is there a reason why I need to have a version of the theme that works with basic Hugo? One of the reasons I used the extended version was that it made the theme repo smaller/cleaner, and if I check in the generated resources my users are going to end up pulling them in too, which seems a bit pointless given that I've specified that they need hugo extended to use the theme.

[onedrawingperday]

Ok. I just saw that you indeed mention it over here

That's fine.

Once you add the screenshots please let me know.

[LisaFC]

Images are up! https://github.com/google/docsy/tree/master/images

[onedrawingperday]

@LisaFC

I have just added Docsy to Hugo Themes with 77794ef

---

@digitalcraftsman

This theme was added to the noDemo array of the Build Script -as discussed above-.

Docsy is a theme specifically designed for technical documentation sets.

[LisaFC]

Thanks so much! Delighted to see it up in the gallery and thanks for all your help!

[digitalcraftsman]

@LisaFC Your theme has been promoted on Hugo's official Twitter account: https://twitter.com/GoHugoIO/status/1197522398444163072

Technical documentations are a great fit for static site generators, for Hugo especially those with a lot of content and pages. Thanks again to you and all contributors of Docsy for expanding the range of such themes.