HTML Includes

[chriscoyier]

Would be nice if each demo had it's own individual component page, and those chunks were included in the main demo page.

1. Grunt includes https://github.com/vanetix/grunt-includes (never tried)
2. Jade includes (yet another dependency)
3. $.load with jQuery (might load janky)
4. PHP includes (yet another dependency)
5. Something else?

[joeybaker]

iframes?

[mikefowler]

If the demo pages were hosted here on Github we could potentially use Jekyll-based includes.

[foleyatwork]

I think we should stay away from rendering on the client. I'm all for using Jeckyll or Grunt to compiler static pages. Seems like PHP would be overkill for this project.

[andismith]

I've forked the project and am putting together a quick demo of how this would work in Jekyll (which Github compiles for you).

[benschwarz]

Using Jekyll with grunt / npm tools is a bit of a pain in the ass too… although pretty possible.
I'd opt for something in the npm / grunt ecosystem. @chriscoyier — perhaps that can be tonight's 20 min super challenge?

[chriscoyier]

I like the idea of Grunt too - so all the build-y stuff is all together and grunt watch is the only thing you need to do.

I looked at the grunt includes project, and it seems kinda perfect, but I didn't understand exactly what file you author the includes in. Would we make like index.author-here.html which gruntifies to index.html ?

[andismith]

Sounds like your going to do it a different way now - but here's how you'd do it in Jekyll in case you change your minds. The # by each demo let's you go to its individual page.

http://andismith.github.io/Effeckt.css/

[benschwarz]

Thanks @andismith, you rock!

[andismith]

No problem - I need to go to bed now as it's gone midnight. I've created a pull request if you decide to use Jekyll. If not, feel free to ignore it! Night!

[benschwarz]

To be clear: Whichever method we run with, we're aiming to have the source files kept in the top level, and basically have the css & html written out to /dist — That way we can keep deployment of the website / demo much more simple.

I'll review your implementations overnight… Thanks for the awesome activity!

[andismith]

May I suggest a third (fourth?) alternative which is to use https://github.com/assemble/assemble ?

It gives a bit more flexibility with variables - and keeps the content in page. Basically, it works like Jekyll but all in a Grunt environment. I'll try and get a demo together.

[benschwarz]

If I were to do it myself, I would start with assemble

[andismith]

Cool, I'll put together a quick demo after work (in about 3/4 hrs)

[chriscoyier]

So right now we have two pull requests that tackle this same issue. Soon to be a third. Can we talk pros/cons? I'm unsure about which one we should pick.

[grayghostvisuals]

If it's Jekyll then we're back to a ruby dependency which we're still discussing the removal of at this time #45. Grunt EJS Static fits very much inline with the discussion we're having at the thread I've linked to.

[andismith]

Assemble doesn't use Jekyll so doesn't have a Ruby dependency but has a similar syntax.
It allows for YAML variables within our pages, so you're not just adding static files with no ability to change your page based on what's included.

See https://github.com/assemble/assemble for more info on Assemble.

Btw, I don't think there's a wrong solution here.

[grayghostvisuals]

@andismith

I'm liking me some assemble right now. Seems it can do as much or even equal to what Jekyll can do and falls inline with our "No Ruby dependency" discussion. Although the assemble project is still young the site and correlating documentation is really well done. Honestly the docs for assemble are way better then the grunt ejs static docs.

From what I've quickly read so far you can spit out directories and accompanying files of your choice to custom destinations if I'm not mistaken. Maybe we can ping @doowb to help explain assemble a little more to us?

I think Chris might say the same too, but we shall see once he finds the time to look at it himself and report back.

[doowb]

@grayghostvisuals I'd be happy to help. We build our documentation in a similar way for assemble and for our handlebars-helpers repos. @jonschlinkert is really the brains behind building the documentation and the setup process, but I can help.

We use handlebars for our templates because of all the helpers that we've built, but the files don't need the handlebars extensions since you just tell assemble which file to use and tell it to use the handlebars engine.

I'll throw something together that works like @andismith's jekyll example and post back.

[andismith]

@doowb - You working on this now? If so, I'll stop working on my demo.

[doowb]

@andismith - Yes. I'm just about done.

[jonschlinkert]

Yeah @chriscoyier we've love to take a shot at putting this together with Assemble, we created it to do what you're describing. (@grayghostvisuals, thanks for the great compliments! The docs are only a week or two old, so we still have a lot to push up)

[shaekuronen]

Assemble looks great, has a ton of features, have been meaning to try out...

With grunt-ejs-static, the idea is to do way less.

@grayghostvisuals is right, docs are light, but it's almost entirely a boilerplate using established grunt plugins or node modules, which do have in-depth documentation.

The almost part is where grunt-ejs-static comes in, and here's what it streamlines:

-- Generating Static HTML from Includes
-- Using Global or Page Specific Variables from a JSON file

That's it!

If that feature set makes sense for Effeckt, sweet. If not, would love to contribute in any other way, as this project is going to be awesome.

[grayghostvisuals]

@doowb @jonschlinkert
Thanks guys! Looking forward to this. I'm all for seeing this in action as long as Chris feels the same. The sentiment is that we definitely don't want anything w/Ruby dependencies so far. Maybe we can have this on a sep. branch appropriately named "assemble" to see this in action and try out? Is that too much to do?

[doowb]

I have a simple setup done based on @andismith jeykll PR. Here's the repo and Here's the pages running on gh-pages.

By running grunt demo it builds the pages and places them in /dist as requested by @benschwarz. It also copies the assets to /dist/assets and those are referenced in the pages.

I also added grunt deploy which will take all the files from /dist and move them to ../gh-pages. This is a convention I use to make it easier to deploy to the gh-pages branch. I basically have the repo cloned twice, once for the master branch and once for the gh-pages branch. I keep the gh-pages folder on the gh-pages branch, so I can push files into it, then just commit and push those changes. I'm sure this part of the build could be modified if other's have a better approach.

Again, this is a simple way of using assemble. There are some more advanced features and helpers that I could throw in there to reduce the amount of setup needed when a new demo page is added. Please let me know what you think of this first pass and I'll work on the second pass in the meantime.

Thanks.

[jonschlinkert]

In case this helps fill in some gaps:

• Assemble was specifically created for generating components, sites, and accompanying documentation. For instance, you could create a bunch of components for a web project, and then use Assemble to a) build the components individually, b) or wrap the components in layouts and build each component into its own page with or without accompanying documentation (you could, for instance add a custom property to the task options to either show or hide documentation: options: { docs: true }, then any docs wrapped in {{#docs}} block expressions will render), c) build pages from the components to construct a site or web application. Etc.
• Assemble's docs are constructed from components, pages, layouts the way I'm describing, although I'm embarrassed to have anyone look at the project structure lol, since it's by no means idiomatic or representative of how easy or clean Assemble really makes projects.
• Assemble is just a Grunt.js plugin, so it follows the same conventions as other plugins. You could use assemble or grunt-ejs to handle the templates, and everything else can be filled in by other Grunt plugins

Last, @doowb and I are totally willing to roll up our sleeves and fill in whatever gaps exist with Assemble. This is exactly the reason we started the project.

[jonschlinkert]

@doowb created the example project while I was typing my answer if that gives you any indication of how easy it is to use and be productive ;-)

[jonschlinkert]

@grayghostvisuals sorry I feel like I'm commenting too much but I somehow missed the last comment you made. Whatever you guys need, let us know and we'll get it done. Have a happy 4th guys! I'm going to go celebrate with the family.

[grayghostvisuals]

@jonschlinkert no way jose. No worries at all. Appreciate you hopping over here and lending an ear. Happy4th as well. I think it's best now to let others comment with their feedback so we can eventually arrive at a decision.

[cowboy]

In case it helps, see what I did here to deploy to a gh-pages branch:

https://github.com/cowboy/wesbos

(There's a lot of other single-page app RequireJS stuff in there that you can ignore... Unless you don't want to ignore it)

[chriscoyier]

Wow this is sweet!

I'm kinda holding off on working on the demos because I was thinking it would be a merge nightmare.

Is it possible to get a pull request of what @doowb did there and get it merged in?

[doowb]

@chriscoyier I'll submit a PR of what I have now. I'm looking at grunt-gh-pages that @cowboy is using, but I think I have a configuration issue, so I'll leave that out for now.

[grayghostvisuals]

So here's my experience so far (and obviously I'm just getting used to using assemble).

From a forked copy I can only push to the gh-pages branch of that fork when executing grunt deploy. The problem I ran into as a contributor was that I couldn't send a PR of that branch to the upstream's gh-pages branch. What I ended up doing was cloning the main repo as the origin solely. This allowed me as a contributor to run grunt deploy in order to update the main repo's gh-pages branch. You'll see the commit message just says "Updates" which is vague and maybe I missed something. #newbonwheels

[doowb]

From your fork, you couldn't select the gh-pages branch and submit a pull request to the main repo that way?

The grunt-gh-pages is something outside of assemble. I'm sure there are other ways of doing this for submitting pull requests.
I was also thinking of the entire workflow and I think I missed something originally. I didn't update any of the other tasks to look at or use the new dist folder. If the intention was to also build the sass files and put them in dist, then I can update the grunt file to get this working.

I'll take a look at this in an hour or two when I get back home.

[benschwarz]

I really think deploying from /dist with git's subtree push is the best method to keep everything simple.
Because then anyone can send a pull request of the site prebuilt as well… which'll make life easier for the maintainer and the submitter.

[grayghostvisuals]

@doowb Yeah, I have no idea atm if this is an assemble config or a github deal, but I couldn't send a PR of my gh-pages branch from my fork. If there's a solution here to allow PRs from forks of the gh-pages branch that would rly help to smooth out the workflow. I also agree with @benschwarz that running git subtree push --dist origin gh-pages is pretty nifty as well. Too early to say though as we're all getting used to this still and working out the kinks. Let's see what happens. 🍻 🍻

[doowb]

@benschwarz @grayghostvisuals I hadn't seen git subtree before. After reading about it here and playing around with it, I got it working properly.

This yeoman document also shows how to do it, but I had to do a few things before it would allow me to try to submit a PR on github. These are the steps I took to get it to work properly:

• Remove the dist folder
• Add a subtree from the Effeckt.css/gh-pages repo:
  • git subtree add --prefix=dist --squash https://github.com/h5bp/Effeckt.css.git gh-pages
• Do a normal build:
  • grunt
  • grunt demo
• Commit my changes to master like normal
• Push the subtree to my gh-pages branch:
  • `git subtree push --prefix=dist origin gh-pages

I'm a little new to this part of the process, so I hope this is correct and helps someone else. It might be useful to be added to a deployment document similar to yeoman's.

[chriscoyier]

This issue is a wrap! Great work everyone. I'm going to start a fresh thread on how to handle gh-pages

[benschwarz]

@doowb - Sorry, I wish I'd linked the yeoman page, might've made it a bit easier on everyone.
Subtree push is such a dope feature of git.

Super work everyone!