Roadmap to Hugo v1.0

feature
1

Thanks to the awesome community Hugo, gets better with each release. With the latest one we come big steps closer towards Hugo v1.0. But we’ve still some big milestones to tackle on the roadmap.

Therefore, I would compiled a list of features (based on the following feedback) that you would like to see implemented. Feel free to jump into a discussion and share your thoughts and ideas.

This discussion is intended to move this milestones into the spotlight. We also highly appreciate any kinds of contributions.

Roadmap:

These are the parts of Hugo that most of us define as essential for such a release. Until the release of Hugo v1.0 we should have created a stable foundation. This means that we are happy with our data model and interface.

partial rendering

At the moment Hugo rebuilds the entire website even if you change just a single line in a file while saving it. Instead, we could optimize this process: e.g. by only rerendering the post itself and all pages that are associated with it (like tags/category lists or the homepage showing the latest post).

Especially in situations, where you rely on third-party tools in can decrease the performance. Read more on this approach.

Corresponding issue: #1643

localized content and assets

Currently a document is only defined by it’s content and some metadata in the frontmatter. But documents can be more complex and rely on their own assets. Alternatively, we could define a directory and it’s files that would allow more customizable content structures. Read more on this approach.

better asset handling

Example: the community has high demand for the dynamic resizing and cropping of images (e.g. with shortcodes).

Corresponding issue: #1024

plugins: a plugin system would make Hugo even more powerful. Extend Hugo’s functionality easily with a plugin while keeping Hugo itself fast and bloat-free. Some users requested:

We need to develope an interface that defines how plugins can interact with Hugo.

Wishlist:

These are features that are appreciated by users but they shouldn’t block the release of Hugo v1.0. Consider their implementation as independent feature requests.

easier migration: new users have mostly to convert their content. Currently, we’ve a wide variety of third-party scripts. Until now, Hugo has built-in support for Jekyll via an import commands (see #101)

easier deployment: better deployment support to push your generated content to Amazon S3, Heroku, Google Cloud Storage etc.

Corresponding issue: #1543

suggestions for related posts: clearly a very useful feature for bloggers and theme creators.

Go implementation of content formats: currently Hugo relies on third-party helpers written in Python and Ruby. A native implementation in Go would cut the time needed to generate/parse the content. Since it’s beyond the capabilities of Hugo, see it as a request to the Go community.

Corresponding issues:

  • support for native Go implementation of AsciiDoc #1435
  • support for native Go implementation of reStructuredText (reST) #1436
4 Likes
2

I’ve definitely been playing with (and thinking about) SSGs a lot lately. I think Hugo is the best SSG out there. Keep in mind that the following opinions are coming from a publisher, writer, and editor and not a professional developer.

Everything on the roadmap seems great, but I’d like to throw out some suggestions, some of which might not be too popular:

  1. Standardize. Rather than trying to support more formats, plugins, templating languages, etc, I think there is something to be said about just picking one from each and sticking to it. I know this might irritate some people. This seems to be an issue with Jekyll, which has gone through different MD converters, syntax highlighters, etc. As a result, some sites break during upgrades. A 1.0 would be a good idea to pare things down because breaking changes (could be argued) are common. Just a thought for tighter focus/scope.
  2. Write content to .JSON. I know Hugo’s focus is HTML—and I hope the project steers clear of CSS/JS/ES2015/whatever preprocessors and build systems—but I think there is a strong enough rationale behind creating JSON files for indexing (client-side search) and taxonomies/relationships (decouple SPA CMS [#3]).
  3. An SPA CMS Layer. I love the Webhook UI, but the overall build is too slow with bigger sites. I think the CMS should not be part of the 1.0 release and should remain decoupled. This seems like a decent flow—
    • GitHub/Bitbucket: for source control (or hosting).
    • Hugo CMS: An Ember or React SPA that, for example, can write to files in a repo using the GitHub API. If Hugo can write to JSON files for taxonomies/tags, this could then be digested by an SPA for more complex relationships in the CMS (for example, the ability to write “related articles” to the front matter of individual content files). Building locally could include creating starter templates for list/single pages when new content types are created (ie, with corresponding archetypes) in the CMS layer. Previewing and permissions would be essential for any larger static site with a distributed authorship model.
    • Wercker: Watching changes and running Hugo builds. Any tool that watches for changes and triggers a Hugo build would work though.
    • Amazon/Google Cloud/GH Pages: Hosting. Again, anything would work.
    • Fastly/CloudFlare: Caching. Again, anything would work.
  4. +1 for image resizing and optimizing. I think this could fit very well into the standard folder structure for HUGO projects; e.g. static > images > thumbnails and static > images > optimized. Maybe it would just be part of the build in the static folder and not require a separate shortcode so as not to mess with the cleanliness of the markdown. Thumbnail or other sizes could be set in the config file.
  5. More templating functions, intuitive filters and ranges, sorts, markdown flavoring. For example—
    • The ability to sort by any custom metadata within the front matter, even at the single-page level. (My apologies, since I think this might already be possible, but I just haven’t gotten it to work.)
    • Rename existing methods to be more intuitive or align with some of the “standards” organically built out in previous versions of Hugo (eg, using .Node.Pages instead of .Data.Pages and reserve the .Data keyword for actual data files)
    • Triple tics. This doesn’t fit here as much as it does with BlackFriday, but I think this element of GFM is pretty darn common at this point.
  6. Revamped Docs. This is probably the area where I can be of most help (if at all). Here are a couple ideas:
    • Include both templating and output HTML in all samples. This is great for beginners.
    • Don’t merge a feature until the docs have been written for the feature. This prevents merged/added features that are quickly forgotten by the developer team or possibly go undiscovered by end-users (that is, developers building with HUGO).
    • Required “Last Updated” with each page or section of the docs.
5 Likes
3

Hugo already has support for reStructuredText and AsciiDoc, so this item could probably be removed from our roadmap. They were “experimental” for a while only because there are no native Go implementations for those content types. We use third-party Python and Ruby tools to do the content generation. These are really outside the scope of Hugo since they would a major undertaking in their own right, so we just support them with “external helpers.” More info on the AsciiDoc+Go “call to action”:

4

@moorereason I’ll update the readmap above.

Should I make a pull request that updates the referenced issues of the content formats? Instead we could link to the issues regarding their native implementation in Go.

The issues regarding the pagination also seem to be deprecated, since the issues are closed too.

Pagination (See #96, #750)

The same applies to the jekyll import command:

Import from other website systems from Jekyll (See #101)

5

@rdwatters thanks for your detailed opinion.

Keep in mind that the following opinions are coming from a publisher, writer, and editor and not a professional developer

That’s exactly what we want. Hugo should be accessible and productive for all kinds of users ranging from regular bloggers/editors/publishers to developers. All kinds of them have different needs and see some things from a different perspective. This would allow us to use this insights to make Hugo better.

  1. So far, I think, we’ve a very good coverage of content formats. Users that switch from Python- or Ruby-based SSG might be more comformtable with the content format the they already know. The main problem we’ve so far is that we rely on third-party implemenations written in the languages that I mentioned above. A native Go implementation would increase the content generation even more. There are already some projects whose progress we are tracking, but they don’t seem to be ‘ready for production’. Take a look a the wishlist’s issues in the first post.

  2. This is indeed a vary useful feature there’s already an issue about it on Github. The roadmap should give you more information.

  3. That would be really awesome. Even users who don’t know the command line, Git or don’t use text-editors as they primary tool for blogging could easily start using Hugo. But some themes require a bit of setup (mostly copying some files), which can’t be handled automatically without defining a standard. BTW: @hacdias created a really nice front-end as plugin for the caddy server project. Checkout the repo / his forum post. Alternatively, @stayradiated build rango as a stand-alone frontend.

  4. We’ve already an issue about image resizing. Feel free to leave your feedback about a possible way to implement it.

  5. Template shortcodes:

    • Filtering based on metadata defined in the frontmatter is already possible with the where template functions. There are several posts regarding filtering in this forum, like this one
    • There are already plans to rewrite the implementation of nodes.
    • GFM works out of the box thanks to BlackFriday. Did you had some problems?

  6. Also in this department we had some discussions.

    • It would be great if you would create pull requests that improve the docs. More examples would be indeed very helpful for Hugo-primers. Maybe this helps to understand some concepts in Hugo-
    • I can understand that users could be confused by features that are mentioned in the release notes but not documented. This is currently the case for some features. Many people wanted a new release of Hugo but it would also be bad to don’t include some features on ‘the last mile’. In my opinion did @spf13 and the others a good job. Normally, pull requests are merged with docs.
    • Adding a “Last Updated” status would be a one-liner in the docs. Should we add it @bep?
1 Like
6

Yes…

7

Content JSON files

While I agree that writing content to JSON files does reduce the barrier for entry for features such as search and related post recommendation I honestly don’t believe that it’s absolutely necessary. That being said, I haven’t been able to quite wrap my mind around a better way of doing things so while I’m not entirely against the proposal I’m not sure that I’d mark it as a v1.0 requirement. Honestly, what percentage of static sites truly depend on native search?

I’m actually quite flexible on this one. If someone who truly cares about the functionality is able to commit some production quality code, go for it, otherwise, I don’t think it should be considered a blocker.

Native internationalisation and localisation support

This is, without a doubt, a v1.0 requirement and I say this as a native speaker of English who, having a very limited appeal, doesn’t typically worry about such functionality.

Plugins

People might come for performance, ease of deployment, etcetera, but they stay for addon functionality which is important to them.

Migration

Personally, migration from other platforms doesn’t fit what I view as a core issue. Yes, it’s absolutely important, but, is there any reason that such tools can successfully exist outside the release structure and timeline of Hugo’s core?

Deployment

See above.

Related posts

The functionality required for this feature is intrinsically linked to the search functionality and in my opinion should be treated as such.

Image resizing and cropping

This is the definition of a core requirement.

Native implementation of core formats

While not everyone may agree I personally believe that this is also core to Hugo. Yes, in an idea world we’d only have a single markup to rule them all. Unfortunately, this isn’t such a world. Markdown, AsciiDoc, and reStructuredText are today’s de facto standards when it comes to safe markup languages (I’m intentionally ignoring HTML as it is in no way safe). Two core feature of Hugo are its blazing speed and single binary (i.e. zero dependency) distribution. Without native implementations of the core formats one or both of these points is sacrificed.

Documentation

Absolutely. This bullet point is more than a little personal for me. Since discovering Hugo, I had planned to contribute heavily to the documentation effort. Unfortunately, a variety of personal/family circumstances have made that essentially impossible. This is something that I plan on changing in a major way in the coming year.

8

@voxadam thanks for your feedback.

Search

I agree, that not all users require a search for their website. But larger sites like docs (e.g. those of Hugo) or other content-heavy ones would benefit from this feature. This way users don’t need to run a task-runner like Gulp or Grunt.

Plugins

Creating a larger ecosystem with plugins would be a great opportunity to create extensions for common usecases. Users would just download the plugins that they need while Hugo should remain lightweight.

Migration

Having the migrator tools as external tools would make them independet from the Hugo release cycle, but it would also mean that we would have to maintain them as another project. My concern is that those tools we will pay just little attention over the time. Having them directly integrated would force us to keep them up to date. But it would also mean that we would have to exclude the Jekyll importer that is already implemented, if we want to the treat the migrators as external tools.

Related post

It might be right that is a nice enhancement and not a number one priority. Some people requested such functionality and we could implement in on the go while implement the other milestones. I just wanted to give it some place in the spotlight.

Documentation

Improving the documentation would be really awesome if you could contribute in this department. Especially beginners should find a better way to get started with Hugo.

@rdwatters mentioned already some great ideas in this direction:

Include both templating and output HTML in all samples. This is great for beginners

9

I agree, that not all users require a search for their website. But larger sites like docs (e.g. those of Hugo) or other content-heavy ones would benefit from this feature. This way users don’t need to run a task-runner like Gulp or Grunt.

@digitalcraftsman, I absolutely agree that search needs to be on the docket as a planned feature, it’s a really important feature that people already want. I’m only questioning its being a requirement for v1.0. Is there any reason that a proper integrated search solution couldn’t be targeted for say, v1.3 (I totally pulled that number out of thin air)? Integrated search is an important and rather complex feature. I want to ensure that a search less than fully baked search functionality isn’t shoehorned in just to get v1.0 out the door. As a corollary, I’m not entirely convinced that v1.0 should be held back for search.

I’m okay with being wrong on this one; it’s just a thought.

10

@voxadam v1.0 is a big number and a lot of work has to be done until we reach it. In my opinion, the integration of the plugin system is the most time consuming and hardest milestone because it effects so much parts of the codebase.

Integrating the search seems to be relatively a relatively smaller task that could be done in that period of time, I think. But it should block the final release of v1.0

After starting this discussion it would be interesting what the members of the ‘core-team’ of Hugo think. Where do you see Hugo in the future? What are your prior milestones that are necessary to call a release v1.0?

/cc @spf13, @bep, @anthonyfok and others (it’s hard to define ‘core-team’)

11

My 50 cents is to be a little bit pragmatic about this, at least with the current “work force”.

Me myself, I only implement according to my own road map, that is: What I currently need or find interesting/challenging.

There are many nice to haves, but the only two things (that I can think of) that I really need now is:

  1. A proper way of handling the Nodes (front matter etc.). This is a problem I have thought long enough about and should be ready to implement. Not too hard, me think.
  2. A related posts feature. I kind of agree that it’s search related … but it really isn’t the same-same, in my head. This is a harder problem to solve in a good way. I have started on a prototype a couple of times …

As to search, I think Hugo should support that (as in: provide a way to extract the data in a index-friendly format), but it should live outside Hugo.

1 Like
12

I’d like to clarify my previous comments and say I’m more interested in the ability to just write to JSON. I see Hugo as a single tool for managing structured content, and I see JSON as content/data, not logic or presentation.

I’m not a go programmer, but it seems like a simple enough feature and extends the functionality of Hugo considerably, but not for just search. It also adds opportunities for an SPA CMS layer (see my comment above), more async options for improved UX, etc. I would agree that a full-tilt search solution might protract a V1.0 release unnecessarily.

1 Like
13

I love this thread. It’s great to see the passion that everyone has for this project.

I think about 1.0 a bit differently. For me 1.0 is the milestone when we have a stable foundation. This means that we are happy with our data model and interface. I think far too often people release 1.0 long before things are stable. It took us thousands of users to recognize that our node implementation isn’t as flexible as we need it to be.

In my eyes, as soon as we have this stable foundation we can release 1.0 and then a lot of awesome things can be layered on top of it with point releases.

As I’m thinking about it today there are four things that we need to improve to get to a stable foundation.

1. Nodes.

Initially as I designed Hugo I thought that a lot of the way other CMS / SSGs designed their content data model was backwards or broken. Wordpress has everything as a post… then non post things are oddly hacked in. Jekyll is similar but has posts and then dedicated static pages. These make sense given their blog specific roots, but are not a solid foundation for a full content CMS. Drupal has dynamic (almost object oriented) approach to their content model where the base is a Node and Pages and other content extend the base. I took inspiration from this approach and used similar terminology. In Hugo content would be created by the author and nodes would be created by Hugo. I also made the decision that content should live where it wants to live… meaning /content/post/foo.md becomes /post/foo.html. This proved to be a very friendly and intuitive interface for creating content. It was the right interface because it catered to the creator of the content, not the generator.

Now we have learned that this foundation has a few holes in it. People want to be able to have some content on their site that’s hidden from lists. People want to be able to not only define the layout of their taxonomy and other node pages, but provide content for them as well. In essence a lot of the functionality that was in the content layer needs to move down into the node layer. The technical challenges aren’t too hard, but the interface design is tougher. I’m still not sure how to make it so that a given file translates into a node and not content. I’ve thought of a few things here and would love to brainstorm with others on it so we come up with the right solution.

2. Localized content & assets

If I was going to design Hugo today I would do it a bit differently. I would have a post be represented by a directory and a set of files in that directory. Front matter is a novel idea, but it really stems from the concept that a single file represents the entirety of content. In practice a post is often made up of metadata, content (which sometimes spans multiple pages), and media. While the current approach of separating /static and /content makes a lot of sense in a general way… for things like sitewide assets like CSS & JS, it becomes a bit laborous to manage post assets independently of the content.

It would be really nice to be able to have something like

/content/post/foo/
   ->       content.md
   ->       metadata.yml
   ->       headerimage.png
   ->       picture.png

This is a very flexible approach that opens a lot of possibilities (multiple pages of content, multiple languages, etc).
The challenge is how do we unify this approach with the current approach of a file representing the entirety of the post.

3. Better asset handling

I’m not sure what this looks like. Fundamentally it’s a framework which allows for things like image processing, css preprocessing, etc.
I don’t want to rebuild gulp or similar systems, but I’d like to be able to allow for these kind of operations to happen within the context of Hugo.

4. Partial building.

This has been a long asked for feature. It’s hard to do and to date we’ve focused on making Hugo fast enough that it’s often not an issue. It becomes more of an issue when Hugo starts leaning on 3rd party applications to do things more as these tend to be significantly slower than Hugo itself.

I’ve given this a lot of thought and I believe I have a good model for how this can work and in a pretty simple and straightforward way. I believe that the approach that others have taken of trying to discover what needs to be rendered by examining a rendered site is fundamentally broken and at our current speed would actually be slower than Hugo is today. I think by leveraging the watch system we can implement a partial render in a very efficient way by tracking each file that changes and marking all associated content as dirty. Then in the render stage we can limit the processing to only dirty content.

For strictly static content this complexity isn’t needed and there’s already a very straightforward PR on improving the static file copy to only examine the changed file when watching. https://github.com/spf13/hugo/pull/1671

I believe this is it from me.

Reply to other suggestions

To respond to other suggestions in this thread.

native i18n and l10n support is very important. I don’t understand it well enough to suggest I can really qualify what needs to happen here. Luckily Hugo has a lot of bi-lingual developers who this affects significantly. I believe that my #2 point could be a part of this.

Could happen before or after 1.0:

  • easier deployment
  • related posts
  • easier migration
  • write JSON
  • Go implementation of AsciiDoc, ReST, etc
  • template functions
  • revamped docs / website

I hope they all happen ASAP, but we are a community of volunteers each having their own motivation and focus so they will happen when someone feels motivated to do it. I don’t see any of these being predicated on 1.0 or blocking the 1.0 release as none would have breaking changes to the interface or foundation.

8 Likes
14

Partial rebuild is an important addition to the list.

There is one thing I now find myself thinking about. How would partial rebuild interact with a related pages/posts feature? It may be obvious but I’m running on a suboptimal amount of sleep at the moment.

I really like the idea of a directory per post layout. It feels cleaner/neater to me.

15

Steve,
I love pretty much everything you’ve said and agree whole heartly, esp. on #1 & #2 (and I’m curious how #2 would affect #1). One thing you didn’t mention that I would add to your 1.0 list of foundation items:

Plugins

Plugins in Go are an intriguing problem. It’s probably beyond my skill set, but I’ve been contemplating how that would work. What types of plugins do we allow? Where do they plug into the build chain? What types do we pass them and what do they return?

In looking into all of this and trying to familiarize myself with the whole build process, I get the sense that APIs defined within Hugo may need to be altered once plugins enter the scene. I think that’s part of laying a solid foundation for the future.

One other side benefit I hope to see from opening Hugo up to plugins is that we become much better about adding godoc comments to all of our exported types and functions.

Postscript

@digitalcraftsman, let’s get one this straight: any definition of the core team should not include me. :smiley:

1 Like
16

If it should live outsite of Hugo it sounds like an interface that could be used by a plugin. Or did I misunderstood something?

17

What functionality should exactly be supported by a SPA CMS that’s designed for Hugo? Goes it beyound basic CRUD operations with content files?

18

In my opinion plugins are a nice way of implemented custom functionality without bloating the codebase of Hugo.

As you mentioned, we need a define an interface for plugins to allow them to interact with Hugo. But implementig such an interface should be carefully planned since it effects a lot of parts of the codebase. To quote Steve:

Therefore we would have to ask ourself this question before releasing v1.0. On Github there was already a little discussion of possible approaches but it didn’t got much attention.

19

Yes, this is still something in toying with. I’m taking a mobile JS app course this semester. As part of my application, I needed to put out a final project idea and an SPA CMS on top of Hugo was one of them. I’d want for users to be able to create complex relationships between pieces of content (or content types) from within the CMS.

20

That sounds very Interesting. It’s somehow like rango bit with a more advanced feature-set.

Currently, it’s only possible to work with the file’s content and metadata itself to build functions for a SPA CMS. Without an API (which is still just an idea) you’ve to write many things yourself by creating connections between the content and metadata (e.g. posts in the same category).

Let’s say you would write an SPA CMS as mobile app. Where exactly resides Hugo in your stack?