search

baconjs / baconjs.github.io

bacon.js website
8 stars 19 forks source link

Static site generator #7

Closed philipnilsson closed 7 years ago

philipnilsson commented 11 years ago

We'll need some kind of static site generator, or we're going to end up with a bunch of code duplication and stuff. I'd suggest something based on Node. Wintersmith is the first google result, since I haven't used anything else that'd be candidate #1. Anyone have any other preferences?

raimohanska commented 11 years ago

I've used nanoc quite a bit. It's flexible enough. The (possible) downside would be that it runs on Ruby, but I don't mind that. Are we constrained by github.io supported generators or shall we put the generated site under version control too?

philipnilsson commented 11 years ago

I'd say put it under version control.

I don't really speak Ruby. Is there js wrapper, or would we have to write code in it?

raimohanska commented 11 years ago

My Ruby ain't great either, but there really isn't much code involved in a simple thing as the bacon.js site. And you can also consider this a learning opportunity :) There's not much wrapping needed. You just call nanoc and the site gets generated.

techpeace commented 11 years ago

I've used/reviewed several static site generators, and my personal preference is Middleman. It's has the most functionality, yet it's simple to use. It also has a robust plugin dev community. It's always my go-to when starting a new static site. Our company's marketing site (and blog) are currently run on Middleman.

phadej commented 10 years ago

While experimenting with generating of README.md and html version of api docs, I already made a small DYI static page generator, there's one mustache template for the page and it works quite well.

From api-docs-generating-pov, generating baconjs.github.io is not just gluing html fragments together...

philipnilsson commented 10 years ago

I've recently tried using wintersmith (nodejs) and Hakyll (haskell), and my clear favourite is Hakyll. Of course it'd be somewhat nicer to have a js-based SSG for a js-related site, but Hakyll is so much nicer. You also have easy access to the wonderful pandoc http://johnmacfarlane.net/pandoc/.

Of course, most content would just be in markdown or whatever, so I hereby offer to set something up using Hakyll as one possibility.

On Fri, Jan 31, 2014 at 1:58 PM, Oleg Grenrus notifications@github.comwrote:

While experimenting with generating of README.md and html version of api docs, I already made a small DYI static page generator, there's one mustache template for the page and it works quite well.

From api-docs-generating-pov, generating baconjs.github.io is not just gluing html fragments together...

Reply to this email directly or view it on GitHubhttps://github.com/baconjs/baconjs.github.io/issues/7#issuecomment-33791800 .

Philip Nilsson, +46 2922 4651

phadej commented 10 years ago

I made a quick PR https://github.com/baconjs/baconjs.github.io/pull/13

I would go for something like this. The site wouldn't get any more complicated any soon I guess. But it's still quite easy to integrate api reference generation.

raimohanska commented 10 years ago

It would be exciting to see how Hakyll applies here! (I'm a Haskell fanboy)

Also my guess would be that using a good generator will result to a more maintainable site in the long run, especially if more stuff gets added.

On the other hand, I'd like to use the source material for the readme API and the reference on the site. On the site, we could include live examples for some of the methods. Maybe the API part should be maintained in the bacon.js codebase along with generators that create both the readme and the html file/files for inclusion on the site? This stuff could then be included on the site by the site generator, regardless of whether we use Hakyll or Wintersmith or Oleg's homebrewn solution.

I'm so glad you guys have the enthusiasm and energy to contribute here. Personally I have very little time for Bacon.js right now. Please let me know if there's anything I can help with though!

raimohanska commented 10 years ago

I added @phadej to the bacon.js and bacon.github.io teams to make it easier for you to make the good stuff happen!

phadej commented 10 years ago

I like Hakyll idea as well, though have no experience with it (or any other SSG). And I guess it/something else will suit well if we generate api reference separately (might be a good idea anyway).

It's indeed easier to add api reference html snippet generating code to bacon.js repository, but the generated html is very this repo related, so I vote to have html dependent code here. Just point it where bacon.js repo is (and assuming ../bacon.js) so it could reuse the parts already there.

BTW: And there is noflo-yekyll the blog postl. Finnish functional F(R)P gem (pun intended). But Hakyll is probably safer solution :)