Converted the site to Jekyll

[santheo]

The repository now has all the configuration in place to work as a Jekyll-generated site on GitHub pages. You can see how it'll look by going to http://santheo.github.io/tacofancy/.

Two steps to getting it to work: first, you need to create a GitHub pages account for yourself. That's as easy as making a project called sinker.github.io and pushing it live. Maybe put an index.html in there for good measure. Second, create a gh-pages branch on your tacofancy project, and push that live. Then the TacoFancy site will live at sinker.github.io/tacofancy. That's it.

To run the site locally, you need to install Jekyll. Just navigate to the directory and type 'bundle install'. If that works, you then just need to type 'make server', navigate to 0.0.0.0:4000 in your browser, and you should be golden.

The site is configured to run at root locally and at /tacofancy on your GH Pages server. If you ever move to this to a domain (or point a domain at your GH Pages account), you'll need to change that. Easy to do: just modify the 'baseurl' setting in _config.yml.

The site runs on Bootstrap 3. I've added almost no extra styling to it beyond what comes out of the box. But this should give you and others a good starting point to style away.

Jekyll has a plug-in structure, so you & others could easily fold in all the automation efforts so the index pages get built up automatically. That'd be nice.

[santheo]

I should note that because you need a gh-pages branch for GH Pages to work, you're going to quickly have the public site out of sync with master. You'll have to constantly merge and push to keep things up to date. Two solutions:

• Change the default branch on your project from 'master' to 'gh-pages'. Then all pull requests will be made against gh-pages, and gh-pages will become your de facto master.
• Create a tacofancy organization on GitHub and transfer ownership to it. Then change the repo name to tacofancy.github.io, which is a GH convention for automatically making a GH Pages site. In that case, the master branch has code that shows up on public site.

I've actually already created the org for you. I'll invite you then transfer ownership once you're there.

[dansinker]

my brain is spinning.

wait what?

[dansinker]

So there's a lot to think about here. I'd outline the main topics of consideration as:

A) Abstracting away the convention of github repos and turning tacofancy more into a site. B) Adding additional overhead to submissions in terms of having to include the (small bit of) YAML frontmatter that Jekyll requires C) Moving the whole thing to a different repository

So for me (and I want to leave this open for a while for discussion), (C) is probably a smart move no matter what. Tacofancy has taken off quickly enough that it seems like it could handle the weight of its own org repo (would also be a cool way to catch the various tacofancy-inspired projects by forking them into the org repo too).

As anyone that's been involved in the "data standards" discussion threads, I'm a broken record about ease of submission, and any bit of additional overhead feels like it's a barrier to entry. And so (B) makes me a little nervous. Does Jekyll, when seeing a md file that doesn't have frontmatter, just render it without a template, or can we set a default template that will automatically frame md files, with or without frontmatter?

But I think it's (A) that I'm wrestling with the most. There's something nicely janky about this existing purely as a repo vs existing as a website. By doing so at a conceptual level, you have all the tools for forking & submitting right there next to the actual content. And by not dressing it up at all, you also keep the thing very approachable in terms of a "Hey, I could do that too," kind of thing.

All that said, I'm going to leave this open for some real discussion, because there are a shit-ton of PROs to all this as well.

[santheo]

Jekyll will definitely render a non-YAML'd .md file sans template, and the result will simply a page showing all markdowned content converted to html. But there'll be no styilng, so it'll look worse than how GH renders it in their preview. They obviously are applying their own styles so things look nice.

I take your point, and apologies for presuming this was a desired step. I just figure this would be a natural way to navigate the repo. I get that one can navigate through the GH repo interface, but it lacks some important conventions that enhance usability:

• The base URL is not easy to remember. You can't assign a domain to a GH repo.
• There's no navigation to give you a sense of where you are, and what's the scope of the site.
• The previews on index pages start low on the page, below the list of files in that directory.
• The list of recieps show underscored filenames, not capitalized, spaced titles.
• The content is surrounded by swaths of unnecessary — and possibly distracting — GitHub chrome.
• It's not mobile-friendly. (See this screenshot.) The READMEs get truncated on GH's mobile view, and sometimes aren't even shown.

Jekyll also offers some nice features that would alleviate some of the pains of keeping those index pages up-to-date. You can write plugins that auto-generate index pages.

Now, the need to create front-matter is a little finicky, I agree. It'd be grand if Jekyll offered an even-more user-friendly, implicit way to add content, wherein it was allowed to assume that a file's directory indicated the layout template it should use. Then users would just need to include one piece of metadata per file: the title. (Which arguably is a requirement you already have, in that users need to learn how to mark the title with the right Markdown syntax.) Someone should build that.

So, anyway, conclusion: my angle on doing this was: TacoFancy already is a site — loading github.com/sinker/tacofancy in their browser is how people are going to navigate it — so let's just make it one that's easier to use.

[dansinker]

Don't get me wrong, I think there's a lot lot lot of upside to this approach, just want to talk it through a bit more. On Nov 6, 2013 10:41 AM, "Sandor Weisz" notifications@github.com wrote:

Jekyll will definitely render a non-YAML'd .md file sans template, and the result will simply a page showing all markdowned content converted to html. But there'll be no styilng, so it'll look worse than how GH renders it in their preview. They obviously are applying their own styles so things look nice.

I take your point, and apologies for presuming this was a desired step. I just figure this would be a natural way to navigate the repo. I get that one can navigate through the GH repo interface, but it lacks some important conventions that enhance usability:

• The base URL is not easy to remember. You can't assign a domain to a GH repo.
• There's no navigation to give you a sense of where you are, and what's the scope of the site.
• The previews on index pages start low on the page, below the list of files in that directory.
• The list of recieps show underscored filenames, not capitalized, spaced titles.
• The content is surrounded by swaths of unnecessary — and possibly distracting — GitHub chrome
• It's not mobile-friendly. The READMEs get truncated on GH's mobile view, and sometimes aren't even shown.

Jekyll also offers some nice features that would alleviate some of the pains of keeping those index pages up-to-date. You can write plugins that auto-generate index pages.

Now, the need to create front-matter is a little finicky, I agree. It'd be grand if Jekyll offered an even-more user-friendly, implicit way to add content, wherein it was allowed to assume that a file's directory indicated the layout template it should use. Then users would just need to include one piece of metadata per file: the title. (Which arguably is a requirement you already have, in that users need to learn how to mark the title with the right Markdown syntax.) Someone should build that.

So, anyway, conclusion: my angle on doing this was: TacoFancy already is a site — loading github.com/sinker/tacofancy in their browser is how people are going to navigate it — so let's just make it one that's easier to use.

— Reply to this email directly or view it on GitHubhttps://github.com/sinker/tacofancy/pull/69#issuecomment-27889714 .

[santheo]

Oh for sure. Sorry -- I wasn't trying to be defensive. I just wanted to spell out what I thought those upsides were.

[knowtheory]

It depends what the objectives/priorities are i think.

Is the goal to make an attractive collaborative taco recipe book/site? Is the goal to explore git(hub) as a collaborative authoring/editing system? What're the priorities of those two things?

My objective in https://github.com/sinker/tacofancy/pull/68 was to start from the dumbest most minimally invasive point of automation, partly out of a desire to keep the structure of the repo as clean/clear to non-code contributors.

A hybrid is probably possible by using the tacofancy repo as a git-submodule within a separate Jekyll repository, so that the authoring/editing environment is still clean/clear.

[dansinker]

"A hybrid is probably possible by using the tacofancy repo as a git-submodule within a separate Jekyll repository, so that the authoring/editing environment is still clean/clear."

@knowtheory can you expand on this a little? Talk to me like I'm stupid. BECAUSE I AM.

[dansinker]

Also, Jekyll or not Jekyll, I'm wondering how @evz's API factors into all this. Couldn't a site also be built on top of that?

[evz]

I can even add CORS headers if you want it all client side. If we get the tags convention going from #68, it'd be gravy. Or Pico de gallo, I guess.

[dansinker]

CLEARLY YOU MISSED THE "TALK TO ME LIKE I'M STUPID" PART.

CORS headers?

[evz]

Just to clarify, I've got the basic tables put together (more on that here) and with that can pretty much put together whatever endpoints you'd need. Personally, I like this approach just so the main project stays relatively unencumbered and gives people a chance to get their hands dirty using git/github without needing to worry about breaking the build. @santheo I'd be more than happy to provide some endpoints (or you can make them yourself over here) if that's the route we end up choosing.

[evz]

Cross Origin Resource Sharing. When you load stuff in a browser from another site, the default is for the javascript interpreter to reject the request (because of bad guys). But, if the resource that you are requesting provides a certain header on it's response, the javascript interpreter in the client's browser will be OK with it and allow it to load.

[evz]

and by "load stuff" I mean load stuff using javascript.

[knowtheory]

Yeah, so, repositories are just git managed directory structure. Within a repository you can tell git that one of the subdirectories should actually point to a separate git repository.

I'd still want some minimal build scripts internal to the repo for generating index though.

[knowtheory]

So, a practical explanation of CORS:

You know how Quartz is just a fancy Backbone.js app on top of wordpress? So, the thing that stops any random person from being able to build an alternative JS app and pulling the same data from Quartz (but say just swapping out the ads or something) are the Cross Origin rules that browser put on what sorts of things you're allowed to load through Javascript (or more specifically from what domains a website is allowed to load data from).

One way to work around it is JSON-P. The modern way browsers are trying to address it is the CORS system. Basically a website can whitelist other sites who are allowed to load data/resources in HTTP headers. CORS also allows for more types of interaction than just getting data (you'd also be able to put/post/delete data).

[dansinker]

OK, so out walking the dog today I realized that I'm massively overcomplicating this in my head.

Talking with folks on Twitter--and Sandor's very good points about over all UX for non-geeks--it's clear that some level of front-end for the site would be useful.

That said, I'd like to keep the github roots as clean and as exposed as possible.

How do we do this in the easiest, but also most useful way possible?

[evz]

@santheo I have yet to look very deeply at what you've done in this pull request so pardon me if this comes across sounding completely ignorant. Would it be possible to keep this stuff in the gh-pages branch in such a way that all it would take to publish new recipes would be to do a merge from the master? That would have the benefit of making a public facing site work without too much hassle and it would leave the master branch free of Jekyll stuff. @sinker the additional overhead there would be a separate merge to the gh-pages branch after merging a pull request. Which, now that I've typed all of this with my right thumb while standing in the aisle on a moving train, might be a pain.

[dansinker]

I think, other than the double-merge dance, (which really wouldn't be that big of a pain in the ass) the main question is simply that of the YAML frontmatter.

And maybe that's just enough structure to make the structured data people happy without bringing undue burden to submitters?

[evz]

On the other hand, how fault tolerant is Jekyll when it comes to parsing that YAML? If someone doesn't stick it in there or formats it poorly, what does that do to the site when it gets published? Honest questions as I know very little about how that Jekyll works (but have used similar static site generators that fall apart when they get bad YAML).

[dansinker]

My experience is that it just renders the malformed YAML as markup and dumps the layout template.

But that's just something that could be caught in the original PR On Nov 7, 2013 8:44 AM, "Eric van Zanten" notifications@github.com wrote:

On the other hand, how fault tolerant is Jekyll when it comes to parsing that YAML? If someone doesn't stick it in there or formats it poorly, what does that do to the site when it gets published? Honest questions as I know very little about how that Jekyll works (but have used similar static site generators that fall apart when they get bad YAML).

— Reply to this email directly or view it on GitHubhttps://github.com/sinker/tacofancy/pull/69#issuecomment-27970624 .

[santheo]

Honestly I'm not opposed to the double-merge dance. You'd just have to update the ## header syntax on all new files to YAML. But the biggest problem would be links. Right now recipes are being linked to via .md extensions. In the Jekyll site, they have .html extensions. If it were just the index page that linked to recipes, that'd be easy. But there's lots of cross-referencing throughout the repo, and you'd have to keep a watch out for errant links every time you did a merge.

One loss in converting the main branch to Jekyll is that the preview in GH would lose a little punch. The headline goes from looking like a headline, to this:

And fwiw, that 'layout' property isn't doing much right now. It's just setting the active state of the nav. In the future it'll probably be useful, in order to show a sidenav of all recipes in the same section, but we're not doing that yet. So you could trim the YAML down to just the headline if that made things easier.

(I still say someone should build out a Jekyll feature for implicit layouts, where pages are assumed to be organized by directory, and the chosen layout either comes from a) a file in _layouts that's named after the directory in question, or b) a _layout.html file that lives in the same directory as the file. COME ON LAZYGIT.)

[knowtheory]

So this is tough.

The basic challenge imo is still that the Github repo browser is the primary route to understanding the repo structure and how to commit/edit (although i'll note that the "new file" icon is both tiny and unlabeled unless you roll over it). I think that the github browser version needs to stay viable as a way to read through the repo.

That said, there are going to be things that we might want to do that will not be possible through the repo browser. We won't be able to visually style things, and we won't be able to use javascript (something that I would want for a faceted search on ingredients).

The stuff i've written in #68 could pretty easily be rewritten into ruby, so that's not a major concern (and Jekyll obviates some of the need too). The fact that all the links would have to be rewritten (and would not work in the github browser) concerns me a lot more, since both the indexes and recipes link to other .md files w/in the repo, and rewriting them in the repo directly would mean that the github browser wouldn't be usable for browsing.

As an aesthetic thing, i wish we could contain all the config files and such into a single subdirectory so that people who just want to browse and/or contribute, but aren't technical wouldn't bump into them.

[dansinker]

"The fact that all the links would have to be rewritten (and would not work in the github browser) concerns me a lot more" +100

On Sun, Nov 10, 2013 at 5:11 PM, Ted Han notifications@github.com wrote:

So this is tough.

The basic challenge imo is still that the Github repo browser is the primary route to understanding the repo structure and how to commit/edit (although i'll note that the "new file" icon is both tiny and unlabeled unless you roll over it). I think that the github browser version needs to stay viable as a way to read through the repo.

That said, there are going to be things that we might want to do that will not be possible through the repo browser. We won't be able to visually style things, and we won't be able to use javascript (something that I would want for a faceted search on ingredients).

The stuff i've written in #68https://github.com/sinker/tacofancy/pull/68could pretty easily be rewritten into ruby, so that's not a major concern (and Jekyll obviates some of the need too). The fact that all the links would have to be rewritten (and would not work in the github browser) concerns me a lot more, since both the indexes and recipes link to other .md files w/in the repo, and rewriting them in the repo directly would mean that the github browser wouldn't be usable for browsing.

As an aesthetic thing, i wish we could contain all the config files and such into a single subdirectory so that people who just want to browse and/or contribute, but aren't technical wouldn't bump into them.

— Reply to this email directly or view it on GitHubhttps://github.com/sinker/tacofancy/pull/69#issuecomment-28165212 .

[santheo]

Yeah, it's a problem. I wonder how hard it would be to write a plugin that converted all .md links to .html links. I'm not even sure Jekyll allows for stuff like that.

Huh, I just noticed that GitHub Pages runs in --safe mode when running Jekyll, so no plugins allowed. We'd have to render locally and upload that. Hmm.

[dansinker]

Still wonder if there isn't a point where bending jekyll to the breaking point leads to it making more sense to use the API from @evz to build a straight site in addition/compliment to his randomizer. On Nov 10, 2013 10:10 PM, "Sandor Weisz" notifications@github.com wrote:

Yeah, it's a problem. I wonder how hard it would be to write a plugin that converted all .md links to .html links. I'm not even sure Jekyll allows for stuff like that.

Huh, I just noticed that GitHub Pages runs in --safe mode when running Jekyll, so no plugins allowed. We'd have to render locally and upload that. Hmm.

— Reply to this email directly or view it on GitHubhttps://github.com/sinker/tacofancy/pull/69#issuecomment-28173046 .

[KatherineMichel]

Yes, I know that Jekyll is the engine GitHub uses to render gh-pages, but I'm still confused about what makes Jekyll useful in this situation as an optional file structure... because it renders .md and .md is easier to generate than html?

I came across a jQuery plug-in (quicksand http://razorjack.net/quicksand/ https://github.com/razorjack/quicksand/ ) that generates the kind of layout that I would envision for a tacofancy website, although the straightforward functionality of the plug-in might not fit. It's a plug-in that replaces one list with another using a shuffling animation. When you click on a category along the navbar, a group of screenshots of the recipes for the category would appear and you can click on one for close up. At the end of the navbar could be a button such as 'Get Random Taco Recipe' or 'Get Random Veggie Taco' and when you click that button, the relevant random screen shots materialize and can be tweeted through the bot as they have been or manually shared through share buttons. Unfortunately quicksand does not seem to support randomization although more advanced functionality can be built on top of it for instance by using ajax calls.

[dansinker]

closing.