Easier path for new users

[epogrebnyak]

I'm trying to see what can be done for quicker/wider adoption of the theme, two ideas:

1. Explain in Readme why node/npm is needed for Hugo theme. Can this theme work without npm? What are the benefits of extra dependency?

2. Faster way to replicate different parts of screen.
   As a new user I'm frustrated which parts of config control which parts of layout. There is a tutorial, but it king of assumes more knowledge about theme internal.

Key areas for new user:

• how do I change content of landing page? Where is content file that controls it?
• what controls the menu structure
• how do I start the blog? Where the files would go?
• where do the markdown files go?
• what I should not touch and leave for later?

Many of these are on the Hugo side, but a theme documentation could help. For example I did build a few sites in hugo, including Academic theme, but still not sure how to do things with new theme (especially when node run jumps in).

Can do some PRs into new documentation where needed, once I understand myself.

3. Github actions workflow?

[epogrebnyak]

Like here: why not tell users what is the end goal or benefit of using npm and why exactly npm surfaces for a hugo theme. For non-JS people that is a burden, better know exactly why this is for? Running non or installing packages is not a good explaination yet, unclear what is the end benefit of it.

Requirements
Make sure all dependencies have been installed:

Hugo >= 0.75.0/extended (needed for SCSS processing support)
Node.js >= 14.15.0 (needed to install npm packages and run commands)

[h-enk]

Doks is set up with The Twelve-Factor App in mind. See in particular: II. Dependencies.

Every Hugo theme uses dependencies. Dependencies provide for functionalities. There are basically 3 ways (in order of adoption by theme developers):

1. Hardcode deliver
2. Hugo Modules
3. npm modules

I adopted option 3. From the twelve-factor methodology perspective, option 1 is an obviously no-go, and option 2 is (unfortunately) too limited (yet).

For the Doks documentation, the idea is to not repeat (in line with the twelve-factor methodology) the Hugo and Netlify documentation. So, the Doks documentation describes the Doks specifics ONLY. Where relevant, I've linked to the appropriate section in the Hugo or Netlify documentation.

A lot of your questions are Hugo specifics. However, I agree that there's room for improvement for the Tutorial.

Not sure what your point about Github actions workflow is about?

[emptymalei]

I guess @epogrebnyak was talking about a GitHub Actions workflow to deploy it to Github pages. If this is the case, I have an example here.

[epogrebnyak]

If your starting point is Hugo docs, there is little to indicate npm installation is an option for a theme use, the only described method is git submodule for a theme. So for non-Javascript user seeing npm for Hugo is a bit of surprise. Maybe is Javascript community that easier to understand, but not from a perspective of a Hugo user.

[epogrebnyak]

Github Actions that deploy to Github Pages example: https://github.com/fastai/fastpages

[h-enk]

If your starting point is Hugo docs, there is little to indicate npm installation is an option for a theme use, the only described method is git submodule for a theme. So for non-Javascript user seeing npm for Hugo is a bit of surprise. Maybe is Javascript community that easier to understand, but not from a perspective of a Hugo user.

Valid point — thanks for keep pushing. I'm planning to write more on Hugo and npm/ why use npm. To be continued.

[epogrebnyak]

This kind of information about npm as asset delivery tool for non-JS project is really scarce and would be highly useful. Some of expectations (can use as sceleton for docs): - what is the goal - installing a Doks theme for Hugo - traditional way is hugo docs - git or copying to themes direcotry - why npm is well suited for that - here is how we configured npm it to work - here is how to use it - restate benefits (better theme delivery, additional commands) чт, 31 дек. 2020 г. в 17:27, Henk Verlinde <[email protected]>:

…

If your starting point is Hugo docs, there is little to indicate npm installation is an option for a theme use, the only described method is git submodule for a theme. So for non-Javascript user seeing npm for Hugo is a bit of surprise. Maybe is Javascript community that easier to understand, but not from a perspective of a Hugo user. Valid point — thanks for keep pushing. I'm planning to write more on Hugo and npm/ why use npm. To be continued. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#57 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLTNQCGOMPZHPF3ROKTSXSC5JANCNFSM4VI4V5PA> .

[shaneberry]

Exactly. My first question was "why node?"

[h-enk]

In short: Doks uses npm (Node package manager) to easier manage dependencies and customize build scripts.

For more background, see my Master npm with Hugo series for now.

[vicevolf]

At the first glance of the document, I thought it was a hexo theme because it needed nodejs and NPM.
I took a second look at the document and thought it was a doc generator using Hugo, not a Hugo theme.
When I looked at the document for the third time, my heart was full of confusion, for example: it uses NPM, can it be deployed automatically like most Hugo using vercel?

I'm not proficient in NPM and nodejs. I only have a preliminary understanding of Hugo. It's really difficult to start doks.

[epogrebnyak]

Sorry doks may look confusing to new users - npm is used for packaging of Hugo theme and dependencies management. One of dependencies can be Hugo itself, it is just a way of installing and using Hugo. I think Doks are now installable as a usual theme for Hugo too, even though I have not tried it yet myself.

[epogrebnyak]

Not that my answer should clarify everything, it just tells you are right, there are things that might confuse even a proficient user.

[vicevolf]

If I like the flavor of NPM and nodejs, I will choose the theme of hexo, but I prefer the cleanness of Hugo, so I just need to install Hugo to find the theme of Hugo. So I think your topic is worth it, because after reading the doks document, my desire to choose doks has declined 🍧。

In fact, I don't think the document theme needs to be upgraded frequently with NPM, and stable large version iteration may be enough. Documents don't always want more fancy new features than blogs.

This may be similar to fontawesome. I'm not in a hurry to upgrade from 4 to 5. I'll just upgrade next project.

[h-enk]

If you think Doks is not for you, don't use it.

[h-enk]

BTW, Node.js + npm are becoming more and more integrated since Hugo 0.75