Forum Discussion

Headmaster's avatar
Headmaster
Occasional Visitor
5 months ago

API Docs

Hey folks, we have existing API docs (non OAS based) for our legacy REST API in a Jekyll site, built with Markdown. We also have our shiny stoplight-driven docs using OAS's for all our new APIs. Is there a way to migrate the Jekyll docs into Stoplight so they're all together? It seems that Stoplight supports arbitrary Markdown files.

  • Hi Headmaster 

    While Stoplight does support storing markdown files, migrating your Jekyll docs into Stoplight may not be the most efficient approach.

    This is because Stoplight is designed to integrate with your existing version control system (VCS) like Git, allowing you to leverage familiar workflows such as pull requests and version control history.

    In contrast, Jekyll builds static HTML sites, which aren't ideal for version control. Furthermore, Stoplight separates content (markdown) from presentation (themes), so migrating Jekyll docs would likely import the content, but the styling and layout wouldn't translate directly. This means that a direct migration might not be the most effective way to transition your documentation to Stoplight.

    Hope this helps - Happy to help further!!
    Thank you very much and have a great one!
    Warm regards

  • Humashankar's avatar
    Humashankar
    Champion Level 2

    Hi Headmaster 

    While Stoplight does support storing markdown files, migrating your Jekyll docs into Stoplight may not be the most efficient approach.

    This is because Stoplight is designed to integrate with your existing version control system (VCS) like Git, allowing you to leverage familiar workflows such as pull requests and version control history.

    In contrast, Jekyll builds static HTML sites, which aren't ideal for version control. Furthermore, Stoplight separates content (markdown) from presentation (themes), so migrating Jekyll docs would likely import the content, but the styling and layout wouldn't translate directly. This means that a direct migration might not be the most effective way to transition your documentation to Stoplight.

    Hope this helps - Happy to help further!!
    Thank you very much and have a great one!
    Warm regards