loading...

re: Slate, Swagger, and Silos - A Documentation Rebuild Story VIEW POST

TOP OF THREAD FULL DISCUSSION
re: Hi we are evaluating Slate for API documentation. We also have swagger yaml spec. I have seen some solutions for swagger yaml to slate markdown con...
 

There's only one or two options that come to mind that might work, but I haven't personally tried to tackle this problem.

If you look at how Slate handles the TOC, there's a file in the ~/lib subdirectory that does a pre-rendering of the content. So the markdown has already been covered to html and this modifies it. You might be able to get away with something similar if the swagger converted file and the baseline doc had something you could consistently match up against, like a header. The main issue with that is you may have a superfluous site path unless you buried one of the markdown files outside of the normal directory.

Alternatively, you could modify deploy.sh to use regex to merge the two files so they maintain separation in your code base until they are ready to go live. That way you have a single URL path and the documentation would use the normal middleman rendering path. Any changes to ~/deploy.sh would need to come before the run_build() function.

All of that is speculation on what might work. I haven't touched Slate in sometime, but hopefully it can get you in the right direction.

Code of Conduct Report abuse