mintlify/docs

🪴 Mintlify's documentation

docs's Issues

Issue on docs: Local development instructions are missing steps

Path: /development

The docs say just run npm i -g mintlify and then run mintlify dev. That did not work for me.

After doing the NPM install I ran mintlify dev and it asked me to install Yarn. Not really what I wanted, but there was no way around it, so I did.
I then ran mintlify dev again, this time I got:

? yarn must be globally installed. Install yarn? Yes

added 1 package in 830ms
✖ Dependencies were not installed correctly, run
  
      mintlify install
      

So I ran that. It installed another boatload of packages.

Then finally did mintlify dev actually succeed.

I think the docs should mention that yarn is a required dependency (if that is necessary, I would prefer it was not) and the additional command you need to run to install dependencies first.

Get started button takes you to 404 page

https://mintlify.com/docs/introduction

Error 500 on internal pages when hosted on Mintlify

Local mintlify dev renders pages fine.

Online, I am getting a 500 server error on the subpages: https://uitrial.mintlify.app/api-reference/example-usage. The issue persists for 24 hours now, and no reads or replies from Mintlify support team?

What's going on?

Missing the Workflow?

Knowing nothing about Mintlify except that the beautiful sites it produces, I jumped in. I was hoping on the QuickStart page to see something about "mintlify generate" or some idea of how one creates the documents apart from just hand coding MDX. As far as I can tell from the docs site, it's a sort of static site generator targetting documentation, but given there is a Mintlify Writer generating code comments and other references, it seems like there is some connection between source code and the generated sites but I can't tell how. Anyhoo, still a beautiful site.

`hideFeedbackButtons` seems not working

According to the documentation on Global Settings, there is an option called hideFeedbackButtons that allows the hiding of suggestion buttons at the top of pages. However, setting it to true does not seem to disable those buttons.

Furthermore, this option is missing in schema.json. Perhaps this flag has not yet been published to production?

Provide mint.json configuration option to customise suggest edit branch

Problem

Novu docs (https://github.com/novuhq/docs) use a Gitflow branching model with 2 primary branches. All changes first make their way into a trunk branch, and the trunk is periodically merged into the Mintlify deploy branch.

By default, the Mintlify "Suggest edit" feature opens the Github edit page on the deploy branch for the docs, which for repositories using a Gitflow branching model, is the incorrect branch for edits to be made on. This results in poor contributor DX and can result in edits erroneously being pushed against the deploy branch if branch merge checks are not enforced.

Proposed Feature

The mint.json should provide an optional feedback.suggestEditBranch configuration option to enable customisation of the "Suggest edits" branch. If the optional configuration option is not provided, the auto-generated repo.github.deployBranch option should be used.

Proposed Solution

The useUserFeedBack hook can be updated with the following code to support this backward compatible change:

const { suggestEditBranch } = mintConfig?.feedback;
let editBranch;
if (suggestEditBranch) {
    editBranch = suggestEditBranch;
} else {
    editBranch = deployBranch;
}
...
dispatch({
    type: FeedBackActionEnum.SET_CREATE_SUGGEST_HREF,
    payload: `https://github.com/${owner}/${repo}/edit/${editBranch}/${removeFirstSlash(urlPath)}${removeFirstSlash(`${path}.mdx`)}`
});

Who will benefit from this feature?

• Mintlify customers using a Gitflow branching model to manage changes
• Mintlify customers preferring suggested edits to be made against a custom branch
• Contributors to public documentation using the Mintlify platform

I am willing to contribute to the https://github.com/mintlify/docs to support this feature.

Ability to provide custom React components?

Hi!

Coming from Nextra, I have some custom React components (ex: "Retries simulator", "Get your API token") that I need now to either drop or integrate with an iframe.

Is there any plan to support custom React components that could rely on styled-components or similar?

Thanks!

About the relative path of the images

My images resources are in the assets/ directory under each directory. For example:

Dic1
├── assets/
├── file-1-1.mdx
├── file-1-2.mdx
Dic2
├── assets/
├── file-2-1.mdx
├── file-2-2.mdx
...

I don't want to put all the image resources in the images/ directory of my root directory, how to set the global configuration so that the Markdown file reads resources based on a relative path? If not, are there any plans for future updates?

Thank you very much！

Snippets only works on top-level

Hi,

I have /snippets/supported-models.mdx
which renders in /quickstart.mdx
but not /v1/concepts/sdk-reference.mdx

I'm doing the same in both
`import SupportedModels from '/snippets/supported-models.mdx'

`

I would try to change it to ../../snippets/supported-models.mdx but I get

Invalid import path ../../snippets/supported-models.mdx in v1/concepts/sdk-reference.mdx. Import source must start with "/snippets/"

and I read #22 saying that these imports aren't path-based they're just hacky references.

Please let me know if I should be doing anything differently!

Future request: tab-able API accordion items

Please make these tab-able and open-able by keyboard for accessibility reasons, thank you.

Expand Object Properties doesn't work with paramfield

Path: /components/api/expandable

Bug: Doc linking to the wrong place?

on this page https://mintlify.com/docs/api-playground/components/api/param. Clicking the API Playground links to the docs home page. I think its linking to a different page, can you please confirm that.

Feature Request: Add producthunt to footer socials

Can producthunt please be added as a footerSocial in mint.json?

How to add a multilingual document?

How to add a multilingual document?

like this:

eg:
English: https://mintlify.com/en/docs/quickstart
Chinese: https://mintlify.com/zh/docs/quickstart

Issue on docs: wrong external link

Path: /settings/global

wrong external link: https://fontawesome.com/search?s=brands%2Cduotone

When I click the Font Awesome link in the picture below, the page behaves strangely.

Suggest Edits button not showing

Sweet feature! Wonder if I'm doing anything wrong

broken-links CLI bugs

https://www.loom.com/share/6b1c711455514bcfb08d9f7cc894c857?sid=81952b0c-7317-4487-9dba-129227ad2c15

Hi, the broken-links command isn't working exactly as desired. I put broken-links as part of my CI/CD which was failing bc of this behavior so I had to take it out. Thanks!

Feature Request: Configurable primary text color

Would be awesome to be able to set the primary text color!

Snippets error

Hello! I'm testing out your docs solution (pretty cool!) but running into an issue with Snippets. The docs say there's no importing or special pathing required, but the error I'm getting implies otherwise. I've tried to make my own snippet and also just copy/paste the snippet in the docs.

sidenote: are snippets the best way for me to handle global doc variables? For example, I tend to support documentation that has an open source version and an enterprise version that sometimes has another product name, so I like to just pass something like {{% productName %}} into my Hugo docs.

Server Error
Error: Expected component `Snippet` to be defined: you likely forgot to import, pass, or provide it.
It’s referenced in your code at `4:27-4:60`

This error happened while generating the page. Any console logs will be displayed in the terminal window.
Call Stack
_missingMdxReference
eval at <anonymous> (webpack-internal:///./node_modules/next-mdx-remote/dist/index.js), <anonymous> (232:9)
_createMdxContent
eval at <anonymous> (webpack-internal:///./node_modules/next-mdx-remote/dist/index.js), <anonymous> (36:17)
renderWithHooks
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7766:16)
renderIndeterminateComponent
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7840:15)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8075:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderContextProvider
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8039:3)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8153:11)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderIndeterminateComponent
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7894:7)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8075:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderChildrenArray
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8351:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8280:7)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderHostElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7750:3)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8081:5)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderIndeterminateComponent
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7894:7)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8075:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderChildrenArray
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8351:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8280:7)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderHostElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7750:3)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8081:5)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderChildrenArray
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8351:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8280:7)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderNode
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8399:12)
renderHostElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7750:3)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8081:5)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)
renderIndeterminateComponent
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (7894:7)
renderElement
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8075:7)
renderNodeDestructiveImpl
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8243:11)
renderNodeDestructive
file:///Users/lanel/.mintlify/mint/client/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.development.js (8215:14)

Add support for links in Steps component titles

The Steps component doesn't seem to support links yet.

Adding this support would increase the component's flexibility + be greatly appreciated!

How to customize SEO default values in `mint.json`?

The SEO documentation page mentions that we can customize the SEO default value globally (ex: og:image) in the mint.json file; however, I don't find such parameters in the mint.json documentation page.

Add support for Umami analytics

Hi, I'm the founder of Umami Analytics. I saw that you had an analytics integration section, https://mintlify.com/docs/integrations/analytics/overview, and would love to get included.

The implementation would look like this:

"analytics": {
  "umami": {
    "websiteId": "required",
    "hostUrl": "optional"
  }
}

The parameters would generate the following script:

<script defer src="{hostUrl}" data-website-id="{websiteId}"></script>

if hostUrl is not specified, it should default to https://cloud.umami.is/script.js.

Great product btw! We were looking for a solution for our own docs and found Mintlify.