Explore alternatives to Hugo

[Mr0grog]

I think it makes sense to move ahead with #68, which uses Hugo, but mostly because that keeps what’s changing there small (just content and menus, not the whole framework).

However, we noted the following in that PR:

@Mr0grog: I’m also not 100% sure Hugo is the best fit (this nav bar code is horrifying, and while it could be better, it would still be pretty complicated because of Hugo’s lack of plugins)

@olizilla: Strongly agree. I find Hugo's template system deeply bizarre. I feel I must be missing a super strong grounding in Go templates. Anything even mildy data driven gets really complex. And the error messages are infuriatingly cryptic too. I'd gladly discuss moving to something else, the challenge is finding a static site generator that can deal with relative paths for links and resouces like css background-image urls and inline styles.

Let’s use this issue to explore/discuss potential tools. (Off the top of my head: maybe Gitbook? I used it for the research and I know it can be customized, but I don’t know quite how extensively.)

Running list of suggested tools:

• Gitbook (Both a hosting service and a free, open source static site generation tool. Used in @flyingzumwalt’s Decentralized Web Primer)
• Gatsby.js (Being used for the new js.ipfs.io; make sure to check gatsby-plugin-ipfs)
• Metalsmith (More of a plug-in framework for static sites)
• VuePress (See also the “book”)
• Hexo
• Sphinx

[0x-r4bbit]

Hexo is a nice site generator as well: https://hexo.io/

Comes with a great ecosystem. Plus, it's written in JavaScript, so it'll be relatively easy to a) change it to your needs and b) get outside contributions.

[magik6k]

Sphinx might be a good option - http://www.sphinx-doc.org/en/stable/index.html

[dignifiedquire]

libp2p, multiformats, ipld and ipfs websites are all implemented using Hugo currently. And it has been really hard to make sure relative linking works with any other framework. Is there a specific reason to not use Hugo, given that these frameworks all pretty much have the same functionality?

[Mr0grog]

Is there a specific reason to not use Hugo, given that these frameworks all pretty much have the same functionality?

I hope the concerns here were clearly addressed in the issue description and in #68, but to reiterate: the templating system can be very hard to work with and not able to work around that by extending functionality with plugins makes some parts of Hugo pretty painful (for example, there are a lot of nice features we could add to the built-in Markdown support, but the only way to do so within Hugo would be to have a separate source directory that builds Hugo’s content directory that then builds the site, which is kind of ridiculous).

I think it’s well understood that relative links are a big problem. In #68, I also stated that there’s a huge value in keeping similar workflow and tools across the different sites. A change here certainly isn’t the most high priority and we probably ought to have a prototype that demonstrates it can be much easier to work with and/or more flexible first.

[dignifiedquire]

Thank you for iterating, I missed to read the details in #68, before commenting, sorry about that.

[meiqimichelle]

It seems like we're staying with Hugo for the time being, in large part because, as @Mr0grog said, there’s a huge value in keeping similar workflow and tools across the different sites. I'm going to close this issue for now. We can re-open in the future should we want to explore transitioning all or most of our sites off Hugo.