Document support for .md
#1900
Merged
Document support for .md
#1900
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
k-finken
reviewed
Nov 26, 2025
Contributor
k-finken
left a comment
k-finken
left a comment
There was a problem hiding this comment.
I think this looks good but I don't think we should replace MDX with Markdown in most of the spots since Markdown isn't a superset of those two. I think we should keep MDX in most of the spots and just label a few specifics with we support .md as well.
CC @hahnbeelee
| 3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. | ||
|
|
||
| <Tip> | ||
| If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components. |
k-finken
approved these changes
Nov 26, 2025
Contributor
k-finken
left a comment
k-finken
left a comment
There was a problem hiding this comment.
Left 1 comment but otherwise looks great 🚢
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Documentation changes
This PR replaces most uses of
MDXwithMarkdownsince we support.mdand.mdxfile types.Biggest change is in
pages.mdxwhere we explain that a page is a Markdown file and it can be either type, but MDX can use JSX.I left all the API-related content as MDX only since no one currently has
.mdendpoint pages and we don't want people creating them. So users would only really be going from MDX to openAPI or setting up MDX endpoint pages.Closes https://linear.app/mintlify/issue/DOC-210/update-docs-to-mention-standard-md-file-support
For Reviewers
When reviewing documentation PRs, please consider:
✅ Technical accuracy
✅ Clarity and completeness
✅ User experience
Note
Clarifies Markdown page support (.md and .mdx) and standardizes MDX terminology across docs, with key updates to Pages, Editor, and Migration guides.
organize/pages.mdxto define pages as Markdown; support.mdand.mdx; recommend MDX for full functionality.editor.mdx.migration.mdxto use Markdown pages; add tip to convert.mdto.mdx; adjust asset reference wording.api-playground/mdx-setup.mdxandapi-playground/overview.mdxregarding custom endpoint pages.customize/react-components.mdxandcustomize/custom-scripts.mdx.usercontent access and examples indeploy/personalization-setup.mdx.api.mdxconfiguration description inorganize/settings.mdx.organize/navigation.mdx.Written by Cursor Bugbot for commit 7211090. This will update automatically on new commits. Configure here.