Why not create a new template for raml2html?

[kevinrenskers]

Hey! I like the direction you're taking with this template. Since raml2html could definitely use a new default template, why not join efforts and add this template to raml2html? Instead of making a new library that depends on raml2md to render raml -> md -> html in slate style :)

[wdullaer]

I actually considered it at some point. The reason I didn't do it in the end was because there was no easy way to copy over static assets (I needed to inline all the css in the template IIRC, and there was no way to include a logo). Combined with some time pressure, I ended up running with the current solution.

If you like it though, I'm more than happy to help integrate it in raml2html (which I've been happy user of for quite some time)

[kevinrenskers]

Yea, the goal of raml2html is to output a single html file, so inlining css is a must, and logos would have to be done as a url rather then a local asset I think. If we'd output multiple files the whole command line API would need to change.

Inline css is a bit annoying but not a huge problem, and going with a logo url (at least for now) would already better then having no logo at all in raml2html :)

It'd be pretty awesome if at some point when you have time, you could fork raml2html's develop branch and add your template to it. It would probably be best to stick with Nunjucks, not sure if that would be a problem?

[wdullaer]

I'll give it a shot. I can't guarantee any timeline though. It's been rather hectic lately. Would this be in addition to the current template or as a replacement?

I can imagine people liking the compact format as well. And there are also still some things that annoy me about the current slate like layout.

[kevinrenskers]

Just build it as a replacement in your branch/fork. I think it would indeed become the new default one, and then we can think about keeping the old one around later :)

[kevinrenskers]

And yeah no hurry at all of course!

[sichvoge]

Thanks Kevin. Agree, it would be good to have only one since mistakes on one could be avoided to be repetitive on the other. I already would have a list for this repo on some missing renderings, but if you ( @wdullaer ) really think about moving the template to raml2html, those things might not really be a problem anymore. :)

Still let me know if you want me to raise it.

Regarding the new template, I'd say we could store the old in a common-templates folder inside raml2html and let people either use the default template or choose one from that folder.

What do you think?

[sichvoge]

BTW, my test base always will be https://github.com/raml2html/raml2html/blob/master/examples/world-music-api.raml :)

[wdullaer]

Moving this template into raml2html won't magically make additional features available. So if certain components are not rendered (and I know stuff is missing, I essentially scratched until my own itch went away), please raise it, maybe with some mockups of how you would things to be visualised.

Moving this to raml2html will require me rewriting the nunjucks templates to output straight html rather than markdown (tedious but not really hard work) and inlining all the css and javascript.

Some features which are harder to port are the fact that you can tweak the colour scheme and pass in a logo. Those things are not supported by raml2html right now, unless I add in a similar build pipeline. Having all of the javascript and css inline will also make the theme harder to maintain in the future (this could be worked around by keeping everything as separate files in the source and essentially building the final template when publishing to npm)

[kevinrenskers]

raml2html 5.0.0 was just released with support for themes, and themes can supply their own rendering logic, so they can use any templating language they want. In fact, raml2md is now rewritten as a theme for raml2html. See https://github.com/raml2html/raml2html/issues/322 for more info.

It would be great to have this available as a theme! :)

[sichvoge]

Thats awesome @kevinrenskers.

[wdullaer]

@kevinrenskers will do!

[wdullaer]

I'm nearly done porting this to a raml2html theme. I still need to do some code cleanup, tests and get the language tabs back to work. I expect to put a first version on github next weekend.

@kevinrenskers can I add additional configuration items for this theme that can be specified through raml2html? If so, can you give an example? I'll probably also make a small PR for raml2html itself, to improve some error handling when a theme is faulty.

After this, the theme should have feature parity with this repo. However not all raml features are supported at this point. I can really use some help there (mockups etc).

[kevinrenskers]

I'll make sure that any and all cli parameters are passed onto the theme somehow. Then you can just support whatever you want.

[wis3guy]

i would be quite keen to test this out as soon as it becomes available.

[kevinrenskers]

I've been struggling to support arbitrary CLI options due to a problem with Commander, see https://github.com/tj/commander.js/issues/609. Hopefully this can be resolved soon. I'll let you know when I more / when it's done.

[wdullaer]

I should have a working version up on github by Saturday the latest

@kevinrenskers I took a look and see what you mean. I have a potential workaround, but it involves parsing out the theme option manually (once you know the theme, you can pass the commander instance to the theme to attach its own options) Would it be interesting to create a slack / irc / gitter for raml2html so we can discuss some of these things in more realtime?

[kevinrenskers]

I think I'll replace Commander with https://github.com/yargs/yargs

[kevinrenskers]

At the moment themes can only return a config object, they don't get anything passed to them. I'll need to change it so that themes can/need to supply a function that gets the program arguments as a param, and returns the config object.

[kevinrenskers]

Ok, raml2html PR is up! https://github.com/raml2html/raml2html/pull/331

[kevinrenskers]

Oh yeah and about creating a slack / irc / gitter channel.. I don't think I'd ever be online in it to be honest, since I don't want a 24/7 stream of support questions and stuff :) I try to be as hands-off with raml2html as possible, let other people jump in with PR's.

If the community decides to start something like this, they have my blessing of course. But at the moment there don't seem to be a lot of contributors, so..

[kevinrenskers]

raml2html@5.1.0 has been published

[wdullaer]

https://github.com/wdullaer/raml2html-slate-theme

Works with all new fancy raml2html features

If someone can confirm that this is fine for them I'll publish it on npm tomorrow