Forum Discussion

Headmaster's avatar
Headmaster
Occasional Visitor
7 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 t...
  • Humashankar's avatar
    Humashankar
    6 months ago

    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 3
6 months ago

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