From a5cc0d75bd9fcf9d600f5da25fb2e641a06be2ba Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:10:32 +0000 Subject: [PATCH 1/2] docs: add help-center article on offline export Node.js requirement --- docs.json | 3 ++- help-center/offline-export-requires-node.mdx | 25 ++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 help-center/offline-export-requires-node.mdx diff --git a/docs.json b/docs.json index a34f823ac..ca26134af 100644 --- a/docs.json +++ b/docs.json @@ -492,7 +492,8 @@ "help-center/register-external-mcp-server-in-discovery", "help-center/visitor-count-dropped-after-crawler-filtering", "help-center/migrate-from-confluence", - "help-center/migrate-docs-from-a-zip-export" + "help-center/migrate-docs-from-a-zip-export", + "help-center/offline-export-requires-node" ] } ] diff --git a/help-center/offline-export-requires-node.mdx b/help-center/offline-export-requires-node.mdx new file mode 100644 index 000000000..3883094d8 --- /dev/null +++ b/help-center/offline-export-requires-node.mdx @@ -0,0 +1,25 @@ +--- +title: "Serve an offline export archive without Node.js" +description: "Why the mint export archive ships a Node.js server, whether you can host it on a plain static file host, and what to do if Node.js is not available." +keywords: ["offline export", "static hosting", "node.js", "serve.js", "mint export", "air-gapped", "no node runtime"] +--- + +Every archive produced by `mint export` ships with `serve.js`, a zero-dependency Node.js HTTP server that recipients run to view the docs locally. The `Start Docs.command` (macOS) and `Start Docs.bat` (Windows) launchers just invoke `node serve.js`, so recipients need [Node.js](https://nodejs.org) v20.17.0+ installed regardless of whether the site uses the AI assistant, the API playground, or any other dynamic feature. For the full export workflow, see [Offline export](/deploy/export). + +## Why the archive uses a local server + +The archive is designed for offline viewing on a recipient's own machine, not for hosting on a static web server. `serve.js` handles the URL rewriting and MIME-type behavior that Mintlify pages rely on when opened at `http://localhost:3000`. Opening the pre-rendered `.html` files directly from the filesystem (`file://`) is not supported and produces broken navigation and asset loading. + +## Serving the export on a static host + +Mintlify does not publish or support a "pure static" mode for `mint export`. The archive is not shaped for upload to an S3 bucket, GitHub Pages, or a plain Nginx site. + +If you need Mintlify content on a static host without a Node.js runtime, use one of these approaches instead: + +- **Publish to Mintlify.** Push the same repository to Mintlify and serve it from your `.mintlify.site` subdomain or a [custom domain](/customize/custom-domain). This is the supported way to serve Mintlify docs over HTTP. +- **Self-host.** Enterprise plans include a [self-hosted](https://mintlify.com/pricing?ref=self-hosted) option that runs your docs inside your own infrastructure. Contact support to discuss requirements. +- **Request the feature.** If you need `mint export` to produce a static-hostable bundle, open a request in [GitHub Discussions](https://github.com/orgs/mintlify/discussions/categories/feature-requests) so the team can weigh the demand. + +## If the recipient cannot install Node.js + +Node.js is a hard requirement for viewing a `mint export` archive. If the intended recipient cannot install it (for example, a locked-down air-gapped workstation), share a portable Node.js build alongside the archive, or provide the docs through one of the alternatives above. From 73001bdd20ca9492d0f3fa0811dca710f3507eeb Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:13:50 +0000 Subject: [PATCH 2/2] docs: translate offline export Node.js help-center article (es, fr, zh) --- es.json | 3 +- .../offline-export-requires-node.mdx | 31 +++++++++++++++++++ fr.json | 3 +- .../offline-export-requires-node.mdx | 31 +++++++++++++++++++ zh.json | 3 +- .../offline-export-requires-node.mdx | 31 +++++++++++++++++++ 6 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 es/help-center/offline-export-requires-node.mdx create mode 100644 fr/help-center/offline-export-requires-node.mdx create mode 100644 zh/help-center/offline-export-requires-node.mdx diff --git a/es.json b/es.json index ffa5006de..3992bc27c 100644 --- a/es.json +++ b/es.json @@ -470,7 +470,8 @@ "es/help-center/register-external-mcp-server-in-discovery", "es/help-center/visitor-count-dropped-after-crawler-filtering", "es/help-center/migrate-from-confluence", - "es/help-center/migrate-docs-from-a-zip-export" + "es/help-center/migrate-docs-from-a-zip-export", + "es/help-center/offline-export-requires-node" ] } ] diff --git a/es/help-center/offline-export-requires-node.mdx b/es/help-center/offline-export-requires-node.mdx new file mode 100644 index 000000000..f63bd79c8 --- /dev/null +++ b/es/help-center/offline-export-requires-node.mdx @@ -0,0 +1,31 @@ +--- +title: "Servir un archivo de exportación offline sin Node.js" +description: "Por qué el archivo de mint export incluye un servidor Node.js, si puedes alojarlo en un host de archivos estáticos y qué hacer si Node.js no está disponible." +keywords: ["exportación offline", "hosting estático", "node.js", "serve.js", "mint export", "entorno aislado", "sin runtime de node"] +--- + +Cada archivo producido por `mint export` incluye `serve.js`, un servidor HTTP de Node.js sin dependencias que los destinatarios ejecutan para ver la documentación de forma local. Los lanzadores `Start Docs.command` (macOS) y `Start Docs.bat` (Windows) simplemente invocan `node serve.js`, así que los destinatarios necesitan tener [Node.js](https://nodejs.org) v20.17.0+ instalado, independientemente de si el sitio usa el asistente de IA, el playground de API o cualquier otra función dinámica. Para el flujo completo de exportación, consulta [Exportación sin conexión](/es/deploy/export). + +
+## Por qué el archivo usa un servidor local +
+ +El archivo está diseñado para verse sin conexión en la máquina del destinatario, no para alojarse en un servidor web estático. `serve.js` gestiona la reescritura de URL y el comportamiento de los tipos MIME en los que se basan las páginas de Mintlify cuando se abren en `http://localhost:3000`. Abrir los archivos `.html` prerenderizados directamente desde el sistema de archivos (`file://`) no está soportado y produce navegación rota y errores al cargar recursos. + +
+## Servir la exportación en un host estático +
+ +Mintlify no publica ni admite un modo "puramente estático" para `mint export`. El archivo no está preparado para subirse a un bucket de S3, GitHub Pages ni a un sitio simple de Nginx. + +Si necesitas contenido de Mintlify en un host estático sin un runtime de Node.js, usa alguno de estos enfoques en su lugar: + +- **Publica en Mintlify.** Sube el mismo repositorio a Mintlify y sírvelo desde tu subdominio `.mintlify.site` o desde un [dominio personalizado](/es/customize/custom-domain). Esta es la forma soportada de servir documentación de Mintlify por HTTP. +- **Autoalojamiento.** Los planes Enterprise incluyen una opción [autoalojada](https://mintlify.com/pricing?ref=self-hosted) que ejecuta tu documentación dentro de tu propia infraestructura. Contacta a soporte para hablar de los requisitos. +- **Solicita la función.** Si necesitas que `mint export` produzca un paquete alojable de forma estática, abre una solicitud en [GitHub Discussions](https://github.com/orgs/mintlify/discussions/categories/feature-requests) para que el equipo pueda evaluar la demanda. + +
+## Si el destinatario no puede instalar Node.js +
+ +Node.js es un requisito obligatorio para ver un archivo de `mint export`. Si el destinatario previsto no puede instalarlo (por ejemplo, una estación de trabajo bloqueada y aislada de la red), comparte una versión portátil de Node.js junto con el archivo, o proporciona la documentación mediante alguna de las alternativas anteriores. diff --git a/fr.json b/fr.json index 998fad760..14fff7f8c 100644 --- a/fr.json +++ b/fr.json @@ -470,7 +470,8 @@ "fr/help-center/register-external-mcp-server-in-discovery", "fr/help-center/visitor-count-dropped-after-crawler-filtering", "fr/help-center/migrate-from-confluence", - "fr/help-center/migrate-docs-from-a-zip-export" + "fr/help-center/migrate-docs-from-a-zip-export", + "fr/help-center/offline-export-requires-node" ] } ] diff --git a/fr/help-center/offline-export-requires-node.mdx b/fr/help-center/offline-export-requires-node.mdx new file mode 100644 index 000000000..b9d6bef7e --- /dev/null +++ b/fr/help-center/offline-export-requires-node.mdx @@ -0,0 +1,31 @@ +--- +title: "Servir une archive d'export hors ligne sans Node.js" +description: "Pourquoi l'archive mint export inclut un serveur Node.js, si vous pouvez l'héberger sur un hôte statique, et que faire sans Node.js installé." +keywords: ["export hors ligne", "hébergement statique", "node.js", "serve.js", "mint export", "environnement isolé", "sans runtime node"] +--- + +Chaque archive produite par `mint export` est livrée avec `serve.js`, un serveur HTTP Node.js sans dépendances que les destinataires exécutent pour consulter la documentation localement. Les lanceurs `Start Docs.command` (macOS) et `Start Docs.bat` (Windows) ne font qu'invoquer `node serve.js`, donc les destinataires doivent avoir [Node.js](https://nodejs.org) v20.17.0 ou ultérieur installé, que le site utilise ou non l'assistant IA, l'aire de jeu API ou toute autre fonctionnalité dynamique. Pour le flux d'export complet, consultez [Export hors ligne](/fr/deploy/export). + +
+## Pourquoi l'archive utilise un serveur local +
+ +L'archive est conçue pour une consultation hors ligne sur la machine du destinataire, et non pour un hébergement sur un serveur web statique. `serve.js` gère la réécriture d'URL et le comportement de type MIME sur lesquels reposent les pages Mintlify lorsqu'elles sont ouvertes à l'adresse `http://localhost:3000`. Ouvrir directement les fichiers `.html` pré-rendus depuis le système de fichiers (`file://`) n'est pas pris en charge et provoque une navigation défaillante et un chargement incorrect des ressources. + +
+## Servir l'export sur un hôte statique +
+ +Mintlify ne publie ni ne prend en charge de mode « purement statique » pour `mint export`. L'archive n'est pas conçue pour être téléversée dans un bucket S3, sur GitHub Pages ou sur un simple site Nginx. + +Si vous avez besoin d'héberger du contenu Mintlify sur un hôte statique sans runtime Node.js, utilisez plutôt l'une de ces approches : + +- **Publier sur Mintlify.** Poussez le même dépôt sur Mintlify et servez-le depuis votre sous-domaine `.mintlify.site` ou un [domaine personnalisé](/fr/customize/custom-domain). C'est la méthode prise en charge pour servir de la documentation Mintlify en HTTP. +- **Auto-hébergement.** Les offres Enterprise incluent une option [auto-hébergée](https://mintlify.com/pricing?ref=self-hosted) qui exécute votre documentation au sein de votre propre infrastructure. Contactez le support pour discuter des prérequis. +- **Demander la fonctionnalité.** Si vous avez besoin que `mint export` produise un bundle hébergeable statiquement, ouvrez une demande sur [GitHub Discussions](https://github.com/orgs/mintlify/discussions/categories/feature-requests) afin que l'équipe puisse évaluer la demande. + +
+## Si le destinataire ne peut pas installer Node.js +
+ +Node.js est une exigence stricte pour consulter une archive `mint export`. Si le destinataire visé ne peut pas l'installer (par exemple, un poste de travail verrouillé en environnement isolé), fournissez une version portable de Node.js à côté de l'archive, ou proposez la documentation via l'une des alternatives ci-dessus. diff --git a/zh.json b/zh.json index 8003849bc..6be425a81 100644 --- a/zh.json +++ b/zh.json @@ -470,7 +470,8 @@ "zh/help-center/register-external-mcp-server-in-discovery", "zh/help-center/visitor-count-dropped-after-crawler-filtering", "zh/help-center/migrate-from-confluence", - "zh/help-center/migrate-docs-from-a-zip-export" + "zh/help-center/migrate-docs-from-a-zip-export", + "zh/help-center/offline-export-requires-node" ] } ] diff --git a/zh/help-center/offline-export-requires-node.mdx b/zh/help-center/offline-export-requires-node.mdx new file mode 100644 index 000000000..9f9f3f80c --- /dev/null +++ b/zh/help-center/offline-export-requires-node.mdx @@ -0,0 +1,31 @@ +--- +title: "无需 Node.js 提供离线导出压缩包" +description: "了解 mint export 压缩包为何附带 Node.js 服务器,是否可托管到纯静态主机,以及在无 Node.js 时应如何处理。" +keywords: ["离线导出", "静态托管", "node.js", "serve.js", "mint export", "隔离网络", "无 node 运行时"] +--- + +`mint export` 生成的每个压缩包都附带了 `serve.js`,这是一个零依赖的 Node.js HTTP 服务器,接收方可运行它以在本地查看文档。`Start Docs.command`(macOS)和 `Start Docs.bat`(Windows)启动器只是调用 `node serve.js`,因此无论站点是否使用 AI 助手、API playground 或任何其他动态功能,接收方都需要安装 [Node.js](https://nodejs.org) v20.17.0+。完整的导出工作流请参见[离线导出](/zh/deploy/export)。 + +
+## 为什么压缩包使用本地服务器 +
+ +该压缩包旨在让接收方在自己的机器上离线查看,而不是托管在静态 Web 服务器上。`serve.js` 处理了 Mintlify 页面在 `http://localhost:3000` 打开时所依赖的 URL 重写和 MIME 类型行为。不支持直接从文件系统(`file://`)打开预渲染的 `.html` 文件,这会导致导航失效和资源加载错误。 + +
+## 在静态主机上提供导出内容 +
+ +Mintlify 不发布也不支持 `mint export` 的"纯静态"模式。压缩包并未针对上传到 S3 存储桶、GitHub Pages 或纯 Nginx 站点而设计。 + +如果你需要在没有 Node.js 运行时的静态主机上提供 Mintlify 内容,请改用以下方案之一: + +- **发布到 Mintlify。** 将相同的仓库推送到 Mintlify,通过你的 `.mintlify.site` 子域名或[自定义域名](/zh/customize/custom-domain)提供服务。这是通过 HTTP 提供 Mintlify 文档的官方受支持方式。 +- **自托管。** Enterprise 方案包含[自托管](https://mintlify.com/pricing?ref=self-hosted)选项,可在你自己的基础设施中运行文档。请联系支持团队了解需求。 +- **提交功能请求。** 如果你希望 `mint export` 生成可静态托管的包,请在 [GitHub Discussions](https://github.com/orgs/mintlify/discussions/categories/feature-requests) 中发起请求,以便团队评估需求。 + +
+## 如果接收方无法安装 Node.js +
+ +查看 `mint export` 压缩包时,Node.js 是硬性要求。如果目标接收方无法安装它(例如受限的隔离网络工作站),请随压缩包一同分发便携式 Node.js 构建,或通过上述替代方案之一提供文档。