Doks installation and upgrades

[krispkrisp]

First, I must apologize. I am not a developer but I understand coding. I'm moving from Wordpress to Hugo, and trying to understand the framework and how it works.

1. I was not able to install Doks as a theme inside my website as it is described in standard Hugo documentation. It only works when I use Doks as my website. So it makes it different then for example: Theme -> child theme dependency in WP. Am I right?

2. How would this impact updating? If Doks theme is not in themes directory, and I must build my website by modifing main theme templates, would my work be overwritten if I update via git/npm?

Thanks

[h-enk]

Perfectly fine — you're not alone 😉

Note, that the Doks setup is not Hugo standard (on purpose — see also below). You could compare Doks with a Bedrock + Sage setup for WordPress.

Ad 1) That's correct — Doks is a "starter theme" on purpose (more on why: Adding a theme). Also, I'm not a fan of a parent-child relation with a submodule or module: when you have lots of customizations, a parent update might have no effect or even cause conflicts (I know that from experience — also in the WP world).

Ad 2)

• Updating Doks. Since Doks is a "starter theme", this means you build your site on a particular version of Doks. If you would like to update to a newer version of Doks, you'd have to do that manually by copying-pasting parts "intelligently". I know the latter sounds harsh, but is good doable (I know that from experience).

• Updating dependencies. I recommend regularly updating the local packages your Doks project depends on. It will keep your Doks website stable, usable, and secure (see also: Updating). You could also consider automating update notifications by using a Dependabot workflow.

Hope that answers your questions /clarifies

[krispkrisp]

Now it makes more sense. Thank you :)

[cameronelliott]

@h-enk I have vacillated between using the child-theme and the starter-theme, but am currently using the
starter-theme approach, which does have the advantage of tracking the primary working repository (h-enk/docs).

It seems your comments here prefer/recommend the starter-theme approach.
But the comments in the prologue/quick-start.md page recommends the child theme for those that are unsure about which way to go.

Do you still feel thats the best recommendation??

I also like the fact I can git cherry-pick commits by you to the main repo
into my Doks repo, which isn't really doable on the child-theme.
( Also, github desktop now supports cherry-picking also! )

Thanks for creating & sharing Doks. Cameron

[h-enk]

Do you still feel thats the best recommendation??

@cameronelliott, maybe not. Cherry-picking is indeed something to take into consideration (had not thought about that, to be honest — thanks for your input!). I will rethink /restate the recommendation for choosing between starter/child.

[cameronelliott]

Thats really helpful feedback, as I kind of came to the same conclusion, especially with the ability to cherry pick, or even just simply merge in individual commits from the main repo. Thank you. 😄

[epogrebnyak]

Hank, this still puzzles me a lot ))) in Doks you are so strict on delivering JavaScript dependencies for the theme, but what it comes to updating the theme itself- it has to be manual labor ) Are you sure making doks installable as a theme as git submodule is such a bad idea?

If you would like to update to a newer version of Doks, you'd have to do

that manually by copying-pasting parts "intelligently вт, 23 февр. 2021 г., 13:52 Henk Verlinde <[email protected]>:

…

Perfectly fine — you're not alone 😉 Note, that the Doks setup is not Hugo standard (on purpose — see also below). You could compare Doks with a Bedrock <https://roots.io/bedrock/> + Sage <https://roots.io/sage/> setup for WordPress. Ad 1) That's correct — Doks is a "starter theme" on purpose (more on why: Adding a theme <https://henkverlinde.com/master-npm-with-hugo-managing-dependencies/#adding-a-theme>). Also, I'm not a fan of a parent-child relation with a submodule or module: when you have lots of customizations, a parent update might have no effect or even cause conflicts (I know that from experience — also in the WP world). Ad 2) - *Updating Doks*. Since Doks is a "starter theme", this means you build your site on a particular version of Doks. If you would like to update to a newer version of Doks, you'd have to do that manually by copying-pasting parts "intelligently". I know the latter sounds harsh, but is good doable (I know that from experience). - *Updating dependencies*. I recommend regularly updating the local packages your Doks project depends on. It will keep your Doks website stable, usable, and secure (see also: Updating <https://henkverlinde.com/master-npm-with-hugo-managing-dependencies/#updating>). You could also consider automating update notifications by using a Dependabot workflow <https://github.com/h-enk/doks/blob/master/.github/dependabot.yml>. Hope that answers your questions /clarifies — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#147 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLRAXZUBO2R763DYUNDTAOCFTANCNFSM4YB62SRA> .

[h-enk]

Doks is a starter theme, you shouldn’t need to update it. At least after v1.0.0 that is — the core functionalities will then be stable, and changes will only be minor.

That having said, I'm thinking about /experimenting with doing things smarter — see also: plugins

[h-enk]

I'm also setting up a POC adding Doks as a npm module to a Hugo project. With an init script and Hugo module mounts putting things in place . Basically allowing you to update Doks /using Doks as a parent theme.

Will keep you posted here.

[h-enk]

@krispkrisp, @epogrebnyak, great news!

I've set up a simple and robust POC using Hyas as a npm module + using Hugo module mounts to put things in place (no init script needed).

You can now use Hyas in a parent theme - child theme setup. And, best of all: update Hyas when a new version is released.

Do know the consequences of (any) parent theme - child theme set up: child theme files override parent theme files (also after an update) — this could lead to conflicts (depending on the changes you made).

https://github.com/h-enk/hyas-child-theme

Next step: set this up for the Doks theme, making it an option to start with. Expect it available soon/

[h-enk]

! Now available: Doks child theme — instructions will follow together with release notes /blog post on Doks v0.2.0

[epogrebnyak]

Next step: set this up for the Doks theme, making it an option to start with. Expect it available soon/

Great! I'm sure this useful and hard work, but I'm a bit lost what new packaging achieves:

Should we be able to install Doks as git submodule then? Or a child theme, but not through git but via npm? Or this is about updating versions of Doks theme as a starter theme? Or both?

Why does the child theme override the parent theme too? In usual Hugo installation this is other way around.

[krispkrisp]

Thank you for the update :) I'm already working on the main version.(not child) However I have noticed one problem: - when I deactivate all JS, the theme still generated an empty main.js file czw., 18 mar 2021 o 16:20 Henk Verlinde ***@***.***> napisał(a):

…

! Now available: Doks child theme <https://github.com/h-enk/doks-child-theme> — instructions will follow together with release notes /blog post on Doks v0.2.0 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#147 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AS4ZLH3VL33TBZHASLUYXEDTEIK4FANCNFSM4YB62SRA> .

[h-enk]

That's intentionally — you could still want to add JS.

Nevertheless, interesting to have an option to also disable the main.js /disable all JS. I will add that.