[Question] Are we allowed to use third-party documentation platforms like Mintlify?

[vamsimanohar]

Summary

We are exploring options to improve the documentation for observability.opensearch.org. One option is Mintlify, which has an OSS Program offering their Pro plan for free to open source projects. From initial communications, they are willing to accept OpenSearch into the program. Before proceeding, we need to understand: are we allowed to use third-party hosted documentation platforms for OpenSearch projects?

How Mintlify Works (Important Context)

Mintlify is not a build tool or static site generator. It is a hosted commercial platform that owns the deployment pipeline:

1. You write Markdown/MDX docs in a GitHub repo with a mint.json config
2. You connect the repo to your Mintlify account (via their dashboard, not GitHub CI)
3. Mintlify pulls changes from the repo, builds, and hosts the site on their infrastructure
4. Your custom domain (e.g., observability.opensearch.org) points via DNS CNAME to Mintlify's servers (see Mintlify Custom Domain docs)

GitHub repo (docs source) → Mintlify account pulls & builds → Hosted on Mintlify servers
                                                                        ↓
                                                        observability.opensearch.org
                                                        (DNS CNAME → Mintlify infrastructure)

Key point: There is no GitHub Actions / CI involved in deployment. The build and hosting are entirely controlled by Mintlify through their account/dashboard. This means:

• Mintlify controls the hosting — if access is revoked or terms change, the site goes down
• The Mintlify account owner controls deployment, not the GitHub repo
• This is a dependency on a third-party commercial service for project infrastructure

Current Status

• From initial communications, Mintlify is willing to accept OpenSearch into their OSS Program (free Pro plan).
• No account has been created and no action has been taken — waiting for guidance before proceeding.

Questions

1. Are we allowed to use hosted commercial platforms (like Mintlify) for OpenSearch project documentation, even if offered free under an OSS program?
2. What is the approval process if we want to use such a service? Does LF need to review terms, own the account, etc.?
3. Should we stick to open source self-hosted alternatives? Options that deploy via GitHub CI to GitHub Pages (no third-party hosting dependency):
   • Read the Docs (LF recommended)
   • Docusaurus
   • MkDocs Material
4. Is there precedent? Other LF projects use Mintlify (e.g., Agent Communication Protocol). How did they get approval?

Concerns

• No GitHub CI control: Deployment is through Mintlify's platform, not our CI/CD. We lose control over the build and deploy pipeline.
• Hosting dependency: If Mintlify changes terms or revokes access, the site goes down (similar to past issues with HuggingFace OSS program).
• Account ownership: If approved, the account must be LF-controlled, not individual.
• Portability: The docs source (Markdown) is portable, but the mint.json config and Mintlify-specific components are not.

References

• Mintlify OSS Program: https://www.mintlify.com/oss-program
• Mintlify Docs: https://www.mintlify.com/docs
• Mintlify Custom Domain Setup: https://mintlify.com/docs/settings/custom-domain
• Target site: https://observability.opensearch.org/
• LF project using Mintlify: https://agentcommunicationprotocol.dev/

/cc @peternied

[peternied]

@opensearch-project/opensearch-migrations have y'all looked into Mintlify for the migration project and might have some thoughts about deploying it here?

[peterzhuamazon]

Have mentioned this in the syncup with LF folks and pending their answers, but I am in question whether it is really needed.
I am not seeing what exact benefits we have in using this service vs. github pages, which is completely in our control and deployment cycles.

LF generally recommended github pages and readthedocs for your website and you already have a website deployed at observability.opensearch.org. Thanks.

https://jira.linuxfoundation.org/plugins/servlet/desk/portal/2/IT-29467