Can Hugo play to a wider audience?

[dkebler]

What Steve and company have done with Hugo is awesome. After doing plenty of head butting on other static site builders choosing Hugo was a no brainer. BUT like many great pieces of code being written it’s mostly in the purview of other coders themselves or like me a kinda a “middleperson” who knows enough about coding to bash through issues, configurations and problems, but is not capable of writing GO code.

That leaves the majority of the planet who may never realize the totally awesome benefits of Hugo.

How can they be included?.

Clearly even the BEST documentation would not be the answer. Hugo’s is decent and getting bettter but no matter how wonderful it gets documenation is still the purview of geeks.

I’ve been contemplating how to allow all the noobs of the world access to all this cool stuff like Hugo and git etc for doing what they really desire which is getting out their content on the internet, collaborating and managing it without having to get “geek” help nor spending much $$. There are already lots of anemic “site builders” out there for the clueless that honestly are not very functional. My idea is not to cater to the clueless but to convince suitablely motivated clueless into upping their game by providing well thought out and useful resources, training and working environments.

I have a few ideas which I am currently working on and share below. But in making this post what I looking for is those of us “middlepeople” learning/using Hugo interested in getting it into the hands of as many “normal” folks as we can. This clearly goes outside the focus of this discussion board since it involves things like creating a complete user editing environment, tutorials(video) and creating full blow hugo sites (beyond just themes) that can be molded easily to the bottom line (getting someone’s content online and easily edited).

So anyone on this discussion board interested in joining me in this endeavor?

----------- what I have been working on so far ----------------
Putting together a suite of applications and scripts (of which hugo is central) that provides a turnkey to creating/maintaing hugo based websites including version control/collaboration via git and serving them via AWS. After coming up with a system to install this identical suite on any OS I not only have have a recent college grad in literature using this “suite” on a MAC to do Hugo editing (was easy to train a 20 something!) but get this an 80 year old director of a non-profit using Hugo within Windows. I am thinking the ultimate solution is to create a fully configured virtual machine to distriubte that folks can run on their desktop.

Creating a zurb foundation based hugo site(s) that provides a FULL functioning quickstart (not just a theme) and is easily customizable (e.g. I use a sass palette file and users set their colors via paletton.com). This is has been my grip of all these frameworks even commerical templates based on them. You couldn’t really just run with them. I envision folks simply editing the md files in the content directory to get “their version” with maybe a few tweeks to the pallette and maybe a few choices for layouts and with taxonomies already set to go both for editing and display. As some here agreed before a single “killer” (well-documented) example would be worth all the standard documentation.

[bep]

It\s shorter than the above,

1. Hugo have to get to 1.0 with the features most people expectect from a static site gen – and a few they get surprised by // all in Go speed.
2. The doc should get a rewrite (and mosty shortened) by then.
3. The community is hopefully bigger by then, so more people to write code and doc…

[snej]

It sounds like there are two different goals being talked about:

@dkebler wants Hugo to reach non-geeks, the people who would today be using wordpress.com or SquareSpace or other hosted blogging service; or possibly using a self-hosted engine like WordPress with some hand-holding like DreamHost’s auto-installer.

@bjornerik is talking about competing with Jekyll, OctoPress and other static generators; basically reaching geeks who are comfortable working with command-line tools, directory trees, creating files to manage content.

Both are important. The second seems like a shorter-term goal, necessary for Hugo to achieve liftoff; but in the long run it would be awesome to have the kind of packaging and automation that would provide a user-friendly turn-key blogging/CMS service.

[tanzaho]

@dkleber This is indeed a really nice idea, I remember having read somewhere that @spf13 wanted to add some CMS features to Hugo to some extend (probably in an additional layer).

Though, have a virtual machine does sound really geeky, right
The good question is not what, but how. Is there any thread or page where the future milestones are listed/discussed ?
I would be really happy to contribute (as a non-Go advanced user).

[dkebler]

Been waiting to see some replies.

I agree with @snej on his second point. Providing an ever better workflow and resources to those capable is needed as in bringing in a critical mass of knowledage adopters in the short run. My second point falls in with that and I was just now thinking about the best way to have a shared location of “used/tested/organized/reviewed” shortcodes, gists, full sites, themes, workflow tools/patterns, tips, blog, how-tos etc. that would go beyond well beyond the documentation’s. Maybe a seperate hugo users site is the answer (of course built using hugo) and making use of other tools like http://www.gistboxapp.com, github, aws, etc

As to his first. Excatly @snej, I am talking about those who might be using wordpress (and its shortcomings) and missing out on the advantages of a static builder and using collaborative/version tools like git. Totally a different audience. This “site” I mention above would not be for then. Their resouces would be necessarily separate so as not to scare them away. They need a comprehensive gui environment in which to work. To this end I have bundled this suite of applications that importantly runs on linux/mac/windows

• Smartgit (java based gui for git CLI)

• Sublime (with markdown and other useful packages loaded and keybindings for things like easy insertion of shortcodes. The sky is the limit with sublime between tons of packages, easy python programming and user settings.

• Hugo

• Firefox/Chrome (instance launched open to hugo served page(s)

• Bash (scripts for launching/running Hugo and launching the other programs, plus other functions)

What else? Alternatives? A custom GUI program
to hold this all togther

I have to say from experience that without something like a chef recipe getting this installed correctly on a random users computer is a bit problematic but I am sure there are tools out there like chef that can be used for all three OS. But because more businesses are going the VM route on their computers (for security, maintence and other reasons) a VM is making the most long run sense. It’s gotten way easier for end users. Now all one does is install a copy of vmware player and download your VM (linux under the hood) and launch it from list in the GUI. Having a VM would allow painless standarization of the environment and also make it easy for updates and improvements etc (via chef for linux based VM). In the short term the VM would be great for advanced users. I wish such a thing would have existed when I first came across Hugo. It would have been a game changer and time saver even though I was/am capable of creating my own working environment.

Mostly what I am concentrating on now is trying to build a completely full, customizable, documented hugo based template/site with a well thought out workflow and scripts and other tools to make that easier. For my reasons I have chosen the foundation/sass route even though most of the hugo code around is bootstrap or others. Not just a simple blog but full content website with alternate layouts. I am thinking it will be best to have an actual “project” to apply the development to. I do have a Joomla site I am planning on “converting” but this hugo users site would be a great place (I like the “meta” notion).

More thoughts now? What about a hugo users site/repo/collaboration to advance hugo?

[zzamboni]

@dkebler, really interesting topic. Along the lines of tools usable by non-techies, I’ve been working on a tool called Enwrite in the last few weeks, which generates Hugo content from a set of Evernote posts. It’s still in very early stages and not really usable yet (still very much the purview of geeks, as you put it), but my idea is to make it able to fully generate a website by writing and tagging stuff from Evernote. Please feel free to take a look and let me know what you think.

[RickCogley]

@dkebler, great topic. There’s necessarily a technical barrier, the first time you start introducing things like git. But that said, hugo is one of the easiest if not the easiest static site generators available. Kudos to @spf13 and team, for putting it together. I’m loving it so far.

I think one approach would be to make a “how to build a website” tutorial, and use it as a way to teach people about semi manual site building. It’s a great way to do it, because you can see the results immediately. Any css change, boom; any structure change, boom, it’s right there in http://localhost:1313.

[davidj3]

That leaves the majority of the planet who may never realize the totally awesome benefits of Hugo.

How can they be included?.

May I step forward as a representative of “the majority of the planet” who would very much like to be “included”?

My aim is in the first instance to make a blog that is fully built and tweaked client-side, so I can carry it about either on my laptop, on a flash drive, or both, and put it on my website using FTP. I’m offline a lot of the time and when I do go online it’s usually not for long, and I do not want to have to write the articles, or even cut-and-paste them, when online. I expect a fair amount of traffic and I do not want to have to rely on the ridiculously slow model of server-side generation on each reader request, which would also be completely out of my control and for that reason alone is out of the question. Since I want to be able to say here is my blog folder, and here are the articles in it, here are the images etc., without dealing with a “database” and PHP or SQL, the option of running WAMP portably doesn’t appeal either. (Why do people even use the word “database” in this context? It’s not something that gets queried. Not as I understand it, anyway.) The articles will usually be lengthier than the average blog article. They’ll mostly be of an academic-type character and I will probably tweak old ones as time goes on. It’s far far easier for me to keep a file of them which is a file of how they actually appear online (or as drafts being worked on, but in the same format). Easier for me and also easier if I want to send someone one or several of the articles, rather than saying “go to my blog”. I’d like the site to show up on search engines when people do the right searches, as most site owners would, but I am not especially bothered with SEO. Frankly I am acquainted with the smell of snake oil.

So I’ll be using a static site generator, to generate a blog in the first instance, on blog.[mydomain], and then perhaps some other parts of the site.

Hugo appeals more than the alternatives, because it doesn’t require Python or Ruby. But unfortunately some of the documentation and requirements do assume a fair amount of geekiness.

Here are the needs of someone like me. Forgive me for not using the right geeky terminology.

1. Set the template up with 2 or 3 columns, and so that the UI works OK both on proper monitor screens and the small ones that people have on their phones. Make it easy to play about with column width, number of columns, etc, and of course all the flimflam such as background colours, fonts, text size, etc. I’ll want to be able to see all of this happening in the source code, whether HTML or CSS.

2. Be able to have lists of links to “most recent x articles”, “most recommended y articles”, lists by categories, etc., and lists ordered by variables that I define and can assign to each article. In addition to “most recent 10 articles in reverse date order” let me do something a bit less mind-numbing than “archive”.

3. Commenting is an issue with static blogs. Disqus is out because it relies on a third party. A form that visitors can use to send me email, with emails autotagged to say which article they’re commenting on, will be fine. It shouldn’t necessarily say “click to send email”. It should rather say “Click to send a comment. All comments are subject to moderation”. But the functionality is the same. I’d also like to be able to change the email address at will, just in case I get hit with too big a spam problem.

That’s about it really.

I wouldn’t touch Wordpress or Blogger with a bargepole, and of the static blog generators the best one for my needs appears to be Hugo, perhaps followed some way behind by Jekyll. Dreamweaver is also an option, or at least it may turn out to be one if its templating can give me what I want.

I’m not a total newbie. I can code in raw HTML, and while I don’t know much CSS, I could learn it fast. I’m just putting my needs up here for those of you good fellows in geekland to know that decent non-geeky documentation on how to use Hugo to achieve points 1-3 above would be very welcome.

[rdwatters]

@davidj3

Here are some shooting-from-the-hip responses to your comments:

1. Hugo shouldn’t preclude you from setting up any template you’d like. You can use go templates to create div.row, .div.columns, sections, list items, etc. I think what you’re talking about here is layout, which is different than your template and a matter of CSS, which is not handled by Hugo. The templating layer, once you get the hang of the Golang templates, is considerably more robust (and a whole lot faster) than what you’ll find in Jekyll, Hexo, etc. That said, it is a little less easy to grok at times.
2. You can do this already. Look into first and sort in the docs. As far as defining variables in each article, you have more or less free reign with Hugo’s ability to parse yaml, toml, and json front matter in content files. Your metadata capabilities are only bound by the limits of your imagination:smiley:
3. So this seems to be asking for three different things: commenting, share functionality (ie, auto-completing email fields), and a forms solution equivalent to “contact me.” If you’re talking about commenting, Disqus isn’t a bad solution. If you’re worried about management, you can set a global config param and then set a param at the content-page level as well. Add this to your template for article pages and you should be golden. As for the contact form, check out formspree.io, which will send information directly to your email account. I guess you could even set up a formspree html form in each content page that pulled in the title of the piece as a hidden value (hidden as in just hide it in css but have it sent over the wire to formspree).

To be less abstract, you here is an example of a share menu that includes an email share link as the last list item:

{{$siteName := "davidj3.com" }}
<div class="social-media-share-menu">
    <ul class="share-menu">
      <li><a class="facebook share" href="https://www.facebook.com/sharer/sharer.php?u={{.Permalink}}"><i class="icon-facebook"></i></a></li>
        <li><a href="https://twitter.com/home?status={{.Permalink}}" class="twitter share"><i class="icon-twitter"></i></a></li>
        <li><a href="https://www.linkedin.com/shareArticle?mini=true&url={{.Permalink}}&title={{.Title}}&summary={{.Description}}" class="linkedin share"><i class="icon-linkedin"></i></a></li>
        <li><a href="https://plus.google.com/share?url={{.Permalink}}" class="googleplus share"><i class="icon-googleplus"></i></a></li>
        <li><a href="mailto:?subject=Read %22{{.Title}}%22 on {{$siteName}}&body=Check out %22{{.Title}}%22 on {{$siteName}}%0D%0DDescription:%0D%0D%22{{ .Description }}%22%0D%0D{{.Permalink}}" class="email share"><i class="icon-email"></i></a></li>
    </ul>
    <a id="share-button" href="#"><i class="icon-share"></i></a>
</div>

If you’re looking to use Disqus per the example I mentioned above, you can set the following in your config.toml (this is all assuming you don’t want to use the built-in shortcode):

[params]
  UseDisqus = true

Then in your content file front matter:

title: My Academic-Type Character Blog Post
include_comments: true

Then you could use a similar partial to the following once you sign up for Disqus:

{{ if and .Site.Params.UseDisqus .Params.include_comments}}
	<div id="disqus_thread"></div>
	<script async>
	var disqus_config = function () {
	this.page.url = {{.Permalink}}; // Replace PAGE_URL with your page's canonical URL variable
	// this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
	};
	(function() { // DON'T EDIT BELOW THIS LINE
	var d = document, s = d.createElement('script');
	s.src = '//yourdisqusid.disqus.com/embed.js';
	s.setAttribute('data-timestamp', +new Date());
	(d.head || d.body).appendChild(s);
	})();
	</script>
	<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>
{{ end }}

@davidj3

fully built and tweaked client-side

As for this, I’m not sure what you mean. If you’re looking for full client-side rendering a la a JavaScript MVC, you may have a point that Hugo is not the right tool for what you’re trying to do. I guess you could create markdown files and have Hugo spit them into .json that is then digested by your Ember/Angular/React application, but there are other tools out there better built for that purpose, and I personally think that defeats the whole purpose of an SSG, no?

[dkebler]

Ok TWO years later I finally have something produced that addresses the noob factor I brought up with this post. One doesn’t need to know css, nor go templates, javascript etc.

It’s a single page generator theme with sections and a butt load of settings in the config file, a nice set of shortcodes and a guide and starter built from …you guessed…Hugo! It’s mobile first and responsive

See my post in the announcements section
https://discuss.gohugo.io/t/noob-friendly-complete-landing-page-generator/6268

[claudia]

Non-geek here (using @snej’s terminology).

I don’t necessarily want a more user-friendly solution, but what I would love is better documentation.

Not to say that what we have right now isn’t great, both on hugo docs and on websites of theme builders who have taken the time to write down their instructions. But I built my website on hugo and for the past three weeks I’ve been trying to understand just how to get it online. I’ve narrowed it down to two sets of instructions, and I don’t understand why they’re different. I sense that there are things I should know, assumptions that are probably obvious to a geek that have seeped into the docs. If I had a better set of instructions, I would be having so much fun right now. I would also have a published website.

Maybe the solution is for the geek writers to work with non-geek writers, who would be able to detect, say, the leaps made between steps 5 and 6, so they could become steps 5, 5.1, 5.2, and 6.

[rdwatters]

@Claudia

I empathize with you, but I think the docs needs to be well scoped. Hugodocs is ultimately a publication and should not aim to be everything for everyone. The previous version of the docs tried to take on too much, and unless you’re Wikipedia, such attempts rarely bear fruit.

I think the forums are a great place to ask questions and ask for pointers to additional resources. Compared to the documentation of most FOSS projects I’ve looked at, Hugo is generous in its inclusion of walkthroughs for various hosting solutions…

[Jura]

@claudia

I built my website on hugo and for the past three weeks I’ve been trying to understand just how to get it online. I’ve narrowed it down to two sets of instructions, and I don’t understand why they’re different.

(…)

Maybe the solution is for the geek writers to work with non-geek writers, who would be able to detect, say, the leaps made between steps 5 and 6, so they could become steps 5, 5.1, 5.2, and 6.

Sorry to hear about your troubles! Addressing this issue is probably out of scope for this topic (can perhaps better be in a separate topic?), but what ‘two sets of instructions’ are you talking about?

From what I know of the documentation, there are not two sets of conflicting information. The information certainly should not be so conflicting that after 3 weeks it’s still unclear. So I’d love to know where those problems are, since they obviously need to be fixed then.

I know that the quick start contains steps (perhaps you got stuck there? ), but there’s no step 6 on that page.

[claudia]

Thanks, @Jura! I wasn’t asking for help in this topic—my point was that docs that would include a little bit more detail would help non-geeks understand what they need to do better. The step numbers were also just to illustrate that point: I sense there is sometimes information between step X and Z that I don’t know, that would belong to X.1.

The information I’ve been reading (from the docs, theme creators and github) is different, not conflicting, which is logical, because they each take different things into account—I simply don’t know why, or what I should take into account in my case. Don’t worry, the docs are fine

[claudia]

That is true, I don’t think they should take on too much either. In fact, the hugo docs are incredible right now—I know because I was able to follow with no experience with git at first. All I’m saying (and hugo docs doesn’t necessarily need to fix it) is that as a non-geek, I do feel that sometimes there is information I was supposed to know in order to know what to do next. But what you said is also true—I suppose that is what forums are for, and the hugo community really is friendly and helpful.

[winstonhoseadriggins]

Hello, I am an avid reader of the very informative posts contained within the Hugo Discussion Forum.

I came across this particular thread and would like to share my views on the topic.

From my understanding, the crucial point the Originator posts is:

“But in making this post what I looking for is those of us “middlepeople” learning/using Hugo interested in getting it into the hands of as many “normal” folks as we can. This clearly goes outside the focus of this discussion board since it involves things like creating a complete user editing environment, tutorials(video) and creating full blow hugo sites (beyond just themes) that can be molded easily to the bottom line (getting someone’s content online and easily edited).

So anyone on this discussion board interested in joining me in this endeavor?”

My experience working within the Hugo framework has been an enjoyable one.

I must acknowledge that there is a steep technical hurdle that must be overcome to develop and publish a Hugo website.

I embarked on my journey of discovery by cloning the available Hugo themes and publishing the Hugo sites to my Gitlab repository.
https://gitlab.com/winstonhoseadriggins/

Then, I registered a few example sites with Google to be indexed in search.

Bootstrap4 Example
https://winstonhoseadriggins.gitlab.io/hugo-boot4/

Emoji Presentation
https://winstonhoseadriggins.gitlab.io/hugo-presentation/

The next phase of my journey involves developing my own themes for clients.

In sharing my thoughts and examples in response to the topic “Can Hugo play to a wider audience” I hope to encourage those struggling with the documentation to press forward with a firm resolve and knowledge that Yes, you can have your own website!

[maiki]

I’m inspired to share some thoughts on this, having spent time tracking and solving the most asked questions in #support. It has been the framework by which I learn about Hugo the program and Hugo the idea + community.

My big idea is this: Hugo (and potentially other SSGs) is a piece of future retro-tech, and a decade of “web 2.0” has changed the way creators approach web tech.

What do I mean by “future retro-tech”? Well, let’s play out a common (if not dominant) workflow for a web editor (person) using Hugo:

1. Create content
2. commit and push
3. ???
4. Profit

When we look at that, we see this amazing process that fits what we are doing already. But of course it wasn’t easy to get there, because when we refer to that publishing pipeline we are actually talking about:

• Install a binary for the local OS
• Configure and understand version control
• Provision hosting somewhere
• Tweak a theme using HTML, CSS, and possible JS and Go template tags
• Writing for hypertext
• Being able to do absolutely anything they can think of (terrifying)

These are the things we discuss here. Now compare to WordPress (which I love and do not think is bloated). The common content workflow is:

1. Create content
2. Hit publish
3. Profit

No question mark, because WordPress is an online OS, and gives direct feedback. That is good for lots of folks, but the difference really changes when you see what goes into hosting a WordPress site:

• One-click install everywhere
• Pay someone else to host it
• Pick a theme that can’t do anything you can think of, but all the things you need
• WYSIWYG
• Able to do anything another person has done and shared as a one-click installable piece of code

These aren’t even the same game on the backend. But WordPress, for better or worse, has pushed forward the paradigm of the web as an app, and Hugo returns to the concept of the web as a document publishing and retrieval system. And it does so by employing best practices and technology.

I have limited time to contribute, so I am slowly building up little meta-tutorials, in hopes we can see what is useful and move that knowledge into the docs. Among the topics of “how to get help” and “how to talk about Hugo”, I’d also like to see a breakdown of the publishing stack so folks can interact with each component at their level (and hopefully level up after a while!).

• Hugo creates static web pages: that means you put HTML files somewhere to host
• Version control is useful, and Hugo has some neat features around that, and everyone is using it, but it is not required to use Hugo, and we can’t teach people how to use git.
• Web hosting is all over the place, but we produce text files, so we can’t recommend a way to do it, we can only list the many ways it goes down, and let folks make their own decisions; this is nuanced, of course. Can’t keep folks from asking for recommendations.
• All the webcraft that isn’t Hugo, but it handled in transparent ways for other systems, like HTTPS, or comments/forms, or CDNs for assets, etc. These are interesting topics, but is outside the scope of a static site generator.

I don’t want the docs to reflect all of those things, because it is too much work for us to curate and keep updated. Also, there are much better resources. If anything, I’d like to identify topics of interest and explain them like we are five years old, so we give folks the words to find what they are looking for.

And to make this not completely off topic, this thinking is in the spirit of making the web easier for everyone, and making Hugo accessible to a wider audience. But I think Hugo will remain in the wheelhouse of web publishers that are also web editors, or a sysop that is maintaining the templates while creators are still using some GUI to create their content. I don’t think Hugo will ever compete with WordPress, aside from eating the cake it is leaving behind by becoming more of an online OS.

Apologies for the run-on text-wall. Trying to get this documented so I can act on it.

[Jura]

@maiki

I’d also like to see a breakdown of the publishing stack so folks can interact with each component at their level (and hopefully level up after a while!).

(…)

But I think Hugo will remain in the wheelhouse of web publishers that are also web editors, or a sysop that is maintaining the templates while creators are still using some GUI to create their content. I don’t think Hugo will ever compete with WordPress, aside from eating the cake it is leaving behind by becoming more of an online OS.

Just to reply on a small bit of your good post: I think the docs can benefit from describing use cases (user avatars, in more fancy terms). That way we can point people to more specialised information tailored to what they want to achieve.

For instance someone that comes from WordPress might never have used version control, and might have no need for it if he simply writes in Word and keeps his content stored there. And then uploads the static HTML to his server. So no need to overwhelm this person with version control information.

So perhaps documentation information with the end in mind helps:

• If you want to use Netlify with Hugo, use these and these resources.
• Already have a server with Apache? Then check out these resources on FTP upload and something else.

and so on. Does that make sense?

[maiki]

User cases is a great idea! I will definitely contribute one or two, coming from the POV of my clients.

When I think about how to introduce folks to Hugo… I started writing this and realized I hadn’t checked to see if we had an intro to Hugo that wasn’t the quick start. Turns out there is a what is hugo page kinda sorta hidden in the docs (it isn’t linked to from the sidebar, but is the first link on the about page).

That’s a great start, and we can just iterate there based on what we’ve learned from folks asking questions. I’d like to touch on the broad subjects of all the components that touch Hugo, but defer to external resources for further research. So, explain how Hugo relates to version control, hosting, HTML, Go, etc., and give folks the words and links to figure out the rest, or asking informed questions.

@Jura we can start any of these documents here in the forums, and move them to docs as needed. Any particular use case you have in mind?