DEV Community

Discussion on: Slate, Swagger, and Silos - A Documentation Rebuild Story

pandit_pratibha profile image

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 conversion, but that seems like having all documentarion in yaml and use slate for rendering. What I want ideally is have swagger yaml as baseline API doc that comes with dev release and be able to build more detailed documentation on top of it directly in slate. Key here is to be able to preserve both slate doc & baseline doc from swagger every release without having to redo slate documentation. Have you come across this workflow or have any tips? Thanks

preciselyalyss profile image
Alyss 💜 Author • Edited on

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 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 ~/ 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.