Add a "default" Hugo theme

[dstroot]

Hugo needs a very simple, plain default theme that is updated along with each Hugo release to be a canonical example of a theme. It would also make Hugo operational out of the box, which it is not now.

When you install Hugo it cheekily walks you through setting up a site and adding content and then it doesn't work because you need to add a theme. So you go searching for a theme - this takes far too long because the themes that exist are not sortable or searchable for what version of Hugo they apply to and you don't know if they will work or not. So you spend far too much time futzing with this just to get pages to build.

One the other hand, if you have a working base site a known good default theme now you can go futz around with what theme you like and try to get them working.

Just my view but hopefully some of you agree with me out there. 😄

[Jos512]

I agree, and from my standpoint having a default theme probably helps with writing documentation for beginners too.

[moorereason]

@magikstm, please use the reactions feature on the initial post instead of adding +1 comments.

[magikstm]

Thanks @moorereason . I Didn't know about this feature. I removed my comment and used reactions instead.

[ghost]

@bep @moorereason @digitalcraftsman

I'd be happy to take a stab at this, but is this something the maintainers are interested in?

[bep]

@sethmacleod That would be great. There are two issues in this one:

1) Create a default theme 2) Make that theme available via the command line hugo -theme default (or something)

If you could start with a sketch of 1) we can tackle the other issue later. I'm not sure where to put such a theme ...

@digitalcraftsman may have some valid input about that and what such a theme should contain.

[pixxx]

Hi, wouldn't it be enough or easier to simply create a default theme and update it along with hugo, and then simply install as with other themes, only that this one is always up to date with the latest functionality. I don't see why this should be bundled with hugo. Others don't really have this option either or?! But hey I wouldn't say no to a feature like that either.

[bep]

@pixxx the problem with "install as with other themes" is that we currently have no simple way of "installing a theme" -- it is a git clone into themes thing. I'm not saying we should bundle it, but we should (eventually):

• Get some kind way of pointing to remote themes and just get them automatic
• Add some "special" command option for the default theme

So, whatever we do, you should be able to download one binary and then.

hugo --someFlagForDefaultTheme

[pixxx]

@bep that of course would be a nice option, I can understand the demand indeed, the way you explained it. Guess I like Hugo so much so that I can live with git clone way longer than other issues. Plus in the end it's all about learning go and making my own themes for me. Other themes which aren't that many, are mainly a great resource to learn from in my case, what's way more important to me is that the documentation is always up to date.

[digitalcraftsman]

@digitalcraftsman may have some valid input about that and what such a theme should contain.

@dstroot suggested a dead simple theme. It would be good if we could define the kind of theme and its scope:

• should it be more focused on blogging or rather more general purpose?

As aforementioned we've to compile a list of features as well. They shouldn't be to complicated and be relevant for the majority of users. Here are my two cents of what we should highlight:

• the creation of content
  • url management
  • taxonomies
• the template system (structure + directory layout)
• asset handling (CSS, JS etc) + linking them
• menus
• basic i18n
• basic settings in config file

@rdwatters this sounds like a great candidate for the revamp of the quickstart guide.

the problem with "install as with other themes" is that we currently have no simple way of "installing a theme" -- it is a git clone into themes thing. I'm not saying we should bundle it, but we should (eventually)

I already suggested in #505 that we could create a repository for the default theme. Via a special command we could download the theme as zip file, extract the theme and start the built-in server.

By adding tags in Git we're also able to download the version of the theme that corresponds to Hugo 0.xx.

[ghost]

@dstroot suggested a dead simple theme. It would be good if we could define the kind of theme and its scope:

• should it be more focused on blogging or rather more general purpose?

@digitalcraftsman Couldn't it do both? For example, something like how Davide Petilli is set up?

Regarding features, I like what you've listed so far. Some of my thoughts:

• use examples of shortcodes, both built-in and custom
• fairly robust templating for a blog portion, e.g. taxonomies, archetypes, ordering, next/prev, etc.
• commenting explaining how things work
• sane defaults for partials

I agree that the theme doesn't need to be complex, but it should have enough for newbies to be able to learn from it as well as be a good boilerplate for people who want to get a website up quickly.

[digitalcraftsman]

Couldn't it do both? For example, something like how Davide Petilli is set up?

The website looks nice and has a common structure. I'm not sure where we should draw the line between "newbie"-friendly and (complex?) real world example. The theme should act more as a tutorial rather than beeing yet another theme. It would be great to hear a few more voices.

You made some good additions to the list :+1:

[bep]

The learning aspect of it is important.

But I think a surprising amount will actually use this for their web site, so it has to look good, and have some built-in flexibility ...

• Color scheme choice
• i18n support
• etc.

Many people want a "one click" web site that looks good.

So I would suggest that you start out by forking a good starting point.

[rdwatters]

Add some "special" command option for the default theme 👍 👍 👍

Whatever happens, having a theme installed by default is actually a really annoying feature. (Jekyll used to do this, I believe, and then you had to run a flag to run it without the theme.) I agree with @bep that it should be the opposite.

@rdwatters this sounds like a great candidate for the revamp of the quickstart guide.

Agreed! The default and quick start should be inseparably wedded:

hugo new site mysite -t qs
hugo new site mysite -t default (per Bjorn)

Or whatever...

updated along with each Hugo release to be a canonical example of a theme

Maybe. I think it's more important for it to be an example of how Hugo works in general, but I think we are saying the same thing.

Should it be more focused on blogging or rather more general purpose?

It should be a blog. "General purpose" is too much to tackle for a default theme. I don't think Hugo should ever be promoted as a "blogging tool"—that's a hard impression to undo. However, a blog is best because it's the simplest IA for a new user to grok; i.e., posts, pages, tags, categories, homepage, comments, etc...

Even the most non-technical user understands these concepts. Plus, it's got enough to it to demonstrate the overarching concepts and can be updated along with the docs with each new major version of Hugo 😄 .

Notes on New Quick Start

I'm not hijacking this thread; I just think the the QS and default theme should be linked concepts.

Here's some of my notes:

1. The current quick start is not quick. It tries to do too much. This isn't an insult. Shekhar did a great job, but it wasn't created as a Quick Start in the first place.
2. A bookshelf is too specific a use case.
3. Remove all git tutorial info. `git, basic command line usage, and comfort with a text editor are now "assumptions."
4. Delete the deployment step altogether
   • This is now it's own section within the docs
   • Hugo sites are deployable anywhere, so why promote one hosting solution?
   • How many new users want to deploy a default quick-start theme 15 minutes into using a tool?
5. If it takes the end user more than 20 minutes end to end to finish the QS with a project like Hugo, it's time to trim the fat

I agree it should focus on concepts, but it should not go in depth. That's what the actual documentation is for. The current QS has a detailed explanation of directory structure, which is off-putting to new users, duplicative of other areas of the site, and therefore screws with doc search overall maintainability of the docs. (Plus, I think some of it is just out of date.)

IMHO, a new Quick Start with the default theme has two purposes:

A. Demonstrate convenience in getting up and running B. Introduce end users to the mental model of the tool, including sexy features

So here's the "curriculum":

1. Project directory structure (including static, content, layout)
2. Content front matter, shortcodes (Hugo built-ins or those that ship with the theme), archetypes, taxonomies
3. Templates lookup, blocks, lists/single, partials
4. Themes customization (overrides)
5. Next steps points users to deployments, installing additional themes, creating their own shortcodes, templating, yada, yada, yada.

The theme can/should have many of these built in so the end user can explore and see the mechanics of how things work.

As an aside, the new docs have copyable/downloadable code blocks, which will make it much easier to demonstrate concepts that seem to be confusing; e.g., partials/context and overriding themes.

[rdwatters]

I'm not saying we should bundle it...

@bep So hear me out on this, but an easier way to keep a QS and default theme in sync would be to use a readFile shortcode in the QS body copy that reads from the default theme's directories and outputs the code blocks. In other words, a theme that would be bundled with Hugo the way that the docs are bundled. Then it's just a matter of keeping the surrounding text up to date surrounding each of the code blocks. Of course, that means treating it like, er, an internal template...and not really teaching people of git cloning the other themes...so it has obvious drawbacks.

I'm just wondering if you have any clever ideas on how these two might best be synchronized...

[bep]

I'm just wondering if you have any clever ideas on how these two might best be synchronized...

Two options:

1) Have talked about hugo get some time ago, i.e. addressable external resources (put the full path to the theme in your config.toml and we'll pull it for you into your HUGOPATH). 2) Embed it into the binary (i.e. no readFile shortcodes mumbo jumbo), and write it to the user's disk on demand.

Note: We don't really bundle the Hugo docs.

[rdwatters]

Embed it into the binary (i.e. no readFile shortcodes mumbo jumbo), and write it to the user's disk on demand.

Even better. As long as it updates the docs accordingly and means doc contributors/editors don't have to copy and paste, I'm all for it. 😄

[ghost]

What are people's thoughts on frameworks? Remain framework agnostic? Bootstrap v3 won't be supported soon, but v4 is still in alpha. Use HTML5 Boilerplate? Also, for the stylesheets, should we use css or a preprocessor?

[rdwatters]

@sethmacleod I'm not a fan...at all, but for this use case they make perfect sense since there will be inevitable handoffs. That said, rather than build something new, maybe it's best to get some insight from @digitalcraftsman about the most popular blog theme currently for Hugo, fork it, and just update it to make sure it meets all the above requirements discussed on this thread?

One thing I would suggest would be something typography focused without a ton of images...since the latter is a) harder to sorta genericize and b) dealing with an asset that isn't exactly Hugo's strength (i.e., images)....

[pixxx]

@sethmacleod same for me, I don't care for frameworks, guess the whole point is having something very basic and being able to add a framework and/or preprocessor if wanted. More of a scaffolding with all the bells and whistles Hugo offers, so that you can start something great with ease. I think that would make a lot of people happy. But I can't emphasize enough on documentation, that's really what has to sit, the moment you start searching to hard to get results you loose touch with Hugo, and might start looking at other alternatives. I see this all over the place people preferring stuff to work with that is simply well documented no matter if its slow or what not.

[KevinGimbel]

I'd like to offer help in customising a theme or creating a new default theme.

As for frameworks and pre-processors: I would not include a framework and would not use a pre-processors. AFAIK most pre-processors require Ruby or NodeJS, so a third-party dependency written in a different language which means users who want to build on the default theme need to install additional software. Frameworks are nice to get a headstart but they bloat the codebase and we need to keep them in sync/update the theme with each new release.

Something minimalist that shows different Hugo features like shortcodes or partials and generally educates about the layout system would be more valuable IMO.

Anyway, if help is wanted I'm happy to offer some of my time. :)

[budparr]

I agree with @kevingimbel re: frameworks and pre/post-processors.

I'd like to suggest, for CSS, Tachyons. It's "atomic/functional, etc. CSS" - I only suggest it because it's easy for people to walk into a manipulate a design without running an asset pipeline, and it's about 15kb gzipped. I've got a work in progress theme using it (and am using it production on Hugo sites) and happy to collaborate with anyone on this.

As has been pointed out, seems like including a theme with Hugo New Site may not be the best approach, but would certainly be good to have an official/canonical theme that takes advantage of Hugo features, exhibits best practices generally, and is a model for code examples. I think @rdwatters might agree.

In the theme I'm developing we're using a subset of the Wordpress Unit Tests content and expect it to be fully valid across a variety of criteria. Again, happy to participate, though I don't want to muddy things if there are already a lot of people on it.

[ghost]

I like the idea of creating a good boilerplate theme that people can build upon, and it might be easiest to do that with no framework or preprocessor and to start a new theme. There may already be a suitable existing theme, but a lot of the current themes are ports from other well know projects. It might be good to have a distinct theme that people can recognize as Hugo's.

[bep]

As this default theme should share the versioning of the main project, how about put it into

https://github.com/spf13/hugo/tree/master/examples/theme

We'll figure out how to best distribute it later, but this way we at least should ba able to keep it up to date.

[rdwatters]

I think @rdwatters might agree.

@budparr I do.

@bep I can submit a PR with basic scaffolding to show the concepts. All are welcome to hack on it and make it pretty :smile:

Are you thinking

A) A standalone site (i.e., with all the layout, content, static, etc at project root theme) or B) A theme from the beginning (i.e., everything in theme/themes/hugodefault and a single content folder at project root)?

This is easy enough to change down the road, but I ask this in light of your previous ideas re embedding it into the binary.

[bep]

@rdwatters look at the issue title.

[moorereason]

If we can keep it small, we can just embed it into the Hugo binary with go-bindata.

[ghost]

So, do people have a preference for forking an existing theme -- and if so, which one -- or creating a new theme?

Just to reiterate, many of the existing themes are ports from other well known projects. I would prefer a theme that is distinctly Hugo's.

[ghost]

I don't mean to spam, so let me know if this should be discussed elsewhere:

@rdwatters I like what you've done with your Hugo Starter Kit and Hugo Theme Starter. The layouts make a lot of sense and I think would be good for standardization.

[ghost]

I created a repo https://github.com/sethmacleod/hugo-default-theme to get the ball rolling. Not much is there now, but I will be working on it more this week. I'll be using the structure and templating of the Hugo Docs Concept as an influence.

[rdwatters]

@rdwatters I like what you've done with your Hugo Starter Kit and Hugo Theme Starter. The layouts make a lot of sense and I think would be good for standardization.

@sethmacleod Sorry for the delayed response. Thanks, but I'll have to review what I put in those "starters" since it's been a minute. I think it's best we decide on which Hugo features the theme should showcase and also which to include in the quick start. I appreciate you getting the ball rolling on this...

Also, per @bep suggestion, might be best to keep this in said folder/dir....

[shawnoster]

Wading in late but I just found this thread because I'm porting an old non-Hugo template and I'm finding the lack of canonical examples frustrating due to my learning style being examples/convention/source vs. docs/forums/blogs.

I'd part with a good amount of whiskey for a Hugo template that was framework free, provided clear and current real-world best-practices, prioritized theming and usability over UI because face it, there are thousands of great UIs out there yet there isn't a single Hugo blog theme that covers all of a basic blog's features that is in sync with the development of Hugo.

I'm looking forward to where this thread goes and I'll be watching hugo-default-theme to get inspired.

I'm also hoping this adds some structure and convention to how param config keys are organized. Seems every theme I clone has config keys under different sections.

[ghost]

Also, per @bep suggestion, might be best to keep this in said folder/dir....

Ah, I've moved my work to https://github.com/sethmacleod/hugo/tree/hugo-default-theme/examples/theme. At what point should I create a PR for a WIP?

Here are lists of features and standards to discuss:

Features

• [ ] basic settings in config file
• [ ] basic i18n
• [ ] menus
• [ ] blog
  • [ ] taxonomies
  • [ ] archetypes
  • [ ] next/prev
  • [ ] tag cloud
  • [ ] comments
• [ ] shortcodes (built-in and custom)
• [ ] color scheme choice
• [ ] code commenting for newbies

Standards

The default theme should set good standards for theme creators. It should be easy for users to switch between themes. Users should not have to make extensive changes to front matter, configuration files, or templates in order to switch themes.

• How to write a theme README
• config.toml
  • no trailing slash for baseurl
    • the trailing slash causes issues with .LanguagePrefix
    • paths should have slashes between each part, e.g. {{ .Site.BaseURL }}/css/style.css instead of {{ .Site.BaseURL }}css/style.css
  • Multilingual ready, so have both languageCode and defaultContentLanguage
  • emojify set?
  • google analytics set?
• site structure
  • themes should use baseof.html, even simple themes as this will make it easier for people to modify themes
  • head partials
    • complex head partials should have subdirectories, partials/head/foo-bar
    • styles, seo, rss, etc. -- if there are a lot, they can each get their own partial, e.g. partials/head/metadata-rss.html
• archetypes
  • default, post, and page all with sane front matter -- can make switching themes easier
• data
  • show how to use data with a relevant example
• static
  • image paths should be standardized to make switching themes easier
  • anything else that should be standardized to make switching themes easier?
• shortcodes
  • are there any that should be standardized that aren't built-in?
• Multilingual
  • keep a database of translated common strings people can use?
  • use absLangURL and relLangURL in templates instead of absURL and relURL

[budparr]

I really like that you've laid out some standards. For reference, Ben Balter did something like this with a "Jekyll Style Guide" a while back. Seems like that would be a good thing to publish for theme designers, aside from this theme.

[bep]

Agree about the standard being a good thing, but we have to do some proper QA so it makes sense. One example from the above:

no trailing slash for baseurl
the trailing slash causes issues with .LanguagePrefix
paths should have slashes between each part, e.g. {{ .Site.BaseURL }}/css/style.css instead of {{ .Site.BaseURL }}css/style.css

• If there is an issue with/without trailing slash in Hugo, it is a bug and we should fix that in one place an not in 100s of themes.
• Also I see very few reasons to use LanguagePrefix (use relLangURL etc.)
• Same with {{ .Site.BaseURL }}/css/style.css -- much better to use {{ "css/style.css" | absURL }}

[ghost]

If there is an issue with/without trailing slash in Hugo, it is a bug and we should fix that in one place an not in 100s of themes. Also I see very few reasons to use LanguagePrefix (use relLangURL etc.)

What I'm thinking of is probably a rare use case, so I assumed LanguagePrefix was working as intended. One of the themes I ported, Dimension, runs into issues with the built-in sitemap.xml. In order to make it work, I changed the <loc> to this:

<loc>{{ $baseURL }}{{ .LanguagePrefix }}/#{{ .File.TranslationBaseName }}</loc>{{ if not .Lastmod.IsZero }}

It appears that LanguagePrefix has a leading slash, which means that if we have a trailing slash in the baseurl, we get a result of example.com//de/#foo. I figured the leading slash is intentional.

There might be a better way than what I did?

Same with {{ .Site.BaseURL }}/css/style.css -- much better to use {{ "css/style.css" | absURL }}

Right, it was the first example that I thought of. I actually used {{ "css/style.css" | relURL }} in the head.html.

I don't actually have strong feelings about the trailing slash on the baseurl. I guess we should consider when baseurls are:

• IP addresses: 0.0.0.0 vs 0.0.0.0/
• subdirectories: foo vs foo/
• root: example.com vs example.com/

As an example, the theme Beautiful Hugo uses no trailing slash in the baseurl and does "{{ .Site.BaseURL }}/css/main.css" in the head. I think it would make it easier for people to switch themes if we pick one as a standard. Hopefully that will minimize links breaking when people swap themes.

[rdwatters]

@sethmacleod If you want to take the reins on this and start building out what you think would be a good default theme, I say have at it. We continue to tackle the best practices as part of the code review piece while you build it out. @bep has a good point about baseURL since it's been a common source of consternation among forum users.

If you're willing to take this on, I can work in tandem on a new Quick Start, which is the last big piece of content I need to tackle with the new docs. @budparr is already doing a super-wicked-awesome job handling the homepage design and a potential new news/blog site for Hugo.

[ghost]

@rdwatters That sounds good to me. I'll hack away at it over the next few days and I'll let you guys know when I've made enough progress where it's worth your time to start reviewing.

I plan to incorporate code examples from your docs, and I'll make notes where I've done things differently -- it may make sense for both to use similar code. I'll also be reviewing others' themes and make notes on what we should review for standardization.

I'll do the html templating first before the styling. I would like the styling to be influenced by what @budparr designs, as I think that would help create a distinctly Hugo theme.

[rdwatters]

Making any headway on this @sethmacleod ?

[budparr]

Thought I'd jump in here. I'm about 90% through creating a default theme. Within the next couple of days I'll through it out to the community for vetting.

[RobertCvn]

Any update on this budparr?

[budparr]

Here's the theme I developed: http://themes.gohugo.io/gohugo-theme-ananke/ I personally don't think that particular theme should be the "default" theme, because it probably includes too much (features/design opinions), but I believe it's pretty close. It's been in the wild for a while now, and I think the next move will be to make a pared down version of it for the default.

[mrichman]

The absence of a default theme is a non-starter for many newcomers. I would expect something to happen in the browser if I do hugo new site and then hugo server, with no further configuration.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help. If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open. If this is a feature request, and you feel that it is still relevant and valuable, please tell us why. This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[vassudanagunta]

@bep This is the number one Issue by upvotes. Shouldn't it be reopened and added to a future release so it stays open?

[Jubijub]

I'm very new to Hugo, and finding good and easy to install themes has been a key element in deciding to pick Hugo over Jekyll or Python based alternatives. Unfortunately, the theme I picked (Hugo Future Imperfect) still works, but start to show its age (no support for image bundle, and the way pictures are handled break some basic features (eg : Twitter cards don't show pictures, etc...). It also lacks things like AMP support, etc...

I am therefore set to update the theme to match recent updates, but not having a reference theme will make this harder.

[alfiepates]

I risk adding to the chorus of "Me too!" by comenting, but I happened across this issue whilst doing something else theme-creation-related and wanted to share my tuppence.

Having Hugo ship with a simple, well-documented reference theme (with no minification or other optimisation) would be an absolute boon for those of us developing our own websites around Hugo. I would also like to see a more advanced reference theme available which takes advantage of some of Hugo's more advanced features - The documentation is pretty good, but having the code in your hands is exceptionally useful for helping understand the documentation.

[mwyvr]

I agree that a simple, styling kept to a minimum, HTML to a minimum, complexity - default theme that shows off core features and best practices that gives the new Hugo user a base to run with - would be a terrific advancement. There were great suggestions up thread as to minimum functionality that will also no doubt will help reduce questions from new users too.

What about including the "example" (rather than "default") theme scaffolding directly inside the Hugo binary and add a new capability to hugo gen? The how to could be as simple as:

1. Download the binary
2. Run hugo gen scaffold
3. Run hugo gen chromastyles
4. hugo server

This would avoid all issues with git, operating system differences, user capabilities, etc.

I'm happy to help in any way I can.

[NathanNeff]

Just started exploring Hugo (and ox-hugo) and I agree 100% that there should be some kind of theme which is bundled with Hugo.

One of the issues for me is finding a theme that I feel is trusted.

What is the status of this request?

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.