{"action":"created","issue":{"url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/89","labels_url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/89/labels{/name}","comments_url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/89/comments","events_url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/89/events","html_url":"https://github.com/kevinrenskers/raml2html/issues/89","id":48827799,"number":89,"title":"RFC: new default templates","user":{"login":"kevinrenskers","id":229384,"avatar_url":"https://avatars.githubusercontent.com/u/229384?v=3","gravatar_id":"","url":"https://api.github.com/users/kevinrenskers","html_url":"https://github.com/kevinrenskers","followers_url":"https://api.github.com/users/kevinrenskers/followers","following_url":"https://api.github.com/users/kevinrenskers/following{/other_user}","gists_url":"https://api.github.com/users/kevinrenskers/gists{/gist_id}","starred_url":"https://api.github.com/users/kevinrenskers/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kevinrenskers/subscriptions","organizations_url":"https://api.github.com/users/kevinrenskers/orgs","repos_url":"https://api.github.com/users/kevinrenskers/repos","events_url":"https://api.github.com/users/kevinrenskers/events{/privacy}","received_events_url":"https://api.github.com/users/kevinrenskers/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/kevinrenskers/raml2html/labels/question","name":"question","color":"cc317c"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":23,"created_at":"2014-11-14T19:08:25Z","updated_at":"2015-05-25T00:45:33Z","closed_at":null,"body":"If you have any ideas about how the default templates should look, please add a comment to this ticket. I'm trying to come up with a list of wishes and requirements that could be given to a designer.\r\n\r\nMy wish list:\r\n\r\n- Glance-able overview of all API endpoints and their methods\r\n- Somehow split the top level documentation from the endpoints\r\n- It should be easy to show/hide the individual methods\r\n- Searchable\r\n- Direct links to specific endpoints, methods\r\n- Single page html output\r\n- Hopefully not rely on bootstrap/jQuery. No external deps = no http/https problems.\r\n- Not written in Handlebars"},"comment":{"url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/comments/105082290","html_url":"https://github.com/kevinrenskers/raml2html/issues/89#issuecomment-105082290","issue_url":"https://api.github.com/repos/kevinrenskers/raml2html/issues/89","id":105082290,"user":{"login":"robertlevy","id":1929538,"avatar_url":"https://avatars.githubusercontent.com/u/1929538?v=3","gravatar_id":"","url":"https://api.github.com/users/robertlevy","html_url":"https://github.com/robertlevy","followers_url":"https://api.github.com/users/robertlevy/followers","following_url":"https://api.github.com/users/robertlevy/following{/other_user}","gists_url":"https://api.github.com/users/robertlevy/gists{/gist_id}","starred_url":"https://api.github.com/users/robertlevy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/robertlevy/subscriptions","organizations_url":"https://api.github.com/users/robertlevy/orgs","repos_url":"https://api.github.com/users/robertlevy/repos","events_url":"https://api.github.com/users/robertlevy/events{/privacy}","received_events_url":"https://api.github.com/users/robertlevy/received_events","type":"User","site_admin":false},"created_at":"2015-05-25T00:45:33Z","updated_at":"2015-05-25T00:45:33Z","body":"I vote pre-render.  If looking at API docs ends up having instructions more complicated than just \"hey open this file\", that would probably be a upgrade blocker for us.   Our main usage of raml2html is running it from our CI scripts and then accessing the static output as an artifact.   \r\n\r\nAs for search, you could emit the json object into the body of the page and then implement the actual search functionality very similarly to how you'd do it if you had a SPA calling a nodejs service to do the work.  I'd be willing to work on a PR for this when you think the timing is right to tackle it.\r\n\r\n> On May 24, 2015, at 7:41 PM, Kevin Renskers <notifications@github.com> wrote:\r\n> \r\n> My biggest question is actually how to implement the new design: pre-render the entire html server-side like I do now? Or go client-side Single Page Application (SPA)?\r\n> \r\n> Pre-render (current implementation)\r\n> \r\n> Output is a single HTML file: server-side Nunjucks templates render the RAML file(s) to a single HTML file\r\n> Easy to integrate with other systems\r\n> Easy to hack the output\r\n> A client-side search feature is pretty damn hard to implement\r\n> The output is pretty big since all the modals etc are written up front, but is mostly a problem with big RAML files (also would be less of a problem when the modals are gone)\r\n> SPA\r\n> \r\n> The idea is that raml2html basically outputs a JSON file that is then rendered client-side using a front-end framework like Angular or React (no more template rendering on the server)\r\n> The output would thus be multiple files, unless all the JS, CSS and the RAML JSON can inlined (requiring a build step? or server-side templates that fill in the client side app like {{RAML_JSON}}?)\r\n> The output would be (somewhat) smaller, especially for large RAML files\r\n> Client side search would be pretty easy to do\r\n> A bit harder to hack the templates, on the other hand it's just a matter of learning Angular or React vs Nunjucks\r\n> Probably harder to integrate into other systems\r\n> I think that the SPA approach makes more sense, especially when you consider the need for a good search feature. My big worry though is how this would still be \"raml to html\", it's more like \"raml to json\" with a SPA wrapped around that. And that SPA part never changes per different RAML doc. It's almost like the new template would be a brand new GitHub repo - simply a web app that renders a raml.json file. And then you'd have a new \"raml2json\" project (a tiny tiny wrapper around the existing raml2obj) and.. raml2html would be dead/replaced.\r\n> \r\n> Also I just made the switch from Handlebars to Nunjucks templates, not sure how everyone would like yet another big change if suddenly it would be Angular or React or something like that.\r\n> \r\n> So yeah, I'm struggling with this a bit.. I keep going back and forth between the 2 options. Like, \"what if we drop the search feature, and keep the Nunjucks approach?\", but then I think \"no that's just silly\", but then I think about how huge of a change the SPA way is, etc etc :)\r\n> \r\n> Input welcome!\r\n> \r\n> —\r\n> Reply to this email directly or view it on GitHub.\r\n> \r\n"}}