Skip to content

Conversation

@ethanpalm
Copy link
Collaborator

@ethanpalm ethanpalm commented Jun 17, 2025

Documentation changes

https://mintlify.com/docs/settings jumps into reference information without explaining what a docs.json file does and why you need one.

This PR builds out the conceptual information on docs.json and why it's pivotal to your docs site.

Changes include

  • Add intro content on what the file does
  • Add setting up section that has the minimum required parameters to function
  • Rename to "Global settings" to avoid any confusion with user or account settings
  • Add examples of a typical docs.json for a SaaS company, with API playground, and with multiple languages
  • Revise all reference content for clarity and completeness
  • Include a link to settings as a call to action at the end of the quickstart

Closes https://linear.app/mintlify/issue/DOC-57/add-conceptual-information-to-settings
Closes https://linear.app/mintlify/issue/DOC-54/docsjson-page-in-search-results


For Reviewers

When reviewing documentation PRs, please consider:

✅ Technical accuracy

  • Code examples work as written
  • Commands and configurations are correct
  • Links resolve to the right destinations
  • Prerequisites and requirements are accurate

✅ Clarity and completeness

  • Instructions are clear and easy to follow
  • Steps are in logical order
  • Nothing important is missing
  • Examples help illustrate the concepts

✅ User experience

  • A new user could follow these docs successfully
  • Common gotchas or edge cases are addressed
  • Error messages or troubleshooting guidance is helpful

@ethanpalm ethanpalm merged commit c02273c into main Jun 17, 2025
4 checks passed
@ethanpalm ethanpalm deleted the docsjson-conceptual-info branch June 17, 2025 23:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants