Open lbliii opened 1 year ago
hahnbeelee
commented
1 year ago Can you...
The syntax is <Snippet file="filename.mdx" />. I just want to confirm that you're following this syntax because your error message is implying that your snippet it not being resolved properly.
lbliii
commented
1 year ago Sure thing! Looking at it again just now, i'm realizing that the snippet works on a regular top-level page (which i never tried) versus a nested page, so i'll also add a copy of my mint.json file.
build-dags/branch-operations/copy-files.mdx
---
title: Copy Files
description: Learn how to copy files between branches.
---
Sometimes you need to be able to copy files between branches. This can be especially useful if you want to commit data in an ad-hoc, disorganized manner to a staging branch and then organize it later.
When you run `copy file`, <Snippet file="product-name.mdx" /> only copies references to the files and does not move the actual data for the files around.{
"$schema": "https://mintlify.com/schema.json",
"name": "Documentation Starter Kit",
"logo": {
"dark": "/logo/dark.png",
"light": "/logo/light.png"
},
"favicon": "/favicon.png",
"colors": {
"primary": "#0069ED",
"light": "#4D9CFF",
"dark": "#0050B4"
},
"topbarLinks": [
{
"name": "Documentation",
"url": "https://mintlify.com/docs"
}
],
"topbarCtaButton": {
"name": "Get Started",
"url": "https://github.com/mintlify/starter"
},
"anchors": [
{
"name": "API Reference",
"icon": "rectangle-terminal",
"url": "api-reference"
},
{
"name": "Changelog",
"icon": "list",
"url": "https://mintlify.com"
},
{
"name": "Community",
"icon": "discord",
"url": "https://mintlify.com/community"
}
],
"navigation": [
{
"group": "Home",
"pages": ["introduction", "features"]
},
{
"group": "Build Dags",
"pages": [{
"group": "Branch Operations",
"pages": [
"build-dags/branch-operations/copy-files",
"build-dags/branch-operations/process-specific-commits",
"build-dags/branch-operations/set-branch-triggers",
"build-dags/branch-operations/set-output-branch"
]
}]
},
{
"group": "API Documentation",
"pages": ["api-reference/authentication"]
},
{
"group": "Endpoint Examples",
"pages": [
"api-reference/endpoint/get",
"api-reference/endpoint/create",
"api-reference/endpoint/update",
"api-reference/endpoint/delete"
]
}
],
"footerSocials": {
"twitter": "https://twitter.com/mintlify",
"github": "https://github.com/mintlify",
"linkedin": "https://www.linkedin.com/company/mintsearch"
}
}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.
Some context: The way we render our pages is not through a typical file rendering process (i.e. using webpack/turbopack). The page essentially exists without the knowledge of other pages which essentially makes it difficult for us to support the classic import blank from blank.mdx functionality. If you're familiar with Next.js we're using getStaticProps to render our pages. This is why we engineered snippets as a workaround for people to create reusable content. You're right that snippets are very much catered towards reusable pieces of content and not really single use variables. We'll have to investigate this use-case more. It's possible that we can leverage javascript variables and encourage reusability for smaller snippets/strings.
lbliii
commented
1 year ago 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.
Some context: The way we render our pages is not through a typical file rendering process (i.e. using webpack/turbopack). The page essentially exists without the knowledge of other pages which essentially makes it difficult for us to support the classic
import blank from blank.mdxfunctionality. If you're familiar with Next.js we're using getStaticProps to render our pages. This is why we engineered snippets as a workaround for people to create reusable content. You're right that snippets are very much catered towards reusable pieces of content and not really single use variables. We'll have to investigate this use-case more. It's possible that we can leverage javascript variables and encourage reusability for smaller snippets/strings.
To be fair, I think this use case is somewhat rare -- I've only encountered it recently myself and I've been doing this for like 6 or so years now haha. Basically what I'm starting to do is have a centralized content repo that is used as a submodule fed into my docs site generator repos (so in my current case, two hugo site front end repos and a markdown content repo that replaces the content directory). But I imagine this might be a need for any solution that is both open source and also offers a premium version with potentially different names/branding/download routes.
(if it helps, my specific case is an acquisition situation where the original solution remains open source under its current branding and the acquiring company repackages it under their brand, but the docs are 99% the same)
hahnbeelee
commented
1 year ago Very interesting use case! Thanks for sharing. Really shines light.
hahnbeelee
commented
1 year ago i'm realizing that the snippet works on a regular top-level page (which i never tried) versus a nested page
This is most likely a bug. Thank you for raising it and I will keep you posted on when we get to it.
lbliii
commented
1 year ago i'm realizing that the snippet works on a regular top-level page (which i never tried) versus a nested page
This is most likely a bug. Thank you for raising it and I will keep you posted on when we get to it.
No problem! I like your product and appreciate the setup experience. I've stayed away from JS-based SSGs for a long time due to how complex setup tends to be and they usually don't easily provide nested docs / other features large docs sets need. But y'all already have multi-version version support (which i want to try!) and native API docs (amazing. I don't want to embed redocly anymore ahahaha).
hahnbeelee
commented
1 year ago Thank you for the kind words! Please feel free to post more here and we'd be glad to help! Also feel free to join our discord community where we also offer help. https://mintlify.com/community
hahnbeelee
commented
1 year ago Also if you don't mind me asking what product are you working on? I'm picking up some context clues from what you've sent so far but I'm so curious now ahah. a dag? is it a git competitor? a web3 product? 👀
lbliii
commented
1 year ago It's a product called Pachyderm, a data processing platform that allows developers and data scientists to build scalable, containerized data pipelines. We were recently acquired by HPE, so now I'm managing two sites.
HowieG
commented
5 months ago i'm realizing that the snippet works on a regular top-level page (which i never tried) versus a nested page
This is most likely a bug. Thank you for raising it and I will keep you posted on when we get to it.
Hi @hahnbeelee ! I'm encountering this issue. Created issue #183
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.