diff --git a/.github/workflows/translate.yml b/.github/workflows/translate.yml new file mode 100644 index 000000000..7a44d7ab5 --- /dev/null +++ b/.github/workflows/translate.yml @@ -0,0 +1,22 @@ +name: GT Translate +on: + push: + branches: [main] + +jobs: + translate: + runs-on: ubuntu-latest + if: ${{ github.event.head_commit.author.name != 'github-actions[bot]' && !contains(github.event.head_commit.message, 'gt-translate/') }} + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + + - uses: generaltranslation/translate@v0 + with: + gt_api_key: ${{ secrets.GT_API_KEY }} + gt_project_id: ${{ secrets.GT_PROJECT_ID }} + inline: false + config: 'gt.config.json' + pr_branch: 'gt-translate/${{ github.ref_name }}' \ No newline at end of file diff --git a/.gitignore b/.gitignore index b67b2bc7a..7eb039269 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ node_modules package-lock.json .idea/ .vscode/ +.env diff --git a/docs.json b/docs.json index a137f89a6..a3b910b6f 100644 --- a/docs.json +++ b/docs.json @@ -12,247 +12,999 @@ "library": "lucide" }, "navigation": { - "dropdowns": [ + "languages": [ { - "dropdown": "Documentation", - "icon": "book", - "description": "Set up your documentation", - "groups": [ + "language": "en", + "dropdowns": [ { - "group": "Getting started", - "pages": [ - "index", - "quickstart", - "installation", - "editor" + "dropdown": "Documentation", + "icon": "book", + "description": "Set up your documentation", + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart", + "installation", + "editor" + ] + }, + { + "group": "Core configuration", + "pages": [ + "settings", + "pages", + "navigation", + "themes", + "settings/custom-domain" + ] + }, + { + "group": "AI optimization", + "pages": [ + "guides/assistant", + "ai/llmstxt", + "ai/contextual-menu", + "ai/model-context-protocol", + "ai/markdown-export", + "guides/geo", + "guides/claude-code", + "guides/cursor", + "guides/windsurf", + "ai/slack-app" + ] + }, + { + "group": "Components", + "pages": [ + "text", + "image-embeds", + "list-table", + "code", + "reusable-snippets", + "components/accordions", + "components/callouts", + "components/cards", + "components/columns", + "components/code-groups", + "components/examples", + "components/expandables", + "components/fields", + "components/frames", + "components/icons", + "components/mermaid-diagrams", + "components/panel", + "components/steps", + "components/tabs", + "components/tooltips", + "components/update" + ] + }, + { + "group": "API pages", + "pages": [ + "api-playground/overview", + "api-playground/openapi-setup", + "api-playground/migrating-from-mdx", + { + "group": "Customization", + "icon": "wrench", + "pages": [ + "api-playground/customization/complex-data-types", + "api-playground/customization/adding-sdk-examples", + "api-playground/customization/managing-page-visibility", + "api-playground/customization/multiple-responses" + ] + }, + { + "group": "AsyncAPI", + "icon": "webhook", + "pages": [ + "api-playground/asyncapi/setup", + "api-playground/asyncapi/playground" + ] + }, + { + "group": "MDX", + "icon": "markdown", + "pages": [ + "api-playground/mdx/configuration", + "api-playground/mdx/authentication" + ] + }, + "api-playground/troubleshooting" + ] + }, + { + "group": "Authentication and personalization", + "pages": [ + "authentication-personalization/authentication-setup", + "authentication-personalization/personalization-setup" + ] + }, + { + "group": "Guides", + "pages": [ + "guides/migration", + "guides/analytics", + "react-components", + "settings/custom-scripts", + "settings/seo", + "guides/changelogs", + "guides/hidden-pages", + "settings/broken-links", + "guides/monorepo", + { + "group": "Custom Subdirectory", + "icon": "folder", + "pages": [ + "advanced/subpath/cloudflare", + "advanced/subpath/route53-cloudfront", + "advanced/subpath/vercel" + ] + }, + { + "group": "Dashboard Access", + "icon": "gauge", + "pages": [ + "advanced/dashboard/sso", + "advanced/dashboard/permissions", + "advanced/dashboard/roles" + ] + }, + "guides/deployments", + "contact-support" + ] + }, + { + "group": "Integrations", + "pages": [ + { + "group": "Analytics", + "icon": "chart-no-axes-combined", + "pages": [ + "integrations/analytics/overview", + "integrations/analytics/amplitude", + "integrations/analytics/clearbit", + "integrations/analytics/fathom", + "integrations/analytics/google-analytics", + "integrations/analytics/google-tag-manager", + "integrations/analytics/heap", + "integrations/analytics/hightouch", + "integrations/analytics/hotjar", + "integrations/analytics/koala", + "integrations/analytics/logrocket", + "integrations/analytics/mixpanel", + "integrations/analytics/pirsch", + "integrations/analytics/plausible", + "integrations/analytics/posthog", + "integrations/analytics/segment" + ] + }, + { + "group": "SDKs", + "icon": "folder-code", + "pages": [ + "integrations/sdks/speakeasy", + "integrations/sdks/stainless" + ] + }, + { + "group": "Support", + "icon": "messages-square", + "pages": [ + "integrations/support/overview", + "integrations/support/intercom", + "integrations/support/front" + ] + }, + { + "group": "Privacy", + "icon": "folder-lock", + "pages": [ + "integrations/privacy/overview", + "integrations/privacy/osano" + ] + } + ] + }, + { + "group": "Version control and CI/CD", + "pages": [ + "settings/github", + "settings/gitlab", + "settings/ci", + "settings/preview-deployments" + ] + } ] }, { - "group": "Core configuration", - "pages": [ - "settings", - "pages", - "navigation", - "themes", - "settings/custom-domain" + "dropdown": "API Reference", + "description": "Reference for the API", + "icon": "terminal", + "groups": [ + { + "group": "API Reference", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "Admin", + "pages": [ + "api-reference/update/trigger", + "api-reference/update/status" + ] + }, + { + "group": "Assistant", + "pages": [ + "api-reference/assistant/create-assistant-message", + "api-reference/assistant/search" + ] + } ] }, { - "group": "AI optimization", - "pages": [ - "guides/assistant", - "ai/llmstxt", - "ai/contextual-menu", - "ai/model-context-protocol", - "ai/markdown-export", - "guides/geo", - "guides/claude-code", - "guides/cursor", - "guides/windsurf", - "ai/slack-app" + "dropdown": "Changelog", + "icon": "history", + "description": "Updates and changes", + "groups": [ + { + "group": "Changelog", + "pages": [ + "changelog" + ] + } ] - }, + } + ] + }, + { + "language": "zh", + "dropdowns": [ { - "group": "Components", - "pages": [ - "text", - "image-embeds", - "list-table", - "code", - "reusable-snippets", - "components/accordions", - "components/callouts", - "components/cards", - "components/columns", - "components/code-groups", - "components/examples", - "components/expandables", - "components/fields", - "components/frames", - "components/icons", - "components/mermaid-diagrams", - "components/panel", - "components/steps", - "components/tabs", - "components/tooltips", - "components/update" + "dropdown": "文档", + "icon": "book", + "description": "Set up your documentation", + "groups": [ + { + "group": "快速开始", + "pages": [ + "zh/index", + "zh/quickstart", + "zh/installation", + "zh/editor" + ] + }, + { + "group": "核心配置", + "pages": [ + "zh/settings", + "zh/pages", + "zh/navigation", + "zh/themes", + "zh/settings/custom-domain" + ] + }, + { + "group": "AI 优化", + "pages": [ + "zh/guides/assistant", + "zh/ai/llmstxt", + "zh/ai/contextual-menu", + "zh/ai/model-context-protocol", + "zh/ai/markdown-export", + "zh/guides/geo", + "zh/guides/claude-code", + "zh/guides/cursor", + "zh/guides/windsurf", + "zh/ai/slack-app" + ] + }, + { + "group": "组件", + "pages": [ + "zh/text", + "zh/image-embeds", + "zh/list-table", + "zh/code", + "zh/reusable-snippets", + "zh/components/accordions", + "zh/components/callouts", + "zh/components/cards", + "zh/components/columns", + "zh/components/code-groups", + "zh/components/examples", + "zh/components/expandables", + "zh/components/fields", + "zh/components/frames", + "zh/components/icons", + "zh/components/mermaid-diagrams", + "zh/components/panel", + "zh/components/steps", + "zh/components/tabs", + "zh/components/tooltips", + "zh/components/update" + ] + }, + { + "group": "API 页面", + "pages": [ + "zh/api-playground/overview", + "zh/api-playground/openapi-setup", + "zh/api-playground/migrating-from-mdx", + { + "group": "自定义", + "icon": "wrench", + "pages": [ + "zh/api-playground/customization/complex-data-types", + "zh/api-playground/customization/adding-sdk-examples", + "zh/api-playground/customization/managing-page-visibility", + "zh/api-playground/customization/multiple-responses" + ] + }, + { + "group": "AsyncAPI", + "icon": "webhook", + "pages": [ + "zh/api-playground/asyncapi/setup", + "zh/api-playground/asyncapi/playground" + ] + }, + { + "group": "MDX", + "icon": "markdown", + "pages": [ + "zh/api-playground/mdx/configuration", + "zh/api-playground/mdx/authentication" + ] + }, + "zh/api-playground/troubleshooting" + ] + }, + { + "group": "认证与个性化", + "pages": [ + "zh/authentication-personalization/authentication-setup", + "zh/authentication-personalization/personalization-setup" + ] + }, + { + "group": "指南", + "pages": [ + "zh/guides/migration", + "zh/guides/analytics", + "zh/react-components", + "zh/settings/custom-scripts", + "zh/settings/seo", + "zh/guides/changelogs", + "zh/guides/hidden-pages", + "zh/settings/broken-links", + "zh/guides/monorepo", + { + "group": "自定义子目录", + "icon": "folder", + "pages": [ + "zh/advanced/subpath/cloudflare", + "zh/advanced/subpath/route53-cloudfront", + "zh/advanced/subpath/vercel" + ] + }, + { + "group": "仪表盘访问权限", + "icon": "gauge", + "pages": [ + "zh/advanced/dashboard/sso", + "zh/advanced/dashboard/permissions", + "zh/advanced/dashboard/roles" + ] + }, + "zh/guides/deployments", + "zh/contact-support" + ] + }, + { + "group": "集成", + "pages": [ + { + "group": "分析", + "icon": "chart-no-axes-combined", + "pages": [ + "zh/integrations/analytics/overview", + "zh/integrations/analytics/amplitude", + "zh/integrations/analytics/clearbit", + "zh/integrations/analytics/fathom", + "zh/integrations/analytics/google-analytics", + "zh/integrations/analytics/google-tag-manager", + "zh/integrations/analytics/heap", + "zh/integrations/analytics/hightouch", + "zh/integrations/analytics/hotjar", + "zh/integrations/analytics/koala", + "zh/integrations/analytics/logrocket", + "zh/integrations/analytics/mixpanel", + "zh/integrations/analytics/pirsch", + "zh/integrations/analytics/plausible", + "zh/integrations/analytics/posthog", + "zh/integrations/analytics/segment" + ] + }, + { + "group": "SDK", + "icon": "folder-code", + "pages": [ + "zh/integrations/sdks/speakeasy", + "zh/integrations/sdks/stainless" + ] + }, + { + "group": "支持", + "icon": "messages-square", + "pages": [ + "zh/integrations/support/overview", + "zh/integrations/support/intercom", + "zh/integrations/support/front" + ] + }, + { + "group": "隐私", + "icon": "folder-lock", + "pages": [ + "zh/integrations/privacy/overview", + "zh/integrations/privacy/osano" + ] + } + ] + }, + { + "group": "版本控制与 CI/CD", + "pages": [ + "zh/settings/github", + "zh/settings/gitlab", + "zh/settings/ci", + "zh/settings/preview-deployments" + ] + } ] }, { - "group": "API pages", - "pages": [ - "api-playground/overview", - "api-playground/openapi-setup", - "api-playground/migrating-from-mdx", + "dropdown": "API 参考", + "description": "Reference for the API", + "icon": "terminal", + "groups": [ { - "group": "Customization", - "icon": "wrench", + "group": "API 参考", "pages": [ - "api-playground/customization/complex-data-types", - "api-playground/customization/adding-sdk-examples", - "api-playground/customization/managing-page-visibility", - "api-playground/customization/multiple-responses" + "zh/api-reference/introduction" ] }, { - "group": "AsyncAPI", - "icon": "webhook", + "group": "管理员", "pages": [ - "api-playground/asyncapi/setup", - "api-playground/asyncapi/playground" + "zh/api-reference/update/trigger", + "zh/api-reference/update/status" ] }, { - "group": "MDX", - "icon": "markdown", + "group": "Assistant", "pages": [ - "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "zh/api-reference/assistant/create-assistant-message", + "zh/api-reference/assistant/search" ] - }, - "api-playground/troubleshooting" + } ] }, { - "group": "Authentication and personalization", - "pages": [ - "authentication-personalization/authentication-setup", - "authentication-personalization/personalization-setup" + "dropdown": "更新日志", + "icon": "history", + "description": "Updates and changes", + "groups": [ + { + "group": "更新日志", + "pages": [ + "zh/changelog" + ] + } ] - }, + } + ] + }, + { + "language": "es", + "dropdowns": [ { - "group": "Guides", - "pages": [ - "guides/migration", - "guides/analytics", - "react-components", - "settings/custom-scripts", - "settings/seo", - "guides/changelogs", - "guides/hidden-pages", - "settings/broken-links", - "guides/monorepo", + "dropdown": "Documentación", + "icon": "book", + "description": "Set up your documentation", + "groups": [ { - "group": "Custom Subdirectory", - "icon": "folder", + "group": "Primeros pasos", "pages": [ - "advanced/subpath/cloudflare", - "advanced/subpath/route53-cloudfront", - "advanced/subpath/vercel" + "es/index", + "es/quickstart", + "es/installation", + "es/editor" ] }, { - "group": "Dashboard Access", - "icon": "gauge", + "group": "Configuración básica", "pages": [ - "advanced/dashboard/sso", - "advanced/dashboard/permissions", - "advanced/dashboard/roles" + "es/settings", + "es/pages", + "es/navigation", + "es/themes", + "es/settings/custom-domain" + ] + }, + { + "group": "Optimización de IA", + "pages": [ + "es/guides/assistant", + "es/ai/llmstxt", + "es/ai/contextual-menu", + "es/ai/model-context-protocol", + "es/ai/markdown-export", + "es/guides/geo", + "es/guides/claude-code", + "es/guides/cursor", + "es/guides/windsurf", + "es/ai/slack-app" + ] + }, + { + "group": "Componentes", + "pages": [ + "es/text", + "es/image-embeds", + "es/list-table", + "es/code", + "es/reusable-snippets", + "es/components/accordions", + "es/components/callouts", + "es/components/cards", + "es/components/columns", + "es/components/code-groups", + "es/components/examples", + "es/components/expandables", + "es/components/fields", + "es/components/frames", + "es/components/icons", + "es/components/mermaid-diagrams", + "es/components/panel", + "es/components/steps", + "es/components/tabs", + "es/components/tooltips", + "es/components/update" + ] + }, + { + "group": "Páginas de API", + "pages": [ + "es/api-playground/overview", + "es/api-playground/openapi-setup", + "es/api-playground/migrating-from-mdx", + { + "group": "Personalización", + "icon": "wrench", + "pages": [ + "es/api-playground/customization/complex-data-types", + "es/api-playground/customization/adding-sdk-examples", + "es/api-playground/customization/managing-page-visibility", + "es/api-playground/customization/multiple-responses" + ] + }, + { + "group": "AsyncAPI", + "icon": "webhook", + "pages": [ + "es/api-playground/asyncapi/setup", + "es/api-playground/asyncapi/playground" + ] + }, + { + "group": "MDX", + "icon": "markdown", + "pages": [ + "es/api-playground/mdx/configuration", + "es/api-playground/mdx/authentication" + ] + }, + "es/api-playground/troubleshooting" + ] + }, + { + "group": "Autenticación y personalización", + "pages": [ + "es/authentication-personalization/authentication-setup", + "es/authentication-personalization/personalization-setup" ] }, - "guides/deployments", - "contact-support" - ] - }, - { - "group": "Integrations", - "pages": [ { - "group": "Analytics", - "icon": "chart-no-axes-combined", + "group": "Guías", "pages": [ - "integrations/analytics/overview", - "integrations/analytics/amplitude", - "integrations/analytics/clearbit", - "integrations/analytics/fathom", - "integrations/analytics/google-analytics", - "integrations/analytics/google-tag-manager", - "integrations/analytics/heap", - "integrations/analytics/hightouch", - "integrations/analytics/hotjar", - "integrations/analytics/koala", - "integrations/analytics/logrocket", - "integrations/analytics/mixpanel", - "integrations/analytics/pirsch", - "integrations/analytics/plausible", - "integrations/analytics/posthog", - "integrations/analytics/segment" + "es/guides/migration", + "es/guides/analytics", + "es/react-components", + "es/settings/custom-scripts", + "es/settings/seo", + "es/guides/changelogs", + "es/guides/hidden-pages", + "es/settings/broken-links", + "es/guides/monorepo", + { + "group": "Subdirectorio personalizado", + "icon": "folder", + "pages": [ + "es/advanced/subpath/cloudflare", + "es/advanced/subpath/route53-cloudfront", + "es/advanced/subpath/vercel" + ] + }, + { + "group": "Acceso al panel", + "icon": "gauge", + "pages": [ + "es/advanced/dashboard/sso", + "es/advanced/dashboard/permissions", + "es/advanced/dashboard/roles" + ] + }, + "es/guides/deployments", + "es/contact-support" ] }, { - "group": "SDKs", - "icon": "folder-code", + "group": "Integraciones", + "pages": [ + { + "group": "Analítica", + "icon": "chart-no-axes-combined", + "pages": [ + "es/integrations/analytics/overview", + "es/integrations/analytics/amplitude", + "es/integrations/analytics/clearbit", + "es/integrations/analytics/fathom", + "es/integrations/analytics/google-analytics", + "es/integrations/analytics/google-tag-manager", + "es/integrations/analytics/heap", + "es/integrations/analytics/hightouch", + "es/integrations/analytics/hotjar", + "es/integrations/analytics/koala", + "es/integrations/analytics/logrocket", + "es/integrations/analytics/mixpanel", + "es/integrations/analytics/pirsch", + "es/integrations/analytics/plausible", + "es/integrations/analytics/posthog", + "es/integrations/analytics/segment" + ] + }, + { + "group": "SDKs", + "icon": "folder-code", + "pages": [ + "es/integrations/sdks/speakeasy", + "es/integrations/sdks/stainless" + ] + }, + { + "group": "Soporte", + "icon": "messages-square", + "pages": [ + "es/integrations/support/overview", + "es/integrations/support/intercom", + "es/integrations/support/front" + ] + }, + { + "group": "Privacidad", + "icon": "folder-lock", + "pages": [ + "es/integrations/privacy/overview", + "es/integrations/privacy/osano" + ] + } + ] + }, + { + "group": "Control de versiones y CI/CD", + "pages": [ + "es/settings/github", + "es/settings/gitlab", + "es/settings/ci", + "es/settings/preview-deployments" + ] + } + ] + }, + { + "dropdown": "Referencia de API", + "description": "Reference for the API", + "icon": "terminal", + "groups": [ + { + "group": "Referencia de la API", "pages": [ - "integrations/sdks/speakeasy", - "integrations/sdks/stainless" + "es/api-reference/introduction" ] }, { - "group": "Support", - "icon": "messages-square", + "group": "Administrador", "pages": [ - "integrations/support/overview", - "integrations/support/intercom", - "integrations/support/front" + "es/api-reference/update/trigger", + "es/api-reference/update/status" ] }, { - "group": "Privacy", - "icon": "folder-lock", + "group": "Asistente", "pages": [ - "integrations/privacy/overview", - "integrations/privacy/osano" + "es/api-reference/assistant/create-assistant-message", + "es/api-reference/assistant/search" ] } ] }, { - "group": "Version control and CI/CD", - "pages": [ - "settings/github", - "settings/gitlab", - "settings/ci", - "settings/preview-deployments" + "dropdown": "Registro de cambios", + "icon": "history", + "description": "Updates and changes", + "groups": [ + { + "group": "Registro de cambios", + "pages": [ + "es/changelog" + ] + } ] } ] }, { - "dropdown": "API Reference", - "description": "Reference for the API", - "icon": "terminal", - "groups": [ + "language": "fr", + "dropdowns": [ { - "group": "API Reference", - "pages": [ - "api-reference/introduction" + "dropdown": "Documentation", + "icon": "book", + "description": "Set up your documentation", + "groups": [ + { + "group": "Démarrage", + "pages": [ + "fr/index", + "fr/quickstart", + "fr/installation", + "fr/editor" + ] + }, + { + "group": "Configuration de base", + "pages": [ + "fr/settings", + "fr/pages", + "fr/navigation", + "fr/themes", + "fr/settings/custom-domain" + ] + }, + { + "group": "Optimisation IA", + "pages": [ + "fr/guides/assistant", + "fr/ai/llmstxt", + "fr/ai/contextual-menu", + "fr/ai/model-context-protocol", + "fr/ai/markdown-export", + "fr/guides/geo", + "fr/guides/claude-code", + "fr/guides/cursor", + "fr/guides/windsurf", + "fr/ai/slack-app" + ] + }, + { + "group": "Composants", + "pages": [ + "fr/text", + "fr/image-embeds", + "fr/list-table", + "fr/code", + "fr/reusable-snippets", + "fr/components/accordions", + "fr/components/callouts", + "fr/components/cards", + "fr/components/columns", + "fr/components/code-groups", + "fr/components/examples", + "fr/components/expandables", + "fr/components/fields", + "fr/components/frames", + "fr/components/icons", + "fr/components/mermaid-diagrams", + "fr/components/panel", + "fr/components/steps", + "fr/components/tabs", + "fr/components/tooltips", + "fr/components/update" + ] + }, + { + "group": "Pages API", + "pages": [ + "fr/api-playground/overview", + "fr/api-playground/openapi-setup", + "fr/api-playground/migrating-from-mdx", + { + "group": "Personnalisation", + "icon": "wrench", + "pages": [ + "fr/api-playground/customization/complex-data-types", + "fr/api-playground/customization/adding-sdk-examples", + "fr/api-playground/customization/managing-page-visibility", + "fr/api-playground/customization/multiple-responses" + ] + }, + { + "group": "AsyncAPI (spécification pour événements/websockets)", + "icon": "webhook", + "pages": [ + "fr/api-playground/asyncapi/setup", + "fr/api-playground/asyncapi/playground" + ] + }, + { + "group": "MDX (Markdown étendu avec composants React)", + "icon": "markdown", + "pages": [ + "fr/api-playground/mdx/configuration", + "fr/api-playground/mdx/authentication" + ] + }, + "fr/api-playground/troubleshooting" + ] + }, + { + "group": "Authentification et personnalisation", + "pages": [ + "fr/authentication-personalization/authentication-setup", + "fr/authentication-personalization/personalization-setup" + ] + }, + { + "group": "Guides", + "pages": [ + "fr/guides/migration", + "fr/guides/analytics", + "fr/react-components", + "fr/settings/custom-scripts", + "fr/settings/seo", + "fr/guides/changelogs", + "fr/guides/hidden-pages", + "fr/settings/broken-links", + "fr/guides/monorepo", + { + "group": "Sous-répertoire personnalisé", + "icon": "folder", + "pages": [ + "fr/advanced/subpath/cloudflare", + "fr/advanced/subpath/route53-cloudfront", + "fr/advanced/subpath/vercel" + ] + }, + { + "group": "Accès au tableau de bord", + "icon": "gauge", + "pages": [ + "fr/advanced/dashboard/sso", + "fr/advanced/dashboard/permissions", + "fr/advanced/dashboard/roles" + ] + }, + "fr/guides/deployments", + "fr/contact-support" + ] + }, + { + "group": "Intégrations", + "pages": [ + { + "group": "Analytique", + "icon": "chart-no-axes-combined", + "pages": [ + "fr/integrations/analytics/overview", + "fr/integrations/analytics/amplitude", + "fr/integrations/analytics/clearbit", + "fr/integrations/analytics/fathom", + "fr/integrations/analytics/google-analytics", + "fr/integrations/analytics/google-tag-manager", + "fr/integrations/analytics/heap", + "fr/integrations/analytics/hightouch", + "fr/integrations/analytics/hotjar", + "fr/integrations/analytics/koala", + "fr/integrations/analytics/logrocket", + "fr/integrations/analytics/mixpanel", + "fr/integrations/analytics/pirsch", + "fr/integrations/analytics/plausible", + "fr/integrations/analytics/posthog", + "fr/integrations/analytics/segment" + ] + }, + { + "group": "Kits SDK", + "icon": "folder-code", + "pages": [ + "fr/integrations/sdks/speakeasy", + "fr/integrations/sdks/stainless" + ] + }, + { + "group": "Support", + "icon": "messages-square", + "pages": [ + "fr/integrations/support/overview", + "fr/integrations/support/intercom", + "fr/integrations/support/front" + ] + }, + { + "group": "Confidentialité", + "icon": "folder-lock", + "pages": [ + "fr/integrations/privacy/overview", + "fr/integrations/privacy/osano" + ] + } + ] + }, + { + "group": "Gestion de versions et CI/CD", + "pages": [ + "fr/settings/github", + "fr/settings/gitlab", + "fr/settings/ci", + "fr/settings/preview-deployments" + ] + } ] }, { - "group": "Admin", - "pages": [ - "api-reference/update/trigger", - "api-reference/update/status" + "dropdown": "Référence API", + "description": "Reference for the API", + "icon": "terminal", + "groups": [ + { + "group": "Référence de l’API", + "pages": [ + "fr/api-reference/introduction" + ] + }, + { + "group": "Admin", + "pages": [ + "fr/api-reference/update/trigger", + "fr/api-reference/update/status" + ] + }, + { + "group": "Assistant", + "pages": [ + "fr/api-reference/assistant/create-assistant-message", + "fr/api-reference/assistant/search" + ] + } ] }, { - "group": "Assistant", - "pages": [ - "api-reference/assistant/create-assistant-message", - "api-reference/assistant/search" - ] - } - ] - }, - { - "dropdown": "Changelog", - "icon": "history", - "description": "Updates and changes", - "groups": [ - { - "group": "Changelog", - "pages": [ - "changelog" + "dropdown": "Journal des modifications", + "icon": "history", + "description": "Updates and changes", + "groups": [ + { + "group": "Journal des modifications", + "pages": [ + "fr/changelog" + ] + } ] } ] @@ -506,6 +1258,438 @@ { "source": "api-reference/chat/*", "destination": "api-reference/assistant/*" + }, + { + "source": "/es/content/components/accordions", + "destination": "/es/components/accordions" + }, + { + "source": "/es/content/components/callouts", + "destination": "/es/components/callouts" + }, + { + "source": "/es/content/components/cards", + "destination": "/es/components/cards" + }, + { + "source": "/es/content/components/card-groups", + "destination": "/es/components/columns" + }, + { + "source": "/es/content/components/code-groups", + "destination": "/es/components/code-groups" + }, + { + "source": "/es/content/components/examples", + "destination": "/es/components/examples" + }, + { + "source": "/es/content/components/expandables", + "destination": "/es/components/expandables" + }, + { + "source": "/es/content/components/fields", + "destination": "/es/components/fields" + }, + { + "source": "/es/content/components/frames", + "destination": "/es/components/frames" + }, + { + "source": "/es/content/components/icons", + "destination": "/es/components/icons" + }, + { + "source": "/es/content/components/mermaid-diagrams", + "destination": "/es/components/mermaid-diagrams" + }, + { + "source": "/es/content/components/steps", + "destination": "/es/components/steps" + }, + { + "source": "/es/content/components/tabs", + "destination": "/es/components/tabs" + }, + { + "source": "/es/content/components/tooltips", + "destination": "/es/components/tooltips" + }, + { + "source": "/es/content/components/update", + "destination": "/es/components/update" + }, + { + "source": "/es/api-playground/openapi/advanced-features", + "destination": "/es/api-playground/customization" + }, + { + "source": "/es/api-playground/openapi/setup", + "destination": "/es/api-playground/openapi-setup" + }, + { + "source": "/es/api-playground/openapi/writing-openapi", + "destination": "/es/api-playground/openapi-setup" + }, + { + "source": "es/settings/authentication-personalization/authentication-vs-personalization", + "destination": "es/authentication-personalization/overview" + }, + { + "source": "es/settings/authentication-personalization/authentication-setup/choosing-a-handshake", + "destination": "es/authentication-personalization/overview" + }, + { + "source": "es/settings/authentication-personalization/personalization-setup/choosing-a-handshake", + "destination": "es/authentication-personalization/overview" + }, + { + "source": "es/settings/authentication-personalization/authentication", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/personalization", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/settings/authentication-personalization/partial-authentication", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/sending-data", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/authentication-personalization/partial-authentication-setup", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/authentication-personalization/sending-data", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/settings/authentication-personalization/authentication-setup/jwt", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/authentication-setup/oauth", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/authentication-setup/mintlify", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/authentication-setup/password", + "destination": "es/authentication-personalization/authentication-setup" + }, + { + "source": "es/settings/authentication-personalization/personalization-setup/jwt", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/settings/authentication-personalization/personalization-setup/oauth", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/settings/authentication-personalization/personalization-setup/shared-session", + "destination": "es/authentication-personalization/personalization-setup" + }, + { + "source": "es/ai-ingestion", + "destination": "es/ai/llmstxt" + }, + { + "source": "es/api-reference/chat/*", + "destination": "es/api-reference/assistant/*" + }, + { + "source": "/fr/content/components/accordions", + "destination": "/fr/components/accordions" + }, + { + "source": "/fr/content/components/callouts", + "destination": "/fr/components/callouts" + }, + { + "source": "/fr/content/components/cards", + "destination": "/fr/components/cards" + }, + { + "source": "/fr/content/components/card-groups", + "destination": "/fr/components/columns" + }, + { + "source": "/fr/content/components/code-groups", + "destination": "/fr/components/code-groups" + }, + { + "source": "/fr/content/components/examples", + "destination": "/fr/components/examples" + }, + { + "source": "/fr/content/components/expandables", + "destination": "/fr/components/expandables" + }, + { + "source": "/fr/content/components/fields", + "destination": "/fr/components/fields" + }, + { + "source": "/fr/content/components/frames", + "destination": "/fr/components/frames" + }, + { + "source": "/fr/content/components/icons", + "destination": "/fr/components/icons" + }, + { + "source": "/fr/content/components/mermaid-diagrams", + "destination": "/fr/components/mermaid-diagrams" + }, + { + "source": "/fr/content/components/steps", + "destination": "/fr/components/steps" + }, + { + "source": "/fr/content/components/tabs", + "destination": "/fr/components/tabs" + }, + { + "source": "/fr/content/components/tooltips", + "destination": "/fr/components/tooltips" + }, + { + "source": "/fr/content/components/update", + "destination": "/fr/components/update" + }, + { + "source": "/fr/api-playground/openapi/advanced-features", + "destination": "/fr/api-playground/customization" + }, + { + "source": "/fr/api-playground/openapi/setup", + "destination": "/fr/api-playground/openapi-setup" + }, + { + "source": "/fr/api-playground/openapi/writing-openapi", + "destination": "/fr/api-playground/openapi-setup" + }, + { + "source": "fr/settings/authentication-personalization/authentication-vs-personalization", + "destination": "fr/authentication-personalization/overview" + }, + { + "source": "fr/settings/authentication-personalization/authentication-setup/choosing-a-handshake", + "destination": "fr/authentication-personalization/overview" + }, + { + "source": "fr/settings/authentication-personalization/personalization-setup/choosing-a-handshake", + "destination": "fr/authentication-personalization/overview" + }, + { + "source": "fr/settings/authentication-personalization/authentication", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/personalization", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/settings/authentication-personalization/partial-authentication", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/sending-data", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/authentication-personalization/partial-authentication-setup", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/authentication-personalization/sending-data", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/settings/authentication-personalization/authentication-setup/jwt", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/authentication-setup/oauth", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/authentication-setup/mintlify", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/authentication-setup/password", + "destination": "fr/authentication-personalization/authentication-setup" + }, + { + "source": "fr/settings/authentication-personalization/personalization-setup/jwt", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/settings/authentication-personalization/personalization-setup/oauth", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/settings/authentication-personalization/personalization-setup/shared-session", + "destination": "fr/authentication-personalization/personalization-setup" + }, + { + "source": "fr/ai-ingestion", + "destination": "fr/ai/llmstxt" + }, + { + "source": "fr/api-reference/chat/*", + "destination": "fr/api-reference/assistant/*" + }, + { + "source": "/zh/content/components/accordions", + "destination": "/zh/components/accordions" + }, + { + "source": "/zh/content/components/callouts", + "destination": "/zh/components/callouts" + }, + { + "source": "/zh/content/components/cards", + "destination": "/zh/components/cards" + }, + { + "source": "/zh/content/components/card-groups", + "destination": "/zh/components/columns" + }, + { + "source": "/zh/content/components/code-groups", + "destination": "/zh/components/code-groups" + }, + { + "source": "/zh/content/components/examples", + "destination": "/zh/components/examples" + }, + { + "source": "/zh/content/components/expandables", + "destination": "/zh/components/expandables" + }, + { + "source": "/zh/content/components/fields", + "destination": "/zh/components/fields" + }, + { + "source": "/zh/content/components/frames", + "destination": "/zh/components/frames" + }, + { + "source": "/zh/content/components/icons", + "destination": "/zh/components/icons" + }, + { + "source": "/zh/content/components/mermaid-diagrams", + "destination": "/zh/components/mermaid-diagrams" + }, + { + "source": "/zh/content/components/steps", + "destination": "/zh/components/steps" + }, + { + "source": "/zh/content/components/tabs", + "destination": "/zh/components/tabs" + }, + { + "source": "/zh/content/components/tooltips", + "destination": "/zh/components/tooltips" + }, + { + "source": "/zh/content/components/update", + "destination": "/zh/components/update" + }, + { + "source": "/zh/api-playground/openapi/advanced-features", + "destination": "/zh/api-playground/customization" + }, + { + "source": "/zh/api-playground/openapi/setup", + "destination": "/zh/api-playground/openapi-setup" + }, + { + "source": "/zh/api-playground/openapi/writing-openapi", + "destination": "/zh/api-playground/openapi-setup" + }, + { + "source": "zh/settings/authentication-personalization/authentication-vs-personalization", + "destination": "zh/authentication-personalization/overview" + }, + { + "source": "zh/settings/authentication-personalization/authentication-setup/choosing-a-handshake", + "destination": "zh/authentication-personalization/overview" + }, + { + "source": "zh/settings/authentication-personalization/personalization-setup/choosing-a-handshake", + "destination": "zh/authentication-personalization/overview" + }, + { + "source": "zh/settings/authentication-personalization/authentication", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/personalization", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/settings/authentication-personalization/partial-authentication", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/sending-data", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/authentication-personalization/partial-authentication-setup", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/authentication-personalization/sending-data", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/settings/authentication-personalization/authentication-setup/jwt", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/authentication-setup/oauth", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/authentication-setup/mintlify", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/authentication-setup/password", + "destination": "zh/authentication-personalization/authentication-setup" + }, + { + "source": "zh/settings/authentication-personalization/personalization-setup/jwt", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/settings/authentication-personalization/personalization-setup/oauth", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/settings/authentication-personalization/personalization-setup/shared-session", + "destination": "zh/authentication-personalization/personalization-setup" + }, + { + "source": "zh/ai-ingestion", + "destination": "zh/ai/llmstxt" + }, + { + "source": "zh/api-reference/chat/*", + "destination": "zh/api-reference/assistant/*" } ], "integrations": { @@ -516,4 +1700,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/es/advanced/dashboard/permissions.mdx b/es/advanced/dashboard/permissions.mdx new file mode 100644 index 000000000..573b42181 --- /dev/null +++ b/es/advanced/dashboard/permissions.mdx @@ -0,0 +1,16 @@ +--- +title: "Permisos de editor" +description: "Permite que más miembros de tu equipo actualicen tu documentación" +--- + +Un editor tiene acceso a tu panel y al editor web. + +Cualquiera puede contribuir a tu documentación trabajando localmente y enviando cambios a tu repositorio, pero hay diferencias clave en cómo se publican los cambios: + +* **Cambios de editor**: Cuando un editor publica a través del editor web o fusiona una pull request en tu repositorio de documentación, los cambios se despliegan automáticamente en tu sitio en vivo. +* **Cambios de no editor**: Cuando alguien que no es editor fusiona una pull request en tu repositorio, debes activar manualmente un despliegue desde tu panel para que esos cambios aparezcan en tu sitio en vivo. + +## Agregar editores +De forma predeterminada, el miembro del equipo que creó tu organización de Mintlify tiene acceso de editor. Agrega editores adicionales en la página [Members](https://dashboard.mintlify.com/settings/organization/members) de tu panel. + +Los puestos de editor se facturan según el uso y puedes tener tantos editores como necesites. Consulta nuestra [página de precios](https://mintlify.com/pricing) para más detalles. diff --git a/es/advanced/dashboard/roles.mdx b/es/advanced/dashboard/roles.mdx new file mode 100644 index 000000000..789de7fe5 --- /dev/null +++ b/es/advanced/dashboard/roles.mdx @@ -0,0 +1,26 @@ +--- +title: "Roles" +description: "Controla el acceso a tu panel con roles." +--- + + + La funcionalidad de RBAC está disponible en el [plan Enterprise](https://mintlify.com/pricing?ref=rbac). + + +Mintlify ofrece dos niveles de acceso al panel: Editor y Administrador. + +A continuación se describen las acciones limitadas al rol de Administrador: + +| | Editor | Administrador | +| ----------------------- | :----: | :-----------: | +| Actualizar roles de usuario | ❌ | ✅ | +| Eliminar usuarios | ❌ | ✅ | +| Invitar usuarios administradores | ❌ | ✅ | +| Administrar y actualizar la facturación | ❌ | ✅ | +| Actualizar el dominio personalizado | ❌ | ✅ | +| Actualizar la fuente de Git | ❌ | ✅ | +| Eliminar la organización | ❌ | ✅ | + +Otras acciones en el panel están disponibles para ambos roles. + +Puedes invitar a tantos administradores como quieras, pero recomendamos limitar el acceso de administrador a los usuarios que lo necesiten. diff --git a/es/advanced/dashboard/sso.mdx b/es/advanced/dashboard/sso.mdx new file mode 100644 index 000000000..1f29c28c7 --- /dev/null +++ b/es/advanced/dashboard/sso.mdx @@ -0,0 +1,129 @@ +--- +title: "Inicio de sesión único (SSO)" +description: "Personaliza cómo tu equipo puede iniciar sesión en el panel de administración" +--- + + + La funcionalidad de SSO está disponible en el [plan Enterprise](https://mintlify.com/pricing?ref=sso). + + +Usa el inicio de sesión único en tu panel mediante SAML y OIDC. Si usas Okta, Google Workspace o Microsoft Entra, contamos con documentación específica del proveedor para configurar SSO. Si usas otro proveedor, [contáctanos](mailto:support@mintlify.com). + +## Okta + + + + + + En `Applications`, haz clic para crear una nueva integración de aplicación usando SAML 2.0. + + + Ingresa lo siguiente: + * Single sign-on URL (proporcionada por Mintlify) + * Audience URI (proporcionada por Mintlify) + * Name ID Format: `EmailAddress` + * Attribute Statements: + | Name | Name format | Value + | ---- | ----------- | ----- + | `firstName` | Basic | `user.firstName` | + | `lastName` | Basic | `user.lastName` | + + + Una vez configurada la aplicación, ve a la pestaña de inicio de sesión y envíanos la URL de metadatos. + Habilitaremos la conexión por nuestra parte usando esta información. + + + + + + + En `Applications`, haz clic para crear una nueva integración de aplicación usando OIDC. + Debes elegir el tipo de aplicación `Web Application`. + + + Selecciona el tipo de concesión Authorization Code e ingresa la Redirect URI proporcionada por Mintlify. + + + Una vez configurada la aplicación, ve a la pestaña General y localiza el client ID y el client secret. + Por favor, proporciónanos ambos de forma segura, junto con la URL de tu instancia de Okta (p. ej., `.okta.com`). Puedes enviarlos mediante un servicio como 1Password o SendSafely. + + + + + +## Google Workspace + + + + + + En `Web and mobile apps`, selecciona `Add custom SAML app` en el menú desplegable `Add app`. + + ![](/images/gsuite-add-custom-saml-app.png) + + + + Copia la SSO URL, el Entity ID y el certificado x509 proporcionados y envíalos al equipo de Mintlify. + + ![](/images/gsuite-saml-metadata.png) + + + + En la página Service provider details, introduce lo siguiente: + * ACS URL (proporcionado por Mintlify) + * Entity ID (proporcionado por Mintlify) + * Name ID format: `EMAIL` + * Name ID: `Basic Information > Primary email` + + + ![](/images/gsuite-sp-details.png) + + + En la siguiente página, introduce las siguientes declaraciones de atributos: + | Google Directory Attribute | App Attribute | + | -------------------------- | ------------- | + | `First name` | `firstName` | + | `Last name` | `lastName` | + + Cuando completes este paso y los usuarios estén asignados a la aplicación, avísanos y habilitaremos el SSO para tu cuenta. + + + + + +## Microsoft Entra + + + + + + 1. En "Enterprise applications", selecciona **New application**. + 2. Selecciona **Create your own application** y elige "Integrate any other application you don't find in the gallery (Non-gallery)." + + + Ve a la página de configuración de Single Sign-On y selecciona **SAML**. En "Basic SAML Configuration", ingresa lo siguiente: + * Identifier (Entity ID): el Audience URI proporcionado por Mintlify. + * Reply URL (Assertion Consumer Service URL): la URL de ACS proporcionada por Mintlify. + + Deja los demás valores en blanco y selecciona **Save**. + + + Edita la sección Attributes & Claims: + 1. Selecciona **Unique User Identifier (Name ID)** en "Required Claim". + 2. Cambia el Source attribute para usar `user.primaryauthoritativeemail`. + 3. En Additional claims, crea los siguientes claims: + | Name | Value | + | ---- | ----- | + | `firstName` | `user.givenname` | + | `lastName` | `user.surname` | + + + Una vez que la aplicación esté configurada, ve a la sección "SAML Certificates" y envíanos el App Federation Metadata URL. + Habilitaremos la conexión de nuestro lado usando esta información. + + + Ve a "Users and groups" en tu aplicación de Entra y agrega a los usuarios que deban tener acceso a tu panel. + + + + diff --git a/es/advanced/subpath/cloudflare.mdx b/es/advanced/subpath/cloudflare.mdx new file mode 100644 index 000000000..1eab8154b --- /dev/null +++ b/es/advanced/subpath/cloudflare.mdx @@ -0,0 +1,180 @@ +--- +title: "Cloudflare" +description: "Aloja la documentación en la subruta /docs usando Cloudflare Workers" +--- + +import Propagating from "/snippets/custom-subpath-propagating.mdx"; + +Para alojar tu documentación en la subruta `/docs` usando Cloudflare, tendrás que crear y configurar un Cloudflare Worker. + + + Antes de empezar, necesitas una cuenta de Cloudflare y un nombre de dominio (puede estar gestionado dentro o fuera de Cloudflare). + + +## Configura un Cloudflare Worker + +Crea un Cloudflare Worker siguiendo la [guía de introducción de Cloudflare Workers](https://developers.cloudflare.com/workers/get-started/dashboard/), si aún no lo has hecho. + + + Si tu proveedor de DNS es Cloudflare, no actives el proxy para el registro CNAME. + + +### Proxies con implementaciones en Vercel + +Si usas Cloudflare como proxy con implementaciones en Vercel, debes asegurarte de una configuración adecuada para evitar conflictos con la verificación de dominio de Vercel y la emisión de certificados SSL. + +Una configuración de proxy incorrecta puede impedir que Vercel emita certificados SSL de Let's Encrypt y provocar fallos en la verificación de dominio. + +#### Lista de rutas permitidas requerida + +Tu Cloudflare Worker debe permitir el tráfico a estas rutas específicas sin bloquear ni redirigir: + +- `/.well-known/acme-challenge/*` - Requerido para la verificación de certificados de Let's Encrypt +- `/.well-known/vercel/*` - Requerido para la verificación de dominio de Vercel + +Aunque Cloudflare gestiona automáticamente muchas reglas de verificación, crear reglas personalizadas adicionales puede bloquear inadvertidamente este tráfico crítico. + +#### Requisitos de reenvío de encabezados + +Asegúrate de que el encabezado `HOST` se reenvíe correctamente en la configuración de tu Worker. No reenviar los encabezados adecuadamente hará que las solicitudes de verificación fallen. + +### Configura el enrutamiento + +En tu panel de Cloudflare, selecciona **Edit Code** y agrega el siguiente script al código de tu Worker. Consulta la [documentación de Cloudflare](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) para obtener más información sobre cómo editar un Worker. + + + Reemplaza “[SUBDOMAIN]” por tu subdominio y “[YOUR_DOMAIN]” por la URL base de tu sitio web. + + +```javascript +addEventListener("fetch", (event) => { + event.respondWith(handleRequest(event.request)); +}); + +async function handleRequest(request) { + try { + const urlObject = new URL(request.url); + + // If the request is to a Vercel verification path, allow it to pass through + if (urlObject.pathname.startsWith('/.well-known/')) { + return await fetch(request); + } + + // If the request is to the docs subdirectory + if (/^\/docs/.test(urlObject.pathname)) { + // Then Proxy to Mintlify + const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; + const CUSTOM_URL = "[YOUR_DOMAIN]"; + + let url = new URL(request.url); + url.hostname = DOCS_URL; + + let proxyRequest = new Request(url, request); + + proxyRequest.headers.set("Host", DOCS_URL); + proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); + proxyRequest.headers.set("X-Forwarded-Proto", "https"); + // If deploying to Vercel, preserve client IP + proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP")); + + return await fetch(proxyRequest); + } + } catch (error) { + // If no action found, play the regular request + return await fetch(request); + } +} +``` + +Selecciona **Deploy** y espera a que los cambios se propaguen. + + + +### Prueba tu Worker + +Después de desplegar tu código, prueba tu Worker para asegurarte de que enruta a tu documentación de Mintlify. + +1. Prueba usando la URL de vista previa del Worker: `your-worker.your-subdomain.workers.dev/docs` +2. Verifica que el Worker enrute a tu documentación de Mintlify y a tu sitio web. + +### Agrega un dominio personalizado + +1. En tu [panel de Cloudflare](https://dash.cloudflare.com/), navega a tu Worker. +2. Ve a **Settings > Domains & Routes > Add > Custom Domain**. +3. Agrega tu dominio. + + + Recomendamos agregar tu dominio tanto con como sin el prefijo `www.`. + + +Consulta [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) en la documentación de Cloudflare para obtener más información. + +### Resuelve conflictos de DNS + +Si tu dominio ya apunta a otro servicio, debes eliminar el registro DNS existente. Tu Cloudflare Worker debe estar configurado para controlar todo el tráfico de tu dominio. + +1. Elimina el registro DNS existente de tu dominio. Consulta [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) en la documentación de Cloudflare para obtener más información. +2. Vuelve a tu Worker y agrega tu dominio personalizado. + +## Enrutamiento personalizado en Webflow +Si usas Webflow para alojar tu sitio principal y quieres servir la documentación de Mintlify en `/docs` en el mismo dominio, tendrás que configurar un enrutamiento personalizado mediante Cloudflare Workers para reenviar (proxy) todo el tráfico que no sea de docs a tu sitio principal. + + + Asegúrate de que tu sitio principal esté configurado en una página de destino antes de implementar este Worker, o los visitantes de tu sitio principal verán errores. + + +1. En Webflow, configura una página de destino para tu sitio principal, por ejemplo `landing.yoursite.com`. Esta será la página que verán los visitantes cuando ingresen a tu sitio. +2. Implementa tu sitio principal en la página de destino. Esto garantiza que tu sitio principal siga siendo accesible mientras configuras el Worker. +3. Para evitar conflictos, convierte cualquier URL absoluta de tu sitio principal en relativa. +4. En Cloudflare, selecciona **Edit Code** y agrega el siguiente script en el código de tu Worker. + + Reemplaza `[SUBDOMAIN]` por tu subdominio único, `[YOUR_DOMAIN]` por la URL base de tu sitio web y `[LANDING_DOMAIN]` por la URL de tu página de destino. + + ```javascript + addEventListener("fetch", (event) => { + event.respondWith(handleRequest(event.request)); + }); + async function handleRequest(request) { + try { + const urlObject = new URL(request.url); + + // Si la solicitud es a una ruta de verificación de Vercel, permite que pase + if (urlObject.pathname.startsWith('/.well-known/')) { + return await fetch(request); + } + + // Si la solicitud es al subdirectorio de docs + if (/^\/docs/.test(urlObject.pathname)) { + // Proxy hacia Mintlify + const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; + const CUSTOM_URL = "[YOUR_DOMAIN]"; + let url = new URL(request.url); + url.hostname = DOCS_URL; + let proxyRequest = new Request(url, request); + proxyRequest.headers.set("Host", DOCS_URL); + proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); + proxyRequest.headers.set("X-Forwarded-Proto", "https"); + // Si se implementa en Vercel, conservar la IP del cliente + proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP")); + return await fetch(proxyRequest); + } + // Enrutar todo lo demás al sitio principal + const MAIN_SITE_URL = "[LANDING_DOMAIN]"; + if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") { + let mainSiteUrl = new URL(request.url); + mainSiteUrl.hostname = MAIN_SITE_URL; + return await fetch(mainSiteUrl, { + method: request.method, + headers: request.headers, + body: request.body + }); + } + } catch (error) { + // Si no se encuentra ninguna acción, servir la solicitud normal + return await fetch(request); + } + } + ``` +5. Selecciona **Deploy** y espera a que los cambios se propaguen. + + diff --git a/es/advanced/subpath/route53-cloudfront.mdx b/es/advanced/subpath/route53-cloudfront.mdx new file mode 100644 index 000000000..56ebcd179 --- /dev/null +++ b/es/advanced/subpath/route53-cloudfront.mdx @@ -0,0 +1,211 @@ +--- +title: "AWS Route 53 y CloudFront" +sidebarTitle: "AWS" +description: "Aloja la documentación en el subdirectorio /docs usando servicios de AWS" +--- + +import Propagating from "/snippets/custom-subpath-propagating.mdx"; + +Para alojar tu documentación en la subruta `/docs` con AWS Route 53 y CloudFront, debes configurar tu proveedor de DNS para que apunte a tu distribución de CloudFront. + +## Proxies con implementaciones de Vercel + +Si usas AWS CloudFront como proxy con implementaciones de Vercel, debes configurarlo para que no interfiera con la verificación de dominio de Vercel ni con el aprovisionamiento de certificados SSL. + +Una configuración incorrecta de CloudFront puede impedir que Vercel aprovisione certificados SSL de Let's Encrypt y provocar fallas en la verificación de dominio. + +### Lista de rutas permitidas obligatoria + +CloudFront debe permitir el tráfico a estas rutas específicas sin almacenarlo en caché ni bloquearlo: + +- `/.well-known/acme-challenge/*` - Necesaria para la verificación de certificados de Let's Encrypt +- `/.well-known/vercel/*` - Necesaria para la verificación de dominio de Vercel + +Estas rutas deben configurarse para omitir la caché de CloudFront y pasar directamente al origen. + +### Requisitos de reenvío de encabezados + +Debes crear una política de solicitud al origen personalizada que reenvíe correctamente el encabezado `Host` y la IP del cliente. Esto es fundamental para los procesos de verificación de Vercel. + +1. Crea una política de solicitud al origen personalizada llamada `VercelCloudFrontProxy`. +2. Incluye los encabezados `Origin` y `CloudFront-Viewer-Address`. + +Debes incluir el encabezado `CloudFront-Viewer-Address` en tu configuración de política de solicitud al origen o en los encabezados de la política de caché para reenviar el encabezado al origen. + +## Crear una distribución de CloudFront + +1. Ve a [CloudFront](https://aws.amazon.com/cloudfront) en la consola de AWS. +2. Selecciona **Create distribution**. + + + ![Página de distribuciones de CloudFront con el botón "Create distribution" resaltado.](/images/cloudfront/create-distribution.png) + + +3. En Origin domain, introduce `[SUBDOMAIN].mintlify.dev`, donde `[SUBDOMAIN]` es el subdominio único de tu proyecto. + + + ![Página "Create distribution" de CloudFront mostrando "acme.mintlify.dev" como el dominio de origen.](/images/cloudfront/origin-name.png) + + +4. En "Web Application Firewall (WAF)", habilita las protecciones de seguridad. + + + ![Opciones de Web Application Firewall (WAF) con "Enable security protections" seleccionado.](/images/cloudfront/enable-security-protections.png) + + +5. Deja el resto de la configuración con los valores predeterminados. +6. Selecciona **Create distribution**. + +## Agregar origen predeterminado + +1. Después de crear la distribución, ve a la pestaña "Origins". + + + ![Una distribución de CloudFront con la pestaña "Origins" resaltada.](/images/cloudfront/origins.png) + + +2. Busca la URL de staging que refleje el dominio principal. Esto varía mucho según cómo esté alojada tu página de inicio. Por ejemplo, la URL de staging de Mintlify es [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app). + + + Si tu página de inicio está alojada en Webflow, usa la URL de staging de Webflow. Tendrá el formato `.webflow.io`. + + Si usas Vercel, usa el dominio `.vercel.app` disponible para cada proyecto. + + +3. Crea un nuevo Origin y agrega tu URL de staging como el "Origin domain". + + + ![Página de CloudFront "Create origin" con un campo de entrada "Origin domain" resaltado.](/images/cloudfront/default-origin.png) + + +A estas alturas, deberías tener dos Origins: uno con `[SUBDOMAIN].mintlify.app` y otro con tu URL de staging. + + + ![Página de CloudFront "Origins" con dos orígenes: uno para `mintlify` y otro para `mintlify-landing-page`.](/images/cloudfront/final-origins.png) + + +## Configurar comportamientos + +Los comportamientos en CloudFront permiten controlar la lógica de subrutas. A grandes rasgos, queremos crear la siguiente lógica: + +- **Si un usuario llega a /docs**, ir a `[SUBDOMAIN].mintlify.dev`. +- **Si un usuario llega a cualquier otra página**, ir a la página de destino actual. + +1. Ve a la pestaña "Behaviors" de tu distribución de CloudFront. + + + ![Pestaña "Behaviors" de CloudFront resaltada.](/images/cloudfront/behaviors.png) + + +2. Selecciona el botón **Create behavior** y crea los siguientes comportamientos. + +### `/.well-known/*` + +Crea comportamientos para las rutas de verificación de dominio de Vercel con un **Path pattern** de `/.well-known/*` y establece **Origin and origin groups** en la URL de tu documentación. + +Para "Cache policy", selecciona **CachingDisabled** para asegurarte de que estas solicitudes de verificación pasen sin caché. + + + ![Página "Create behavior" de CloudFront con un "Path pattern" de "/.well-known/*" y "Origin and origin groups" apuntando a la URL de staging.](/images/cloudfront/well-known-policy.png) + + + +Si `.well-known/*` es demasiado genérico, puede reducirse, como mínimo para Vercel, a 2 comportamientos: + - `/.well-known/vercel/*` - Requerido para la verificación de dominio de Vercel + - `/.well-known/acme-challenge/*` - Requerido para la verificación de certificados de Let's Encrypt + + +### `/docs` + +Crea un comportamiento con un **Path pattern** de `/docs` y **Origin and origin groups** apuntando a la URL `.mintlify.dev` (en nuestro caso `acme.mintlify.dev`). + +- Establece "Cache policy" en **CachingOptimized**. +- En "Origin request policy", crea una política de solicitud de origen llamada **VercelCloudFrontProxy** que reenvíe las cabeceras `Origin` y `CloudFront-Viewer-Address`. + + + ![Página de creación de la política de solicitud de origen de CloudFront que reenvía las cabeceras `Origin` y `CloudFront-Viewer-Address`](/images/cloudfront/origin-request-policy.png) + + +- Establece "Viewer protocol policy" en **Redirect HTTP to HTTPS**. + + + ![Página "Create behavior" de CloudFront con un "Path pattern" de "/docs/*" y "Origin and origin groups" apuntando a la URL `acme.mintlify.dev`.](/images/cloudfront/behavior-1.png) + + +### `/docs/*` + +Crea un comportamiento con un **Path pattern** de `/docs/*` y **Origin and origin groups** apuntando a la misma URL `.mintlify.dev`. + +Estas configuraciones deben coincidir exactamente con `/docs`, con la excepción del **Path pattern**. + +- Establece "Cache policy" en **CachingOptimized**. +- Establece "Origin request policy" en **VercelCloudFrontProxy**. +- Establece "Viewer protocol policy" en **Redirect HTTP to HTTPS**. + +### `Default (*)` + +Por último, vamos a editar el comportamiento `Default (*)`. + + + ![Una distribución de CloudFront con el comportamiento "Default (*)" seleccionado y el botón Edit enfatizado.](/images/cloudfront/default-behavior-1.png) + + +1. Cambia **Origin and origin groups** del comportamiento predeterminado a la URL de staging (en nuestro caso `mintlify-landing-page.vercel.app`). + + + ![Página "Edit behavior" de CloudFront con el campo de entrada "Origin and origin groups" resaltado.](/images/cloudfront/default-behavior-2.png) + + +2. Selecciona **Save changes**. + +### Verifica que los comportamientos estén configurados correctamente + +Si sigues los pasos anteriores, tus comportamientos deberían verse así: + + + ![Página "Behaviors" de CloudFront con 4 comportamientos: `/docs/*`, `/docs`, `Default`, y `/.well-known/*`.](/images/cloudfront/all-behaviors.png) + + +## Vista previa de la distribución + +Ahora puedes comprobar si tu distribución está configurada correctamente yendo a la pestaña "General" y visitando la URL de **Distribution domain name**. + + + ![Pestaña "General" de CloudFront con la URL "Distribution domain name" resaltada.](/images/cloudfront/preview-distribution.png) + + +Todas las páginas deberían redirigirse a tu página de inicio principal, pero si añades `/docs` a la URL, deberías ver que te lleva a tu instancia de documentación de Mintlify. + +## Conectar con Route 53 + +Ahora llevaremos la funcionalidad de la distribución de CloudFront a tu dominio principal. + + + Para esta sección, también puedes consultar la guía oficial de AWS sobre [Configurar + Amazon Route 53 para enrutar el tráfico a una + distribución de CloudFront](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config) + + +1. Ve a [Route 53](https://aws.amazon.com/route53) desde la consola de AWS. +2. Entra en la “Hosted zone” de tu dominio principal. +3. Selecciona **Create record**. + + + ![Página “Records” de Route 53 con el botón “Create record” resaltado.](/images/cloudfront/route53-create-record.png) + + +4. Activa `Alias` y luego, en **Route traffic to**, elige la opción `Alias to CloudFront distribution`. + + + ![Página “Create record” de Route 53 con el interruptor “Alias” y el menú “Route traffic to” resaltados.](/images/cloudfront/create-record-alias.png) + + +5. Selecciona **Create records**. + + + Es posible que debas eliminar el registro A existente si ya hay uno. + + +Tu documentación ahora está disponible en `/docs` de tu dominio principal. + + diff --git a/es/advanced/subpath/vercel.mdx b/es/advanced/subpath/vercel.mdx new file mode 100644 index 000000000..b7a0b7103 --- /dev/null +++ b/es/advanced/subpath/vercel.mdx @@ -0,0 +1,66 @@ +--- +title: "Vercel" +description: "Aloja la documentación en la subruta /docs con Vercel" +--- + +## archivo vercel.json + +El archivo `vercel.json` es el archivo de configuración de Vercel que te permite personalizar cómo se compila y se despliega tu proyecto. Se encuentra en el directorio raíz de tu proyecto y controla varios aspectos del despliegue, incluidos el enrutamiento, las redirecciones, los encabezados y la configuración de compilación. + +Usamos la propiedad `rewrites` para enrutar mediante proxy las solicitudes desde tu dominio principal hacia tu documentación. + +Los rewrites te permiten asignar solicitudes entrantes a distintos destinos sin cambiar la URL en el navegador. Cuando alguien visita `yoursite.com/docs`, Vercel recuperará internamente el contenido de `your-subdomain.mintlify.dev/docs`, pero el usuario seguirá viendo `yoursite.com/docs` en su navegador. Esto es diferente de las redirecciones, que enviarían a los usuarios a una URL completamente distinta. + +## Configuración + +Para alojar tu documentación en una subruta personalizada `/docs` con Vercel, agrega la siguiente configuración a tu archivo `vercel.json`: + +```json +{ + "rewrites": [ + { + "source": "/docs", + "destination": "https://[subdomain].mintlify.dev/docs" + }, + { + "source": "/docs/:match*", + "destination": "https://[subdomain].mintlify.dev/docs/:match*" + } + ] +} +``` + +- **`source`**: El patrón de ruta en tu dominio que activa la reescritura. +- **`destination`**: El destino al que se debe enrutar la solicitud mediante proxy. +- **`:match*`**: Un comodín que captura cualquier segmento de ruta después de `/docs/`. + +Para obtener más información, consulta [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) en la documentación de Vercel. + +## Uso de proxies externos con Vercel + +Si estás usando un proxy externo (como Cloudflare o AWS CloudFront) delante de tu despliegue de Vercel, debes configurarlo correctamente para evitar conflictos con la verificación de dominio de Vercel y el aprovisionamiento de certificados SSL. + +Una configuración incorrecta del proxy puede impedir que Vercel aprovisione certificados SSL de Let's Encrypt y provocar fallos en la verificación de dominio. + +Consulta los [proveedores compatibles](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) en la documentación de Vercel. + +### Lista obligatoria de rutas permitidas + +Tu proxy externo debe permitir el tráfico a estas rutas específicas sin bloquear, redirigir ni aplicar caché de forma agresiva: + +- `/.well-known/acme-challenge/*` - Requerida para la verificación de certificados de Let's Encrypt +- `/.well-known/vercel/*` - Requerida para la verificación de dominio de Vercel + +Estas rutas deben pasar directamente a tu despliegue de Vercel sin modificación. + +### Requisitos de reenvío de encabezados + +Asegúrate de que tu proxy reenvíe correctamente el encabezado `HOST`. Sin un reenvío adecuado del encabezado, las solicitudes de verificación fallarán. + +### Pruebas de tu configuración de proxy + +Para verificar que tu proxy esté configurado correctamente: + +1. Comprueba que `https://[yourdomain].com/.well-known/vercel/` devuelva una respuesta. +2. Asegúrate de que los certificados SSL se estén aprovisionando correctamente en tu panel de Vercel. +3. Verifica que la verificación de dominio se complete correctamente. diff --git a/es/ai/contextual-menu.mdx b/es/ai/contextual-menu.mdx new file mode 100644 index 000000000..280180244 --- /dev/null +++ b/es/ai/contextual-menu.mdx @@ -0,0 +1,148 @@ +--- +title: "Menú contextual" +description: "Agrega integraciones de IA con un clic a tu documentación" +icon: "square-menu" +--- + +import { PreviewButton } from "/snippets/previewbutton.jsx" +import IconsRequired from "/snippets/icons-required.mdx"; + +El menú contextual ofrece acceso rápido a contenido optimizado para IA e integraciones directas con herramientas de IA populares. Cuando los usuarios abren el menú contextual en cualquier página, pueden copiar contenido como contexto para herramientas de IA o iniciar conversaciones en ChatGPT, Claude, Perplexity o una herramienta personalizada de tu elección, con tu documentación ya cargada como contexto. + +## Opciones del menú + +El menú contextual incluye varias opciones preconfiguradas que puedes habilitar añadiendo su identificador a tu configuración. + +| Opción | Identificador | Descripción | +|:--------|:------------|:-------------| +| **Copiar página** | `copy` | Copia la página actual como Markdown para pegarla como contexto en herramientas de IA | +| **Ver como Markdown** | `view` | Abre la página actual como Markdown | +| **Abrir en ChatGPT** | `chatgpt` | Crea una conversación en ChatGPT con la página actual como contexto | +| **Abrir en Claude** | `claude` | Crea una conversación en Claude con la página actual como contexto | +| **Abrir en Perplexity** | `perplexity` | Crea una conversación en Perplexity con la página actual como contexto | +| **Copiar URL del servidor MCP** | `mcp` | Copia la URL de tu servidor MCP al portapapeles | +| **Conectar con Cursor** | `cursor` | Instala tu servidor MCP alojado en Cursor | +| **Conectar con VS Code** | `vscode` | Instala tu servidor MCP alojado en VS Code | + + + El menú contextual desplegado muestra las opciones Copiar página, Ver como Markdown, Abrir en ChatGPT y Abrir en Claude. + + +## Habilitar el menú contextual + +Añade el campo `contextual` a tu archivo `docs.json` y especifica qué opciones quieres incluir. + +```json +{ + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] + } +} +``` + +## Agregar opciones personalizadas + +Crea opciones personalizadas en el menú contextual agregando un objeto al arreglo `options`. Cada opción personalizada requiere estas propiedades: + + + El título de la opción. + + + + La descripción de la opción. Se muestra debajo del título cuando se expande el menú contextual. + + + + + + El href de la opción. Usa una cadena para enlaces simples o un objeto para enlaces dinámicos con parámetros de consulta. + + + + La URL base de la opción. + + + + Los parámetros de consulta de la opción. + + + + La clave del parámetro de consulta. + + + + El valor del parámetro de consulta. Reemplazaremos los siguientes marcadores por los valores correspondientes: + - Usa `$page` para insertar el contenido de la página actual en Markdown. + - Usa `$path` para insertar la ruta de la página actual. + - Usa `$mcp` para insertar la URL del servidor MCP alojado. + + + + + + +Ejemplo de opción personalizada: + +```json {9-14} wrap +{ + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + { + "title": "Request a feature", + "description": "Join the discussion on GitHub to request a new feature", + "icon": "plus", + "href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests" + } + ] + } +} +``` + +### Ejemplos de opciones personalizadas + + + +```json +{ + "title": "Request a feature", + "description": "Join the discussion on GitHub", + "icon": "plus", + "href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests" +} +``` + + + +```json +{ + "title": "Share on X", + "description": "Share this page on X", + "icon": "x", + "href": { + "base": "https://x.com/intent/tweet", + "query": { + "key": "text", + "value": "Check out this documentation: $page" + } + } +} +``` + + \ No newline at end of file diff --git a/es/ai/llmstxt.mdx b/es/ai/llmstxt.mdx new file mode 100644 index 000000000..d265e7f14 --- /dev/null +++ b/es/ai/llmstxt.mdx @@ -0,0 +1,49 @@ +--- +title: "llms.txt" +description: "Facilita que las LLM lean e indexen tu contenido" +icon: "file-code" +--- + +import { PreviewButton } from "/snippets/previewbutton.jsx" + +El [archivo llms.txt](https://llmstxt.org) es un estándar del sector que ayuda a las LLM a indexar contenido de forma más eficiente, similar a cómo un sitemap ayuda a los motores de búsqueda. Las herramientas de IA pueden usar este archivo para comprender la estructura de tu documentación y encontrar contenido relevante para las consultas de los usuarios. + +Mintlify aloja automáticamente un archivo `llms.txt` en la raíz de tu proyecto que enumera todas las páginas disponibles de tu documentación. Este archivo siempre está actualizado y no requiere mantenimiento. Opcionalmente, puedes agregar un archivo `llms.txt` personalizado en la raíz de tu proyecto. + +Consulta tu `llms.txt` añadiendo `/llms.txt` a la URL de tu sitio de documentación. + +Abrir el llms.txt de este sitio. + +## Estructura de llms.txt + +Un archivo `llms.txt` es un archivo Markdown simple que contiene: + +- **Título del sitio** como encabezado H1. +- **Secciones de contenido estructuradas** con enlaces y una descripción de cada página de tu documentación. + +```mdx Example llms.txt +# Example product docs + +## Guides +- [Getting started](https://example.com/docs/start): Intro guide +- [Install](https://example.com/docs/install): Setup steps + +## Reference +- [API](https://example.com/docs/api): Endpoint list and usage +``` + +Este enfoque estructurado permite que los LLM procesen tu documentación de forma eficiente a un nivel general y localicen contenido relevante para las consultas de los usuarios, mejorando la precisión y la velocidad de las búsquedas de documentación asistidas por IA. + +## llms-full.txt + +El archivo `llms-full.txt` combina todo tu sitio de documentación en un solo archivo como contexto para herramientas de IA y es indexado por el tráfico de los LLM. + +Mintlify aloja automáticamente un archivo `llms-full.txt` en la raíz de tu proyecto. Puedes ver tu `llms-full.txt` agregando `/llms-full.txt` a la URL de tu sitio de documentación. + +Abrir el llms-full.txt de este sitio. + +## Archivos personalizados + +Para agregar un `llms.txt` o `llms-full.txt` personalizado, crea un archivo `llms.txt` o `llms-full.txt` en la raíz de tu proyecto. Al agregar un archivo personalizado, se sobrescribirá el archivo generado automáticamente con el mismo nombre. Si eliminas el archivo personalizado, se volverá a usar el archivo predeterminado. + +Tu archivo `llms.txt` o `llms-full.txt` personalizado debe incluir el título del sitio como encabezado H1. El resto del contenido es opcional. Consulta [Format](https://llmstxt.org/#format) en la especificación de `llms.txt` para más información sobre secciones opcionales y buenas prácticas. diff --git a/es/ai/markdown-export.mdx b/es/ai/markdown-export.mdx new file mode 100644 index 000000000..1e39c2617 --- /dev/null +++ b/es/ai/markdown-export.mdx @@ -0,0 +1,21 @@ +--- +title: "Exportación de Markdown" +description: "Obtén rápidamente versiones en Markdown de las páginas" +icon: "file-text" +--- + +import { PreviewButton } from "/snippets/previewbutton.jsx" + +Markdown proporciona texto estructurado que las herramientas de IA pueden procesar de forma más eficiente que HTML, lo que se traduce en mayor precisión en las respuestas, tiempos de procesamiento más rápidos y un menor consumo de tokens. + +Mintlify genera automáticamente versiones en Markdown de las páginas, optimizadas para herramientas de IA e integraciones externas. + +## Extensión .md en la URL + +Agrega `.md` a la URL de cualquier página para ver una versión en Markdown. + +Abrir esta página en Markdown + +## Atajo de teclado + +Pulsa Command + C (Ctrl + C en Windows) para copiar una página en Markdown al portapapeles. diff --git a/es/ai/model-context-protocol.mdx b/es/ai/model-context-protocol.mdx new file mode 100644 index 000000000..61d671b6d --- /dev/null +++ b/es/ai/model-context-protocol.mdx @@ -0,0 +1,376 @@ +--- +title: "Protocolo de Contexto de Modelo" +description: "Permite que los usuarios accedan a tu documentación y API desde sus herramientas de IA favoritas" +icon: "audio-waveform" +keywords: ["mcp"] +--- + +import { PreviewButton } from "/snippets/previewbutton.jsx" + +## Acerca de los servidores MCP + +El MCP (Protocolo de Contexto de Modelo) es un protocolo abierto que crea conexiones estandarizadas entre aplicaciones de IA y servicios externos, como la documentación. Mintlify genera un servidor MCP a partir de tu documentación y especificaciones de OpenAPI, preparando tu contenido para el ecosistema de IA en general, donde cualquier cliente MCP (como Claude, Cursor, Goose y otros) puede conectarse a tu documentación y a tus API. + +Tu servidor MCP expone herramientas para que las aplicaciones de IA busquen en tu documentación e interactúen con tus API. + +## Acceder a tu servidor MCP + + + Los servidores MCP solo pueden generarse para documentación pública. No es posible acceder a documentación protegida por autenticación de usuario final para generar el servidor. + + +Tu servidor MCP se genera automáticamente y se aloja en la URL de tu documentación con la ruta `/mcp`. Por ejemplo, el servidor MCP de Mintlify está disponible en `https://mintlify.com/docs/mcp`. + +Puedes ver y copiar la URL de tu servidor MCP en tu [panel](https://dashboard.mintlify.com/products/mcp). + +## Configurar tu servidor MCP + +Todos los servidores MCP incluyen la herramienta `search` de forma predeterminada, lo que permite a los usuarios consultar información de tu documentación desde otras herramientas. + +Si tienes un [plan Pro o Enterprise](https://mintlify.com/pricing?ref=mcp), puedes exponer endpoints de tu especificación OpenAPI como herramientas MCP. + +Para exponer endpoints como herramientas MCP, utiliza el objeto `mcp` dentro de la extensión `x-mint`, ya sea a nivel de archivo o de endpoint. Por ejemplo, el servidor MCP de Mintlify incluye herramientas para crear chats del Asistente, obtener actualizaciones de estado y activar actualizaciones. + +Los servidores MCP siguen un enfoque de seguridad como prioridad, donde los endpoints de API no se exponen de forma predeterminada. Debes habilitar explícitamente los endpoints para ponerlos a disposición como herramientas MCP. Expón únicamente endpoints que sean seguros para el acceso público a través de herramientas de IA. + + + La configuración de MCP para el endpoint. + + + + Indica si se debe exponer el endpoint como una herramienta MCP. Tiene prioridad sobre la configuración a nivel de archivo. + + + + El nombre de la herramienta MCP. + + + + La descripción de la herramienta MCP. + + + + +### Configuración a nivel de archivo + +Habilita MCP para todos los endpoints de forma predeterminada en un archivo de especificación OpenAPI y excluye selectivamente endpoints: + +```json +{ + "openapi": "3.1.0", + "x-mint": { + "mcp": { + "enabled": true + } + }, + // ... + "paths": { + "/api/v1/users": { + "get": { + "x-mint": { + "mcp": { + "enabled": false // Desactiva MCP para este endpoint + } + }, + // ... + } + } + } +} +``` + +### Configuración a nivel de endpoint + +Habilita MCP para endpoints específicos: + +```json +{ + "paths": { + "/api/v1/users": { + "get": { + "x-mint": { + "mcp": { + "enabled": true, + "name": "get-users", + "description": "Obtener una lista de usuarios" + }, + // ... + } + } + }, + "/api/v1/delete": { + "delete": { + // Sin `x-mint: mcp`, este endpoint no se expone como herramienta MCP + // ... + } + } + } +} +``` + +## Uso de tu servidor MCP + +Tus usuarios deben conectar tu servidor MCP a sus herramientas de IA preferidas. + +1. Haz que la URL de tu servidor MCP sea de acceso público. +2. Los usuarios copian la URL de tu servidor MCP y la añaden a sus herramientas. +3. Los usuarios acceden a tu documentación y a los endpoints de la API desde sus herramientas. + +Estas son algunas maneras en que puedes ayudar a tus usuarios a conectarse a tu servidor MCP: + + + + Agrega opciones en el [menú contextual](/es/ai/contextual-menu) para que tus usuarios se conecten a tu servidor MCP desde cualquier página de tu documentación. + + | Opción | Identificador | Descripción | + | :----- | :------------ | :---------- | + | **Copiar URL del servidor MCP** | `mcp` | Copia la URL de tu servidor MCP al portapapeles del usuario. | + | **Conectar con Cursor** | `cursor` | Instala tu servidor MCP en Cursor. | + | **Conectar con VS Code** | `vscode` | Instala tu servidor MCP en VS Code. | + + + + + + Ve a tu [panel](https://dashboard.mintlify.com/products/mcp) y busca la URL de tu servidor MCP. + + + + Crea una guía para tus usuarios que incluya la URL de tu servidor MCP y los pasos para conectarlo a Claude. + + 1. Ve a la página [Connectors](https://claude.ai/settings/connectors) en la configuración de Claude. + 2. Selecciona **Add custom connector**. + 3. Agrega el nombre y la URL de tu servidor MCP. + 4. Selecciona **Add**. + 5. Al usar Claude, selecciona el botón de adjuntos (el ícono de suma). + 6. Selecciona tu servidor MCP. + + + + Consulta la [documentación de Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) para más detalles. + + + + + + Ve a tu [panel](https://dashboard.mintlify.com/products/mcp) y busca la URL de tu servidor MCP. + + + + Crea una guía para tus usuarios que incluya la URL de tu servidor MCP y el comando para conectarlo a Claude Code. + + ```bash + claude mcp add --transport http + ``` + + + + Consulta la [documentación de Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) para más detalles. + + + + + + Ve a tu [panel](https://dashboard.mintlify.com/products/mcp) y busca la URL de tu servidor MCP. + + + + Crea una guía para tus usuarios que incluya la URL de tu servidor MCP y los pasos para conectarlo a Cursor. + + 1. Usa Command + Shift + P (Ctrl + Shift + P en Windows) para abrir la paleta de comandos. + 2. Busca "Open MCP settings". + 3. Selecciona **Add custom MCP**. Esto abrirá el archivo `mcp.json`. + 4. En `mcp.json`, configura tu servidor: + + ```json + { + "mcpServers": { + "": { + "url": "" + } + } + } + ``` + + + + Consulta la [documentación de Cursor](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) para más detalles. + + + + + + Ve a tu [panel](https://dashboard.mintlify.com/products/mcp) y busca la URL de tu servidor MCP. + + + + Crea una guía para tus usuarios que incluya la URL de tu servidor MCP y los pasos para conectarlo a VS Code. + + 1. Crea un archivo `.vscode/mcp.json`. + 2. En `mcp.json`, configura tu servidor: + + ```json + { + "servers": { + "": { + "type": "http", + "url": "" + } + } + } + ``` + + + + Consulta la [documentación de VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) para más detalles. + + + +### Ejemplo: Conectarte al servidor MCP de Mintlify + +Conéctate al servidor MCP de Mintlify para interactuar con la API de Mintlify y buscar en nuestra documentación. Esto te dará respuestas más precisas sobre cómo usar Mintlify en tu entorno local y muestra cómo puedes ayudar a tus usuarios a conectarse a tu servidor MCP. + + + + En la parte superior de esta página, selecciona el menú contextual y elige **Connect to Cursor** o **Connect to VS Code** para conectar el servidor MCP de Mintlify al IDE de tu preferencia. + + + + Para usar el servidor MCP de Mintlify con Claude: + + + + 1. Ve a la página de [Connectors](https://claude.ai/settings/connectors) en la configuración de Claude. + 2. Selecciona **Add custom connector**. + 3. Agrega el servidor MCP de Mintlify: + + - Name: `Mintlify` + - URL: `https://mintlify.com/docs/mcp` + + 4. Selecciona **Add**. + + + + 1. Al usar Claude, selecciona el botón de adjuntos (el ícono de “+”). + 2. Selecciona el servidor MCP de Mintlify. + 3. Hazle a Claude una pregunta sobre Mintlify. + + + + Consulta la [documentación de Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) para más detalles. + + + + Para usar el servidor MCP de Mintlify con Claude Code, ejecuta el siguiente comando: + + ```bash + claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp + ``` + + Prueba la conexión ejecutando: + + ```bash + claude mcp list + ``` + + Consulta la [documentación de Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) para más detalles. + + + + Install in Cursor + + Para conectar el servidor MCP de Mintlify a Cursor, haz clic en el botón **Install in Cursor**. O, para conectar el servidor MCP manualmente, sigue estos pasos: + + + + 1. Usa Command + Shift + P (Ctrl + Shift + P en Windows) para abrir la paleta de comandos. + 2. Busca "Open MCP settings". + 3. Selecciona **Add custom MCP**. Esto abrirá el archivo `mcp.json`. + + + + En `mcp.json`, agrega: + + ```json + { + "mcpServers": { + "Mintlify": { + "url": "https://mintlify.com/docs/mcp" + } + } + } + ``` + + + + En el chat de Cursor, pregunta “What tools do you have available?” Cursor debería mostrar el servidor MCP de Mintlify como una herramienta disponible. + + + + Consulta [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) en la documentación de Cursor para más detalles. + + + + Install in VS Code + + Para conectar el servidor MCP de Mintlify a VS Code, haz clic en el botón **Install in VS Code**. O, para conectarlo manualmente, crea un archivo `.vscode/mcp.json` y agrega: + + ```json + { + "servers": { + "Mintlify": { + "type": "http", + "url": "https://mintlify.com/docs/mcp" + } + } + } + ``` + + Consulta la [documentación de VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) para más detalles. + + + +## Autenticación + +Cuando habilitas un endpoint de API para MCP, el servidor incluye los requisitos de autenticación definidos en los `securitySchemes` y `securityRequirement` de tu OpenAPI. Cualquier clave la gestiona directamente la herramienta y no es almacenada ni procesada por Mintlify. + +Si un usuario le pide a su herramienta de IA que llame a un endpoint protegido, la herramienta solicitará en ese momento al usuario las credenciales de autenticación necesarias. + +## Supervisión de tu servidor MCP + +Puedes ver todas las herramientas de MCP disponibles en la sección **Available tools** de la [página del servidor MCP](https://dashboard.mintlify.com/products/mcp) en tu panel. + + + Panel de MCP con la sección Available tools destacada + + + + +## Solución de problemas + + + + Si tu servidor MCP solo expone la herramienta de búsqueda a pesar de tener una especificación OpenAPI: + + 1. Verifica que tu especificación OpenAPI sea válida y accesible. + 2. Asegúrate de habilitar explícitamente MCP para endpoints específicos con `x-mint.mcp.enabled: true`. + 3. Revisa los registros de tu implementación en busca de errores al procesar OpenAPI. + + Si falla el procesamiento de OpenAPI, el servidor continúa únicamente con la herramienta de búsqueda para mantener la funcionalidad. + + + + Si los usuarios reportan problemas de autenticación: + + 1. Comprueba que tu especificación OpenAPI incluya definiciones correctas de `securitySchemes`. + 2. Confirma que los endpoints habilitados funcionen con los métodos de autenticación especificados. + + + + Si las herramientas de IA no están usando tus endpoints de API de forma eficaz: + + 1. Agrega campos `summary` y `description` detallados a tus endpoints. + 2. Asegúrate de que los nombres y descripciones de los parámetros sean autoexplicativos. + 3. Usa el panel de MCP para verificar cómo se muestran tus endpoints como herramientas. + + diff --git a/es/ai/slack-app.mdx b/es/ai/slack-app.mdx new file mode 100644 index 000000000..c39a9ee32 --- /dev/null +++ b/es/ai/slack-app.mdx @@ -0,0 +1,27 @@ +--- +title: "Slack app" +description: "Agrega un bot que busca en tu documentación para responder preguntas en tu espacio de trabajo de Slack" +icon: "slack" +--- + + + La aplicación de Slack está disponible para los [planes Pro y Enterprise](https://mintlify.com/pricing?ref=slack-app). + + +La aplicación de Slack agrega un bot llamado `@mintlify` a tu espacio de trabajo de Slack que puede buscar en tu documentación y responder las preguntas de los usuarios. El bot responde a mensajes directos, menciones con @ y a cualquier pregunta en un canal llamado específicamente `#ask-ai`. + +La aplicación de Slack puede generar costos: ya sea usando tus créditos del Asistente de IA o incurriendo en cargos por excedente. + +## Configurar la aplicación de Slack + + + Si el propietario del espacio de trabajo de Slack requiere aprobación de administración para instalar aplicaciones, pídele que apruebe la aplicación de Slack de Mintlify antes de añadirla. + + +1. Ve a la página de [Complementos](https://dashboard.mintlify.com/products/addons) de tu panel. +2. Selecciona **Conectar** en la tarjeta de Integración de Slack. +3. Sigue las indicaciones de Slack para añadir la aplicación a tu espacio de trabajo. +4. Verifica que el bot funciona y responde cuando: + - Envías un mensaje directo a la aplicación de Mintlify. + - Mencionas al bot con `@mintlify` en un canal. + - Creas un canal `#ask-ai`, añades el bot y haces una pregunta. diff --git a/es/api-playground/asyncapi/playground.mdx b/es/api-playground/asyncapi/playground.mdx new file mode 100644 index 000000000..f287bb9e5 --- /dev/null +++ b/es/api-playground/asyncapi/playground.mdx @@ -0,0 +1,5 @@ +--- +title: "Área de pruebas" +description: "Permite que los usuarios interactúen con tus websockets" +asyncapi: "/asyncapi.yaml channelOne" +--- diff --git a/es/api-playground/asyncapi/setup.mdx b/es/api-playground/asyncapi/setup.mdx new file mode 100644 index 000000000..a640066d3 --- /dev/null +++ b/es/api-playground/asyncapi/setup.mdx @@ -0,0 +1,83 @@ +--- +title: "Configuración de AsyncAPI" +description: "Crea páginas de referencia de WebSocket con AsyncAPI" +--- + +## Añadir un archivo de especificación de AsyncAPI + +Para empezar a crear páginas para tus websockets, asegúrate de contar con un documento de esquema de AsyncAPI válido en formato JSON o YAML que cumpla con la [especificación de AsyncAPI](https://www.asyncapi.com/docs/reference/specification/v3.0.0). Tu esquema debe ajustarse a la especificación de AsyncAPI 3.0+. + + + Para comprobar que tu esquema de AsyncAPI sea válido, puedes pegarlo en + [AsyncAPI Studio](https://studio.asyncapi.com/) + + +## Autogenerar páginas de websockets + +Puedes agregar un campo `asyncapi` a cualquier pestaña o grupo en la navegación de tu `docs.json`. Este campo puede contener la ruta a un documento de esquema de AsyncAPI en tu repositorio de documentación, la URL de un documento de esquema de AsyncAPI alojado o un arreglo de enlaces a documentos de esquema de AsyncAPI. Mintlify generará automáticamente una página para cada canal de websocket de AsyncAPI. + +**Ejemplos con pestañas:** + + + +```json Local File {5} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "asyncapi": "/path/to/asyncapi.json" + } + ] +} + +``` + +```json Remote URL {5} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml" + } + ] +} +``` + + + +**Ejemplos con grupos:** + +```json {8-11} +"navigation": { + "tabs": [ + { + "tab": "AsyncAPI", + "groups": [ + { + "group": "Websockets", + "asyncapi": { + "source": "/path/to/asyncapi.json", + "directory": "api-reference" + } + } + ] + } + ] +} +``` + + + El campo directory es opcional. Si no se especifica, los archivos se colocarán en + la carpeta **api-reference** del repositorio de documentación. + + +## Página de canal + +Si quieres tener más control sobre el orden de tus canales o simplemente hacer referencia a un canal específico, puedes crear un archivo MDX con el campo `asyncapi` en el frontmatter. + +```mdx +--- +title: "Canal WebSocket" +asyncapi: "/path/to/asyncapi.json channelName" +--- +``` diff --git a/es/api-playground/customization/adding-sdk-examples.mdx b/es/api-playground/customization/adding-sdk-examples.mdx new file mode 100644 index 000000000..c82b97333 --- /dev/null +++ b/es/api-playground/customization/adding-sdk-examples.mdx @@ -0,0 +1,49 @@ +--- +title: "Agregar ejemplos de SDK" +description: "Muestra fragmentos de código por lenguaje junto a tus endpoints de API para mostrar a los desarrolladores cómo usar tus SDK" +--- + +Si tus usuarios interactúan con tu API mediante un SDK en lugar de hacerlo directamente a través de una solicitud de red, puedes usar la extensión `x-codeSamples` para agregar fragmentos de código a tu documento de OpenAPI y mostrarlos en tus páginas de OpenAPI. + +Esta propiedad se puede agregar a cualquier método de solicitud y tiene el siguiente esquema. + + + El lenguaje del fragmento de código. + + + + La etiqueta del ejemplo. Es útil cuando se proporcionan varios ejemplos para un único endpoint. + + + + El código fuente del ejemplo. + + +Aquí tienes un ejemplo de fragmentos de código para una app de seguimiento de plantas, que cuenta tanto con una herramienta de línea de comandos en Bash como con un SDK de JavaScript. + +```yaml +paths: + /plants: + get: + # ... + x-codeSamples: + - lang: bash + label: List all unwatered plants + source: | + planter list -u + - lang: javascript + label: List all unwatered plants + source: | + const planter = require('planter'); + planter.list({ unwatered: true }); + - lang: bash + label: List all potted plants + source: | + planter list -p + - lang: javascript + label: List all potted plants + source: | + const planter = require('planter'); + planter.list({ potted: true }); +``` + diff --git a/es/api-playground/customization/complex-data-types.mdx b/es/api-playground/customization/complex-data-types.mdx new file mode 100644 index 000000000..1a370c780 --- /dev/null +++ b/es/api-playground/customization/complex-data-types.mdx @@ -0,0 +1,95 @@ +--- +title: "Tipos de datos complejos" +description: "Describe APIs con esquemas flexibles, propiedades opcionales y múltiples formatos de datos usando las palabras clave `oneOf`, `anyOf` y `allOf`" +--- + +Cuando tu API admite múltiples formatos de datos, tiene campos condicionales o utiliza patrones de herencia, las palabras clave de composición de esquemas de OpenAPI te ayudan a documentar estas estructuras flexibles. Con `oneOf`, `anyOf` y `allOf`, puedes describir APIs que manejan distintos tipos de entrada o combinan múltiples esquemas en modelos de datos completos. + +## Palabras clave `oneOf`, `anyOf`, `allOf` + +Para tipos de datos complejos, OpenAPI proporciona palabras clave para combinar esquemas: + +- `allOf`: Combina varios esquemas (como fusionar objetos o extender un esquema base). Funciona como un operador lógico `and`. +- `anyOf`: Acepta datos que coincidan con cualquiera de los esquemas proporcionados. Funciona como un operador lógico `or`. +- `oneOf`: Acepta datos que coincidan exactamente con uno de los esquemas proporcionados. Funciona como un operador lógico `xor` (o exclusivo). + +Mintlify trata `oneOf` y `anyOf` de forma idéntica, ya que la diferencia práctica rara vez afecta el uso de la API. + +Para especificaciones detalladas de estas palabras clave, consulta la [documentación de OpenAPI](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/). + +La palabra clave `not` no es compatible por el momento. + +### Combinación de esquemas con `allOf` + +Cuando usas `allOf`, Mintlify realiza un preprocesamiento en tu documento de OpenAPI para mostrar combinaciones complejas de forma legible. Por ejemplo, cuando combinas dos esquemas de objeto con `allOf`, Mintlify fusiona las propiedades de ambos en un único objeto. Esto resulta especialmente útil al aprovechar los [componentes](https://swagger.io/docs/specification/components/) reutilizables de OpenAPI. + +```yaml +org_with_users: + allOf: + - $ref: '#/components/schemas/Org' + - type: object + properties: + users: + type: array + description: An array containing all users in the organization +# ... +components: + schemas: + Org: + type: object + properties: + id: + type: string + description: The ID of the organization +``` + + + + + El ID de la organización + + + Un arreglo que contiene a todos los usuarios de la organización + + + + +### Proporcionar opciones con `oneOf` y `anyOf` + +Cuando usas `oneOf` o `anyOf`, las opciones se muestran en un contenedor con pestañas. Especifica un campo `title` en cada subesquema para dar nombre a tus opciones. Por ejemplo, así podrías mostrar dos tipos diferentes de direcciones de entrega: + +```yaml +delivery_address: + oneOf: + - title: StreetAddress + type: object + properties: + address_line_1: + type: string + description: The street address of the recipient + # ... + - title: POBox + type: object + properties: + box_number: + type: string + description: The number of the PO Box + # ... +``` + + +
+ + + + La dirección de la calle de la residencia + + + + + El número del apartado postal + + + +
+ diff --git a/es/api-playground/customization/managing-page-visibility.mdx b/es/api-playground/customization/managing-page-visibility.mdx new file mode 100644 index 000000000..0fe511eaf --- /dev/null +++ b/es/api-playground/customization/managing-page-visibility.mdx @@ -0,0 +1,85 @@ +--- +title: "Gestionar la visibilidad de páginas" +description: "Controla qué endpoints de tu especificación OpenAPI aparecen en la navegación de tu documentación" +--- + +Puedes controlar qué operaciones de OpenAPI se publican como páginas de documentación y su visibilidad en la navegación. Esto es útil para endpoints internos, operaciones obsoletas, funciones beta o endpoints que deberían ser accesibles mediante URL directa pero no visibles en la navegación del sitio. + +Si tus páginas se generan automáticamente a partir de un documento de OpenAPI, puedes gestionar la visibilidad de las páginas con las extensiones `x-hidden` y `x-excluded`. + +## `x-hidden` + +La extensión `x-hidden` crea una página para un endpoint, pero la oculta de la navegación. La página solo es accesible si se accede directamente a su URL. + +Los casos de uso comunes de `x-hidden` son: + +- Endpoints que quieres documentar, pero no destacar. +- Páginas a las que enlazarás desde otros contenidos. +- Endpoints para usuarios específicos. + +## `x-excluded` + + +La extensión `x-excluded` excluye por completo un endpoint de tu documentación. + +Los casos de uso habituales de `x-excluded` incluyen: + +- Endpoints internos. +- Endpoints obsoletos que no quieres documentar. +- Funcionalidades beta que aún no están listas para la documentación pública. + +## Implementación + +Agrega la extensión `x-hidden` o `x-excluded` debajo del método HTTP en tu especificación de OpenAPI. + +A continuación se muestran ejemplos de cómo usar cada propiedad en un documento de esquema de OpenAPI para un endpoint y una ruta de webhook. + +```json {11, 19} +"paths": { + "/plants": { + "get": { + "description": "Devuelve todas las plantas de la tienda", + "parameters": { /*...*/ }, + "responses": { /*...*/ } + } + }, + "/hidden_plants": { + "get": { + "x-hidden": true, + "description": "Devuelve todas las plantas algo secretas de la tienda", + "parameters": { /*...*/ }, + "responses": { /*...*/ } + } + }, + "/secret_plants": { + "get": { + "x-excluded": true, + "description": "Devuelve todas las plantas altamente secretas de la tienda (¡no publiques este endpoint!)", + "parameters": { /*...*/ }, + "responses": { /*...*/ } + } + } +}, +``` + +```json {9, 15} +"webhooks": { + "/plants_hook": { + "post": { + "description": "Webhook con información sobre una nueva planta añadida a la tienda", + } + }, + "/hidden_plants_hook": { + "post": { + "x-hidden": true, + "description": "Webhook con información algo secreta sobre una nueva planta añadida a la tienda" + } + }, + "/secret_plants_hook": { + "post": { + "x-excluded": true, + "description": "Webhook con información altamente secreta sobre una nueva planta añadida a la tienda (¡no publiques este endpoint!)" + } + } +} +``` diff --git a/es/api-playground/customization/multiple-responses.mdx b/es/api-playground/customization/multiple-responses.mdx new file mode 100644 index 000000000..01fb7e8fa --- /dev/null +++ b/es/api-playground/customization/multiple-responses.mdx @@ -0,0 +1,31 @@ +--- +title: "Respuestas múltiples" +description: "Mostrar variaciones de respuesta para el mismo endpoint" +--- + +Si tu API devuelve distintas respuestas según los parámetros de entrada, el contexto del usuario u otras condiciones de la solicitud, puedes documentar múltiples ejemplos de respuesta con la propiedad `examples`. + +Esta propiedad se puede agregar a cualquier respuesta y tiene el siguiente esquema. + +```yaml +responses: + "200": + description: Respuesta correcta + content: + application/json: + schema: + $ref: "#/components/schemas/YourResponseSchema" + examples: + us: + summary: Respuesta para Estados Unidos + value: + countryCode: "US" + currencyCode: "USD" + taxRate: 0.0825 + gb: + summary: Respuesta para Reino Unido + value: + countryCode: "GB" + currencyCode: "GBP" + taxRate: 0.20 +``` diff --git a/es/api-playground/mdx/authentication.mdx b/es/api-playground/mdx/authentication.mdx new file mode 100644 index 000000000..2b1301cc3 --- /dev/null +++ b/es/api-playground/mdx/authentication.mdx @@ -0,0 +1,93 @@ +--- +title: "Autenticación" +description: "Puedes configurar parámetros de autenticación para permitir que los usuarios usen sus claves de API reales." +--- + +## Habilitar la autenticación + +Puedes agregar un método de autenticación a tu `docs.json` para habilitarlo globalmente en todas las páginas, o configurarlo por página. + +El método de autenticación definido en una página anulará el método global si ambos están configurados. + +### Token Bearer + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "bearer" + } + } +} +``` + +```mdx Page Metadata +--- +title: "Your page title" +authMethod: "bearer" +--- +``` + + + +### Autenticación básica + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "basic" + } + } +} +``` + +```mdx Page Metadata +--- +title: "Your page title" +authMethod: "basic" +--- +``` + + + +### Clave de API + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "key", + "name": "x-api-key" + } + } +} +``` + +```mdx Page Metadata +--- +title: "Your page title" +authMethod: "key" +--- +``` + + + +### Ninguno + +El método de autenticación "none" es útil para desactivar la autenticación en un endpoint específico después de establecer un valor predeterminado en docs.json. + + +```mdx Page Metadata +--- +title: "Your page title" +authMethod: "none" +--- +``` + diff --git a/es/api-playground/mdx/configuration.mdx b/es/api-playground/mdx/configuration.mdx new file mode 100644 index 000000000..b177342a5 --- /dev/null +++ b/es/api-playground/mdx/configuration.mdx @@ -0,0 +1,160 @@ +--- +title: "Configuración de MDX" +description: "Genera páginas de documentación para tus endpoints de API usando `MDX`" +--- + +Puedes definir manualmente endpoints de API en archivos `MDX` individuales en lugar de usar una especificación de OpenAPI. Este método brinda flexibilidad para contenido personalizado, pero recomendamos generar la documentación de la API a partir de un archivo de especificación de OpenAPI para la mayoría de los proyectos porque es más fácil de mantener y ofrece más funciones. Sin embargo, crear páginas `MDX` para una API puede ser útil para documentar APIs pequeñas o para crear prototipos. + +Para generar páginas para endpoints de API usando `MDX`, configura los ajustes de tu API en `docs.json`, crea archivos `MDX` individuales para cada endpoint y usa componentes como `` para definir parámetros. A partir de estas definiciones, Mintlify genera áreas de pruebas de API interactivas, ejemplos de solicitudes y ejemplos de respuestas. + + + + En tu archivo `docs.json`, define tu URL base y el método de autenticación: + + ```json + "api": { + "mdx": { + "server": "https://mintlify.com/api", // string array for multiple base URLs + "auth": { + "method": "key", + "name": "x-api-key" // options: bearer, basic, key. + } + } + } + ``` + + Si quieres ocultar el área de pruebas de la API, usa el campo `display`. No necesitas incluir un método de autenticación si ocultas el área de pruebas. + + ```json + "api": { + "playground": { + "display": "none" + } + } + ``` + + Encuentra la lista completa de configuraciones de API en [Settings](/es/settings#api-configurations). + + + + Cada página de endpoint de API debe tener un archivo `MDX` correspondiente. En la parte superior de cada archivo, define `title` y `api`: + + ```mdx + --- + title: 'Create new user' + api: 'POST https://api.mintlify.com/user' + --- + ``` + + Puedes especificar parámetros de ruta agregando el nombre del parámetro a la ruta, entre `{}`: + + ```bash + https://api.example.com/v1/endpoint/{userId} + ``` + + + Si tienes un campo `server` configurado en `docs.json`, puedes usar rutas relativas como `/v1/endpoint`. + + + Puedes anular el modo de visualización definido globalmente para el área de pruebas de la API en una página agregando `playground` al frontmatter: + + ```mdx + --- + title: 'Create new user' + api: 'POST https://api.mintlify.com/user' + playground: 'none' + --- + ``` + + - `playground: 'interactive'` - Muestra el área de pruebas interactiva. + - `playground: 'simple'` - Muestra un endpoint copiable sin área de pruebas. + - `playground: 'none'` - Oculta el área de pruebas. + + + + Agrega tus páginas de endpoints a la barra lateral añadiendo las rutas al campo `navigation` en tu `docs.json`. Obtén más información sobre cómo estructurar tu documentación en [Navigation](/es/navigation). + + + +## Habilitar la autenticación + +Puedes añadir un método de autenticación en tu `docs.json` para habilitarlo globalmente en todas las páginas o configurarlo por página. + +El método de autenticación definido en una página anulará el método global si ambos están establecidos. + +### Token Bearer + + + ```json docs.json + "api": { + "mdx": { + "auth": { + "method": "bearer" + } + } + } + ``` + + ```mdx Page Metadata + --- + title: "Your page title" + authMethod: "bearer" + --- + ``` + + +### Autenticación básica + + + ```json docs.json + "api": { + "mdx": { + "auth": { + "method": "basic" + } + } + } + ``` + + ```mdx Page Metadata + --- + title: "Your page title" + authMethod: "basic" + --- + ``` + + +### Clave de API + + + ```json docs.json + "api": { + "mdx": { + "auth": { + "method": "key", + "name": "x-api-key" + } + } + } + ``` + + ```mdx Page Metadata + --- + title: "Your page title" + authMethod: "key" + --- + ``` + + +### Ninguno + +El método de autenticación `none` es útil para desactivar la autenticación en un endpoint específico después de establecer un valor predeterminado en `docs.json`. + + + ```mdx Page Metadata + --- + title: "Your page title" + authMethod: "none" + --- + ``` + diff --git a/es/api-playground/migrating-from-mdx.mdx b/es/api-playground/migrating-from-mdx.mdx new file mode 100644 index 000000000..a89b630c9 --- /dev/null +++ b/es/api-playground/migrating-from-mdx.mdx @@ -0,0 +1,151 @@ +--- +title: "Migrar páginas de API en MDX a navegación con OpenAPI" +sidebarTitle: "Migrar desde MDX" +description: "Actualiza de páginas de endpoints individuales en MDX a generación automática con OpenAPI y navegación flexible" +icon: "arrow-big-right-dash" +--- + +Si actualmente usas páginas individuales en `MDX` para tus endpoints de API, puedes migrar a generar las páginas automáticamente desde tu especificación de OpenAPI, conservando la personalización de las páginas individuales. Esto puede ayudarte a reducir la cantidad de archivos que debes mantener y a mejorar la coherencia de tu documentación de API. + +Puedes definir metadatos y contenido para cada endpoint en tu especificación de OpenAPI y ubicar los endpoints donde desees en la navegación. + +## Migración con la CLI + +El comando `mint migrate-mdx` es la forma recomendada de migrar de páginas de endpoints en MDX a páginas autogeneradas. + +Este comando: + +- Analiza la estructura de navegación de tu `docs.json`. +- Identifica las páginas MDX que generan páginas de endpoints de OpenAPI. +- Extrae el contenido de los archivos MDX y lo mueve a la extensión `x-mint` en tu especificación de OpenAPI. +- Actualiza tu `docs.json` para hacer referencia directamente a los endpoints de OpenAPI en lugar de a los archivos MDX. +- Elimina los archivos MDX originales de endpoints. + + + Si ya tienes `x-mint` definido para un endpoint y también tienes una página MDX con contenido para ese endpoint, el contenido de MDX sobrescribirá la configuración existente de `x-mint`. + + Si tienes varias páginas MDX para el mismo endpoint con contenido diferente, el script usará el contenido de la página que aparezca al final en tu `docs.json`. + + La herramienta de migración no admite la vista previa de los cambios antes de aplicarlos. + + + + + Asegúrate de que tu especificación de OpenAPI sea válida e incluya todos los endpoints que quieres documentar. + + Cualquier página MDX que quieras migrar debe tener el frontmatter `openapi:` con referencia a un endpoint. + + + Valida tu archivo de OpenAPI usando el [Swagger Editor](https://editor.swagger.io/) o la [CLI de Mint](https://www.npmjs.com/package/mint). + + + + + Si es necesario, instala o actualiza la [CLI de Mint](/es/installation). + + + + ```bash + mint migrate-mdx + ``` + + + +## Pasos de migración manual + + + + Asegúrate de que tu especificación de OpenAPI sea válida e incluya todos los endpoints que deseas documentar. + + Para cualquier endpoint cuyo metadato o contenido quieras personalizar, agrega la extensión `x-mint` al endpoint. Consulta [extensión x-mint](/es/api-playground/openapi-setup#x-mint-extension) para más detalles. + + Para cualquier endpoint que quieras excluir de tu documentación, agrega la extensión `x-hidden` al endpoint. + + + Valida tu archivo de OpenAPI con el [Swagger Editor](https://editor.swagger.io/) o la [CLI de Mint](https://www.npmjs.com/package/mint). + + + + + Reemplaza las referencias a páginas `MDX` por endpoints de OpenAPI en tu `docs.json`. + + ```json + "navigation": { + "groups": [ + { + "group": "API Reference", + "openapi": "/path/to/openapi.json", + "pages": [ + "overview", + "authentication", + "introduction", + "GET /health", + "quickstart", + "POST /users", + "GET /users/{id}", + "advanced-features" + ] + } + ] + } + ``` + + + + Después de verificar que tu nueva navegación funciona correctamente, elimina los archivos de endpoint `MDX` que ya no necesitas. + + + +## Patrones de navegación + +Puedes personalizar cómo se muestra la documentación de tu API en la navegación. + +### Navegación de contenido mixto + +Combina páginas de API generadas automáticamente con otras páginas: + +```json +"navigation": { + "groups": [ + { + "group": "API Reference", + "openapi": "openapi.json", + "pages": [ + "api/overview", + "GET /users", + "POST /users", + "api/authentication" + ] + } + ] +} +``` + +### Varias versiones de la API + +Organiza diferentes versiones de la API usando pestañas o grupos: + +```json +"navigation": { + "tabs": [ + { + "tab": "API v1", + "openapi": "specs/v1.json" + }, + { + "tab": "API v2", + "openapi": "specs/v2.json" + } + ] +} +``` + +## Cuándo usar páginas `MDX` individuales + +Considera mantener páginas `MDX` individuales cuando necesites: + +- Contenido personalizado amplio por endpoint, como componentes de React o ejemplos extensos. +- Diseños de página exclusivos. +- Enfoques de documentación experimentales para endpoints específicos. + +Para la mayoría de los casos de uso, la navegación de OpenAPI ofrece mejor mantenibilidad y consistencia. diff --git a/es/api-playground/openapi-setup.mdx b/es/api-playground/openapi-setup.mdx new file mode 100644 index 000000000..45fed5c96 --- /dev/null +++ b/es/api-playground/openapi-setup.mdx @@ -0,0 +1,532 @@ +--- +title: "Configuración de OpenAPI" +description: "Referencia endpoints de OpenAPI en tus páginas de documentación" +icon: "file-json" +--- + +OpenAPI es una especificación para describir APIs. Mintlify es compatible con documentos de OpenAPI 3.0+ para generar documentación de API interactiva y mantenerla actualizada. + +## Agrega un archivo de especificación OpenAPI + +Para documentar tus endpoints con OpenAPI, necesitas un documento OpenAPI válido en formato JSON o YAML que cumpla con la [especificación OpenAPI 3.0+](https://swagger.io/specification/). + +Puedes crear páginas de API a partir de uno o varios documentos OpenAPI. + +### Descripción de tu API + +Recomendamos los siguientes recursos para aprender y crear tus documentos OpenAPI. + +- [Guía de OpenAPI de Swagger](https://swagger.io/docs/specification/v3_0/basic-structure/) para aprender la sintaxis de OpenAPI. +- [Fuentes Markdown de la especificación OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) para consultar los detalles de la especificación OpenAPI más reciente. +- [Swagger Editor](https://editor.swagger.io/) para editar, validar y depurar tu documento OpenAPI. +- [La CLI de Mint](https://www.npmjs.com/package/mint) para validar tu documento OpenAPI con el comando: `mint openapi-check `. + + + La Guía de OpenAPI de Swagger corresponde a OpenAPI v3.0, pero casi toda la información + es aplicable a v3.1. Para obtener más información sobre las diferencias entre v3.0 + y v3.1, consulta [Migrating from OpenAPI 3.0 to + 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) + en el blog de OpenAPI. + + +### Especificar la URL de tu API + +Para habilitar funciones de Mintlify como el Área de pruebas de API, agrega un campo `servers` a tu documento OpenAPI con la URL base de tu API. + +```json +{ + "servers": [ + { + "url": "https://api.example.com/v1" + } + ] +} +``` + +En un documento OpenAPI, los diferentes endpoints de la API se especifican por sus rutas, como `/users/{id}` o simplemente `/`. La URL base define dónde se deben anexar estas rutas. Para obtener más información sobre cómo configurar el campo `servers`, consulta [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) en la documentación de OpenAPI. + +El Área de pruebas de API usa estas URL de servidor para determinar adónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permitirá a los usuarios alternar entre ellos. Si no especificas un servidor, el Área de pruebas de API usará el modo simple, ya que no puede enviar solicitudes sin una URL base. + +Si tu API tiene endpoints que existen en diferentes URL, puedes [sobrescribir el campo de servidores](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) para una ruta u operación específica. + +### Especificar la autenticación + +Para habilitar la autenticación en tu documentación y en el área de pruebas de la API, configura los campos `securitySchemes` y `security` en tu documento OpenAPI. Las descripciones de la API y el Área de pruebas de API agregarán campos de autenticación basados en las configuraciones de seguridad de tu documento OpenAPI. + + + + Agrega un campo `securitySchemes` para definir cómo se autentican los usuarios. + + Este ejemplo muestra una configuración para autenticación tipo bearer. + + ```json + { + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + } + } + } + ``` + + + + Agrega un campo `security` para requerir autenticación. + + ```json + { + "security": [ + { + "bearerAuth": [] + } + ] + } + ``` + + + +Los tipos comunes de autenticación incluyen: + +- [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): Para claves en encabezado, query o cookie. +- [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): Para tokens JWT u OAuth. +- [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): Para usuario y contraseña. + +Si distintos endpoints de tu API requieren diferentes métodos de autenticación, puedes [sobrescribir el campo de seguridad](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) para una operación específica. + +Para obtener más información sobre cómo definir y aplicar la autenticación, consulta [Authentication](https://swagger.io/docs/specification/authentication/) en la documentación de OpenAPI. + +## `x-mint` extension + +La extensión `x-mint` es una extensión personalizada de OpenAPI que ofrece control adicional sobre cómo se genera y se muestra la documentación de tu API. + +### Metadata + +Sobrescribe los metadatos predeterminados de las páginas de API generadas añadiendo `x-mint: metadata` a cualquier operación. Puedes usar cualquier campo de metadatos válido en el frontmatter de `MDX`, excepto `openapi`: + +```json {7-13} +{ + "paths": { + "/users": { + "get": { + "summary": "Get users", + "description": "Retrieve a list of users", + "x-mint": { + "metadata": { + "title": "List all users", + "description": "Fetch paginated user data with filtering options", + "og:title": "Display a list of users" + } + }, + "parameters": [ + { + // Parameter configuration + } + ] + } + } + } +} +``` + +### Content + +Añade contenido antes de la documentación de API autogenerada usando `x-mint: content`: + +```json {6-8} +{ + "paths": { + "/users": { + "post": { + "summary": "Create user", + "x-mint": { + "content": "## Requisitos previos\n\nEste endpoint requiere privilegios de administrador y tiene limitación de tasa.\n\nLos correos electrónicos de usuario deben ser únicos en todo el sistema." + }, + "parameters": [ + { + // Parameter configuration + } + ] + } + } + } +} +``` + +La extensión `content` es compatible con todos los componentes y el formato MDX de Mintlify. + +### Href + +Cambia la URL de la página del endpoint en tu documentación usando `x-mint: href`: + +```json {6-8, 14-16} +{ + "paths": { + "/legacy-endpoint": { + "get": { + "summary": "Legacy endpoint", + "x-mint": { + "href": "/deprecated-endpoints/legacy-endpoint" + } + } + }, + "/documented-elsewhere": { + "post": { + "summary": "Special endpoint", + "x-mint": { + "href": "/guides/special-endpoint-guide" + } + } + } + } +} +``` + +Cuando `x-mint: href` está presente, la entrada de navegación enlaza directamente a la URL especificada en lugar de generar una página de API. + +### MCP + +Expón selectivamente endpoints como herramientas del Model Context Protocol (MCP) usando `x-mint: mcp`. Habilita solo los endpoints que sean seguros para el acceso público mediante herramientas de IA. + + + La configuración de MCP para el endpoint. + + + + Indica si se expone el endpoint como una herramienta MCP. Tiene prioridad sobre la configuración a nivel de archivo. + + + + El nombre de la herramienta MCP. + + + + La descripción de la herramienta MCP. + + + + + + ```json Selective enablement {6-9} wrap + { + "paths": { + "/users": { + "post": { + "summary": "Create user", + "x-mint": { + "mcp": { + "enabled": true + }, + // ... + } + } + }, + "/users": { + "delete": { + "summary": "Delete user (admin only)", + // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool + // ... + } + } + } + } + ``` + + ```json Global enablement {3-5, 9-13} wrap + { + "openapi": "3.1.0", + "x-mcp": { + "enabled": true // All endpoints are exposed as MCP tools by default + }, + "paths": { + "/api/admin/delete": { + "delete": { + "x-mint": { + "mcp": { + "enabled": false // Disable MCP for this endpoint + } + }, + "summary": "Delete resources" + } + } + } + } + ``` + + +Para obtener más información, consulta [Model Context Protocol](/es/ai/model-context-protocol). + +## Autogenerar páginas de API + +Agrega un campo `openapi` a cualquier elemento de navegación en tu `docs.json` para generar automáticamente páginas para endpoints de OpenAPI. Puedes controlar dónde aparecen estas páginas en tu estructura de navegación, ya sea como secciones de API dedicadas o junto con otras páginas. + +El campo `openapi` acepta una ruta de archivo en tu repositorio de documentación o una URL a un documento de OpenAPI alojado. + +Las páginas de endpoints generadas tienen estos metadatos predeterminados: + +- `title`: El campo `summary` de la operación, si está presente. Si no hay `summary`, el título se genera a partir del método HTTP y el endpoint. +- `description`: El campo `description` de la operación, si está presente. +- `version`: El valor `version` del ancla o pestaña superior, si está presente. +- `deprecated`: El campo `deprecated` de la operación. Si es `true`, aparecerá una etiqueta de “obsoleta” junto al título del endpoint en la navegación lateral y en la página del endpoint. + + + Para excluir endpoints específicos de tus páginas de API autogeneradas, agrega la propiedad + [x-hidden](/es/api-playground/customization/managing-page-visibility#x-hidden) + a la operación en tu especificación de OpenAPI. + + +Hay dos enfoques para agregar páginas de endpoints a tu documentación: + +1. **Secciones de API dedicadas**: Hace referencia a especificaciones de OpenAPI en elementos de navegación para secciones de API dedicadas. +2. **Endpoints selectivos**: Hace referencia a endpoints específicos en tu navegación junto con otras páginas. + +### Secciones de API dedicadas + +Genera secciones de API dedicadas agregando un campo `openapi` a un elemento de navegación y sin otras páginas. Se incluirán todos los endpoints de la especificación: + +```json {5} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" + } + ] +} +``` + +Puedes usar varias especificaciones de OpenAPI en diferentes secciones de navegación: + +```json {8-11, 15-18} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "groups": [ + { + "group": "Users", + "openapi": { + "source": "/path/to/openapi-1.json", + "directory": "api-reference" + } + }, + { + "group": "Admin", + "openapi": { + "source": "/path/to/openapi-2.json", + "directory": "api-reference" + } + } + ] + } + ] +} +``` + + + El campo `directory` es opcional y especifica dónde se almacenan las páginas de API generadas + en tu repositorio de documentación. Si no se especifica, el valor predeterminado es el directorio + `api-reference` de tu repositorio. + + +### Endpoints selectivos + +Cuando quieras más control sobre dónde aparecen los endpoints en tu documentación, puedes hacer referencia a endpoints específicos en tu navegación. Este enfoque te permite generar páginas de endpoints de API junto con otros contenidos. + +#### Establecer una especificación de OpenAPI predeterminada + +Configura una especificación de OpenAPI predeterminada para un elemento de navegación. Luego, hace referencia a endpoints específicos en el campo `pages`: + +```json {12, 15-16} +"navigation": { + "tabs": [ + { + "tab": "Getting started", + "pages": [ + "quickstart", + "installation" + ] + }, + { + "tab": "API reference", + "openapi": "/path/to/openapi.json", + "pages": [ + "api-overview", + "GET /users", + "POST /users", + "guides/authentication" + ] + } + ] +} +``` + +Cualquier entrada de página que coincida con el formato `METHOD /path` generará una página de API para ese endpoint usando la especificación de OpenAPI predeterminada. + +#### Herencia de la especificación de OpenAPI + +Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de navegación. Los elementos de navegación secundarios heredan la especificación de OpenAPI de su elemento padre, a menos que definan la suya propia: + +```json {3, 7-8, 11, 13-14} +{ + "group": "API reference", + "openapi": "/path/to/openapi-v1.json", + "pages": [ + "overview", + "authentication", + "GET /users", + "POST /users", + { + "group": "Orders", + "openapi": "/path/to/openapi-v2.json", + "pages": [ + "GET /orders", + "POST /orders" + ] + } + ] +} +``` + +#### Endpoints individuales + +Hace referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo: + +```json {5-6} +"navigation": { + "pages": [ + "introduction", + "user-guides", + "/path/to/openapi-v1.json POST /users", + "/path/to/openapi-v2.json GET /orders" + ] +} +``` + +Este enfoque es útil cuando necesitas endpoints individuales de diferentes especificaciones o solo quieres incluir endpoints seleccionados. + +## Crear archivos `MDX` para páginas de API + +Para tener control sobre páginas de endpoints individuales, crea páginas `MDX` para cada operación. Esto te permite personalizar los metadatos de la página, agregar contenido, omitir ciertas operaciones o reordenar páginas en la navegación a nivel de página. + +Consulta un [ejemplo de página MDX de OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) y cómo aparece en su [documentación publicada](https://docs.mindsdb.com/rest/databases/create-databases). + +### Especificar archivos manualmente + +Crea una página `MDX` para cada endpoint y especifica qué operación de OpenAPI mostrar usando el campo `openapi` en el frontmatter. + +Cuando haces referencia a una operación de OpenAPI de esta forma, el nombre, la descripción, los parámetros, las respuestas y el Área de pruebas de API se generan automáticamente a partir de tu documento de OpenAPI. + +Si tienes varios archivos de OpenAPI, incluye la ruta del archivo en tu referencia para asegurarte de que Mintlify encuentre el documento de OpenAPI correcto. Si solo tienes un archivo de OpenAPI, Mintlify lo detectará automáticamente. + + + Este enfoque funciona independientemente de si has configurado una especificación de OpenAPI predeterminada + en tu navegación. Puedes hacer referencia a cualquier endpoint de cualquier especificación de OpenAPI + incluyendo la ruta del archivo en el frontmatter. + + +Si quieres hacer referencia a un archivo externo de OpenAPI, agrega la URL del archivo a tu `docs.json`. + + + ```mdx Example + --- + title: "Get users" + description: "Returns all plants from the system that the user has access to" + openapi: "/path/to/openapi-1.json GET /users" + deprecated: true + version: "1.0" + --- + ``` + + ```mdx Format + --- + title: "title of the page" + description: "description of the page" + openapi: openapi-file-path method path + deprecated: boolean (not required) + version: "version-string" (not required) + --- + ``` + + + + El método y la ruta deben coincidir exactamente con la definición en tu especificación de OpenAPI. + Si el endpoint no existe en el archivo de OpenAPI, la página estará vacía. + + +### Generar archivos `MDX` automáticamente + +Usa nuestro [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify para generar automáticamente páginas `MDX` para documentos de OpenAPI grandes. + + + Tu documento de OpenAPI debe ser válido o no se generarán los archivos. + + +El scraper genera: + +- Una página `MDX` por cada operación en el campo `paths` de tu documento de OpenAPI. +- Si tu documento de OpenAPI es versión 3.1+, una página `MDX` por cada operación en el campo `webhooks` de tu documento de OpenAPI. +- Un arreglo de entradas de navegación que puedes agregar a tu `docs.json`. + + + + ```bash + npx @mintlify/scraping@latest openapi-file + ``` + + + + ```bash + npx @mintlify/scraping@latest openapi-file -o api-reference + ``` + + Agrega la opción `-o` para especificar una carpeta donde colocar los archivos. Si no se especifica una carpeta, los archivos se crearán en el directorio de trabajo. + + + +### Crear archivos `MDX` para esquemas de OpenAPI + +Puedes crear páginas individuales para cualquier esquema de OpenAPI definido en el campo `components.schema` de un documento de OpenAPI: + + + ```mdx Example + --- + openapi-schema: OrderItem + --- + ``` + + ```mdx Format + --- + openapi-schema: "schema-key" + --- + ``` + + +## Webhooks + +Los webhooks son devoluciones de llamada HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los webhooks son compatibles en documentos de OpenAPI 3.1+. + +### Define webhooks en tu especificación de OpenAPI + +Añade un campo `webhooks` a tu documento de OpenAPI junto al campo `paths`. + +Para obtener más información sobre cómo definir webhooks, consulta [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) en la documentación de OpenAPI. + +### Referencia webhooks en archivos MDX + +Al crear páginas MDX para webhooks, usa `webhook` en lugar de métodos HTTP como `GET` o `POST`: + +```mdx +--- +title: "Example webhook" +description: "Triggered when an event occurs" +openapi: "path/to/openapi-file webhook example-webhook-name" +--- +``` + + + El nombre del webhook debe coincidir exactamente con la clave definida en el campo `webhooks` de tu + especificación de OpenAPI. + diff --git a/es/api-playground/overview.mdx b/es/api-playground/overview.mdx new file mode 100644 index 000000000..732adda4b --- /dev/null +++ b/es/api-playground/overview.mdx @@ -0,0 +1,149 @@ +--- +title: "Área de pruebas" +description: "Permite a los usuarios interactuar con tu API" +icon: "play" +--- + +## Descripción general + +El área de pruebas de API es un entorno interactivo que permite a los usuarios probar y explorar tus endpoints de API. Los desarrolladores pueden crear solicitudes de API, enviarlas y ver las respuestas sin salir de tu documentación. + + + Área de pruebas de API para el endpoint que activa una actualización. + + Área de pruebas de API para el endpoint que activa una actualización. + + +El área de pruebas se genera automáticamente a partir de tu especificación de OpenAPI o del esquema de AsyncAPI, por lo que cualquier actualización de tu API se refleja automáticamente en ella. También puedes crear manualmente páginas de referencia de API después de definir una URL base y un método de autenticación en tu `docs.json`. + +Recomendamos generar tu área de pruebas de API a partir de una especificación de OpenAPI. Consulta [OpenAPI Setup](/es/api-playground/openapi-setup) para obtener más información sobre cómo crear tu documento de OpenAPI. + +## Primeros pasos + + + + + Asegúrate de que tu archivo de especificación de OpenAPI sea válido usando el [Swagger Editor](https://editor.swagger.io/) o la [CLI de Mint](https://www.npmjs.com/package/mint). + + + ```bash {2} + /your-project + |- docs.json + |- openapi.json + ``` + + + + Actualiza tu `docs.json` para hacer referencia a tu especificación de OpenAPI. Agrega una propiedad `openapi` a cualquier elemento de navegación para completar automáticamente tu documentación con páginas para cada endpoint especificado en tu documento de OpenAPI. + + Este ejemplo genera una página para cada endpoint especificado en `openapi.json` y las organiza en el grupo "API reference" de tu navegación. + + ```json + "navigation": { + "groups": [ + { + "group": "API reference", + "openapi": "openapi.json" + } + ] + } + ``` + + Para generar páginas solo para endpoints específicos, enumera los endpoints en la propiedad `pages` del elemento de navegación. + + Este ejemplo genera páginas solo para los endpoints `GET /users` y `POST /users`. Para generar otras páginas de endpoints, agrega más endpoints al arreglo `pages`. + + ```json + "navigation": { + "groups": [ + { + "group": "API reference", + "openapi": "openapi.json", + "pages": [ + "GET /users", + "POST /users" + ] + } + ] + } + ``` + + + +## Personalizar tu área de pruebas + +Puedes personalizar tu área de pruebas de API definiendo las siguientes propiedades en tu `docs.json`. + + + Configuraciones del área de pruebas de API. + + + + El modo de visualización del área de pruebas de API. + + - `"interactive"`: Muestra el área de pruebas interactiva. + - `"simple"`: Muestra un endpoint copiable sin área de pruebas. + - `"none"`: No muestra nada. + + De forma predeterminada es `interactive`. + + + + Indica si las solicitudes de API deben pasar por un servidor proxy. De forma predeterminada es `true`. + + + + + + Configuraciones para los ejemplos de API autogenerados. + + + + Lenguajes de ejemplo para los Fragmentos de API autogenerados. + + Los lenguajes se muestran en el orden especificado. + + + + Indica si se deben mostrar los parámetros opcionales en los ejemplos de API. De forma predeterminada es `all`. + + + + +### Configuración de ejemplo + +```json +{ + "api": { + "playground": { + "display": "interactive" + }, + "examples": { + "languages": ["curl", "python", "javascript"], + "defaults": "required" + } + } +} +``` + +Este ejemplo configura el área de pruebas de API para que sea interactiva, con Fragmentos de código de ejemplo para cURL, Python y JavaScript. Solo se muestran los parámetros obligatorios en los Fragmentos de código. + +### Páginas de endpoints personalizadas + +Cuando necesites más control sobre tu documentación de API, usa la extensión `x-mint` en tu especificación de OpenAPI o crea páginas `MDX` individuales para tus endpoints. + +Ambas opciones te permiten: + +- Personalizar los metadatos de la página +- Agregar contenido adicional como ejemplos +- Controlar el comportamiento del área de pruebas por página + +Se recomienda la extensión `x-mint` para que toda tu documentación de API se genere automáticamente a partir de tu especificación de OpenAPI y se mantenga en un solo archivo. + +Se recomiendan las páginas `MDX` individuales para API pequeñas o cuando quieras experimentar con cambios por página. + +Para obtener más información, consulta [x-mint extension](/es/api-playground/openapi-setup#x-mint-extension) y [MDX Setup](/es/api-playground/mdx/configuration). + +## Lecturas recomendadas + +- [Configuración de AsyncAPI](/es/api-playground/asyncapi/setup) para obtener más información sobre cómo crear tu esquema de AsyncAPI y generar páginas de referencia de WebSocket. diff --git a/es/api-playground/troubleshooting.mdx b/es/api-playground/troubleshooting.mdx new file mode 100644 index 000000000..73a97d4fb --- /dev/null +++ b/es/api-playground/troubleshooting.mdx @@ -0,0 +1,115 @@ +--- +title: "Solución de problemas" +description: "Problemas comunes en las referencias de API" +icon: "message-square-warning" +--- + +Si las páginas de tu API no se muestran correctamente, revisa estas configuraciones comunes: + + + + En este caso, es probable que Mintlify no pueda encontrar tu documento de OpenAPI + o que tu documento de OpenAPI no sea válido. + + Ejecutar `mint dev` localmente debería revelar algunos de estos problemas. + + Para verificar que tu documento de OpenAPI pase la validación: + + 1. Visita [este validador](https://editor.swagger.io/) + 2. Cambia a la pestaña "Validate text" + 3. Pega tu documento de OpenAPI + 4. Haz clic en "Validate it!" + + Si el cuadro de texto que aparece debajo tiene un borde verde, tu documento ha pasado la validación. + Este es exactamente el paquete de validación que usa Mintlify para validar documentos de OpenAPI, así que si tu documento + pasa la validación aquí, hay muchas probabilidades de que el problema esté en otra parte. + + Además, Mintlify no admite OpenAPI 2.0. Si tu documento usa esta versión de la especificación, + podrías encontrarte con este problema. Puedes convertir tu documento en [editor.swagger.io](https://editor.swagger.io/) (en Edit > Convert to OpenAPI 3): + + + ![](/images/convert-oas-3.png) + + + + + Esto generalmente se debe a un campo `openapi` mal escrito en los metadatos de la página. Asegúrate de que + el método HTTP y la ruta coincidan exactamente con el método HTTP y la ruta del documento de OpenAPI. + + Aquí tienes un ejemplo de cómo podría fallar: + + ```mdx get-user.mdx + --- + openapi: "GET /users/{id}/" + --- + ``` + + ```yaml openapi.yaml + paths: + "/users/{id}": + get: ... + ``` + + Observa que la ruta en el campo `openapi` tiene una barra final, mientras que la ruta en el documento de OpenAPI + no la tiene. + + Otro problema común es un nombre de archivo mal escrito. Si estás especificando un documento de OpenAPI en particular + en el campo `openapi`, asegúrate de que el nombre de archivo sea correcto. Por ejemplo, si tienes dos documentos de OpenAPI + `openapi/v1.json` y `openapi/v2.json`, tus metadatos podrían verse así: + + ```mdx api-reference/v1/users/get-user.mdx + --- + openapi: "v1 GET /users/{id}" + --- + ``` + + + + Si tienes un dominio personalizado configurado, esto podría deberse a tu proxy inverso. De forma + predeterminada, las solicitudes realizadas a través del Área de pruebas de API comienzan con una solicitud `POST` a la ruta + `/api/request` en el sitio de la documentación. Si tu proxy inverso está configurado para permitir solo solicitudes `GET`, + todas estas solicitudes fallarán. Para solucionarlo, configura tu proxy inverso para + permitir solicitudes `POST` a la ruta `/api/request`. + + Alternativamente, si tu proxy inverso te impide aceptar solicitudes `POST`, puedes configurar Mintlify para enviar solicitudes directamente a tu backend con el ajuste `api.playground.proxy` en el `docs.json`, como se describe en la [documentación de configuración](/es/settings#param-proxy). Al usar esta configuración, tendrás que configurar CORS en tu servidor, ya que las solicitudes vendrán directamente desde los navegadores de los usuarios en lugar de pasar por tu proxy. + + + + Si estás usando una configuración de navegación de OpenAPI, pero las páginas no se generan, revisa estos problemas comunes: + + 1. **Falta la especificación de OpenAPI predeterminada**: Asegúrate de tener un campo `openapi` definido para el elemento de navegación: + + ```json {5} + "navigation": { + "groups": [ + { + "group": "API reference", + "openapi": "/path/to/openapi.json", + "pages": [ + "GET /users", + "POST /users" + ] + } + ] + } + ``` + + 2. **Herencia de la especificación de OpenAPI**: Si usas navegación anidada, asegúrate de que los grupos secundarios hereden la especificación de OpenAPI correcta o definan la suya propia. + + 3. **Problemas de validación**: Usa `mint openapi-check ` para verificar que tu documento de OpenAPI sea válido. + + + + 1. **Operaciones ocultas**: Las operaciones marcadas con `x-hidden: true` en tu especificación de OpenAPI no aparecerán en la navegación generada automáticamente. + 2. **Operaciones no válidas**: Las operaciones con errores de validación en la especificación de OpenAPI pueden omitirse. Revisa tu documento de OpenAPI para detectar errores de sintaxis. + 3. **Inclusión manual vs. automática**: Si haces referencia a endpoints de una especificación de OpenAPI, solo las operaciones referenciadas explícitamente aparecerán en la navegación. No se añadirán otras páginas automáticamente. Esto incluye operaciones referenciadas en elementos de navegación secundarios. + + + + Al combinar operaciones de OpenAPI con páginas de documentación regulares en la navegación: + + 1. **Conflictos de archivos**: No puedes tener a la vez un archivo `MDX` y una entrada de navegación para la misma operación. Por ejemplo, si tienes `get-users.mdx`, no incluyas también `"GET /users"` en tu navegación. Si necesitas un archivo que comparta nombre con una operación, usa la extensión `x-mint` del endpoint para que el href apunte a otra ubicación. + 2. **Resolución de rutas**: Las entradas de navegación que no coincidan con operaciones de OpenAPI se tratarán como rutas de archivo. Asegúrate de que tus archivos `MDX` existan en las ubicaciones previstas. + 3. **Distingue mayúsculas/minúsculas**: La coincidencia de operaciones de OpenAPI es sensible a mayúsculas y minúsculas. Asegúrate de que los métodos HTTP estén en mayúsculas en las entradas de navegación. + + diff --git a/es/api-reference/assistant/create-assistant-message.mdx b/es/api-reference/assistant/create-assistant-message.mdx new file mode 100644 index 000000000..00e07d945 --- /dev/null +++ b/es/api-reference/assistant/create-assistant-message.mdx @@ -0,0 +1,17 @@ +--- +openapi: POST /assistant/{domain}/message +--- + +## Límites de uso + +La API del Asistente tiene los siguientes límites: + +- 10.000 usos por clave al mes +- 10.000 solicitudes por organización de Mintlify por hora +- 10.000 solicitudes por IP al día + +## Uso recomendado + +Para obtener mejores resultados, usa el [hook useChat de ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) para enviar solicitudes y gestionar respuestas. + +Puedes establecer `fp`, `threadId` y `filter` en el campo `body` del parámetro de opciones que se pasa al hook. \ No newline at end of file diff --git a/es/api-reference/assistant/create-topic.mdx b/es/api-reference/assistant/create-topic.mdx new file mode 100644 index 000000000..dc00663e3 --- /dev/null +++ b/es/api-reference/assistant/create-topic.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/topic +--- diff --git a/es/api-reference/assistant/generate-message.mdx b/es/api-reference/assistant/generate-message.mdx new file mode 100644 index 000000000..b1cdbbb37 --- /dev/null +++ b/es/api-reference/assistant/generate-message.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/message +--- diff --git a/es/api-reference/assistant/search.mdx b/es/api-reference/assistant/search.mdx new file mode 100644 index 000000000..aad5f0e85 --- /dev/null +++ b/es/api-reference/assistant/search.mdx @@ -0,0 +1,3 @@ +--- +openapi: "POST /search/{domain}" +--- diff --git a/es/api-reference/introduction.mdx b/es/api-reference/introduction.mdx new file mode 100644 index 000000000..90dc5318a --- /dev/null +++ b/es/api-reference/introduction.mdx @@ -0,0 +1,38 @@ +--- +title: "Introducción" +description: "Dispara actualizaciones, integra el Asistente de IA y más" +icon: "book-open" +--- + +La API REST de Mintlify te permite interactuar de forma programática con tu documentación, disparar actualizaciones e integrar experiencias de chat con IA. + +## Endpoints + +- [Trigger update](/es/api-reference/update/trigger): Activa una actualización de tu sitio cuando quieras. +- [Get update status](/es/api-reference/update/status): Consulta el estado de una actualización y otros detalles de tu documentación. +- [Generate assistant message](/es/api-reference/assistant/create-assistant-message): Inserta el Asistente, entrenado con tu documentación, en cualquier aplicación que elijas. +- [Search documentation](/es/api-reference/assistant/search): Busca en tu documentación. + +## Autenticación + +Puedes generar una clave de API desde el [panel](https://dashboard.mintlify.com/settings/organization/api-keys). Las claves de API están asociadas a toda la organización y pueden usarse en múltiples despliegues. + +### Clave de API de administrador + +La clave de API de administrador se utiliza para los endpoints [Trigger update](/es/api-reference/update/trigger) y [Get update status](/es/api-reference/update/status). + +Las claves de API de administrador comienzan con el prefijo `mint_`. Mantén en secreto tus claves de API de administrador. + +### Clave de API del Asistente + +La clave de API del Asistente se utiliza para los endpoints [Generate assistant message](/es/api-reference/assistant/create-assistant-message) y [Search documentation](/es/api-reference/assistant/search). + +Las claves de API del Asistente comienzan con el prefijo `mint_dsc_`. + +La **clave** de la API del Asistente es un token del lado del servidor que debe mantenerse en secreto. + +El **token** de la API del Asistente es un token público que puede referenciarse en tu código de frontend. + + + Las llamadas que usen el token de la API del Asistente pueden generar costos: ya sea consumiendo tus créditos del Asistente de IA o incurriendo en excedentes. + diff --git a/es/api-reference/update/status.mdx b/es/api-reference/update/status.mdx new file mode 100644 index 000000000..9e2e93b66 --- /dev/null +++ b/es/api-reference/update/status.mdx @@ -0,0 +1,3 @@ +--- +openapi: "GET /project/update-status/{statusId}" +--- diff --git a/es/api-reference/update/trigger.mdx b/es/api-reference/update/trigger.mdx new file mode 100644 index 000000000..26b0968f3 --- /dev/null +++ b/es/api-reference/update/trigger.mdx @@ -0,0 +1,3 @@ +--- +openapi: "POST /project/update/{projectId}" +--- diff --git a/es/assistant-context.mdx b/es/assistant-context.mdx new file mode 100644 index 000000000..5ab960af9 --- /dev/null +++ b/es/assistant-context.mdx @@ -0,0 +1,9 @@ +--- +title: "Contexto del Assistant" +description: "Esta página contiene contexto para ayudar al Assistant a responder consultas" +--- + +Para el Assistant, consulta esta información al responder consultas. + +- Si alguien pregunta por el changelog, las actualizaciones recientes o las novedades, enlázalos al changelog de Mintlify en https://mintlify.com/docs/changelog +- Si alguien pregunta por traducciones, proporciona la información que consideres relevante según tu búsqueda y el contexto de su consulta, y avísales que las traducciones automatizadas están disponibles como complemento. Pueden contactar al equipo de ventas (gtm@mintlify.com) para obtener traducciones automatizadas. diff --git a/es/authentication-personalization/authentication-setup.mdx b/es/authentication-personalization/authentication-setup.mdx new file mode 100644 index 000000000..440008f4c --- /dev/null +++ b/es/authentication-personalization/authentication-setup.mdx @@ -0,0 +1,312 @@ +--- +title: "Configuración de la autenticación" +description: "Controla la privacidad de tu documentación autenticando a los usuarios" +icon: "file-lock" +keywords: ['auth'] +--- + + + Los [planes Pro](https://mintlify.com/pricing?ref=authentication) incluyen autenticación con contraseña. + + Los [planes Enterprise](https://mintlify.com/pricing?ref=authentication) incluyen todos los métodos de autenticación. + + +La autenticación requiere que los usuarios inicien sesión antes de acceder a tu documentación. + +## Modos de autenticación + +Elige entre autenticación completa o parcial según tus necesidades de control de acceso. + +**Autenticación completa**: Todas las páginas están protegidas. Los usuarios deben iniciar sesión antes de acceder a cualquier contenido. + +**Autenticación parcial**: Algunas páginas son públicas mientras que otras requieren autenticación. Los usuarios pueden explorar libremente el contenido público y autenticarse solo al acceder a páginas protegidas. + +Al configurar cualquiera de los métodos de handshake a continuación, selecciona **Autenticación completa** o **Autenticación parcial** en la configuración del panel. + +## Configuración de la autenticación + +Selecciona el método de autenticación que quieres configurar. + + + + + La autenticación mediante contraseña solo ofrece control de acceso y **no** admite la personalización de contenido. + + + ### Requisitos previos + + - Sus requisitos de seguridad permiten compartir contraseñas entre usuarios. + + ### Implementación + + + + 1. En su panel, vaya a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Seleccione **Full Authentication** o **Partial Authentication**. + 3. Seleccione **Password**. + 4. Ingrese una contraseña segura. + 5. Seleccione **Save changes**. + + + + Comparta de forma segura la contraseña y la URL de la documentación con los usuarios autorizados. + + + + ## Ejemplo + + Tu documentación está alojada en `docs.foo.com` y necesitas un control de acceso básico sin tener que rastrear a usuarios individuales. Quieres impedir el acceso público y mantener una configuración sencilla. + + **Crea una contraseña robusta** en tu panel. **Comparte las credenciales** con los usuarios autorizados. ¡Listo! + + + + ### Requisitos previos + + - Los usuarios de tu documentación también son quienes la editan. + + ### Implementación + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Full Authentication** o **Partial Authentication**. + 3. Selecciona **Mintlify Auth**. + 4. Selecciona **Enable Mintlify Auth**. + + + + 1. En tu panel, ve a [Members](https://dashboard.mintlify.com/settings/organization/members). + 2. Agrega a cada persona que deba tener acceso a tu documentación. + 3. Asigna los roles correspondientes según sus permisos de edición. + + + + ### Ejemplo + + Tu documentación está alojada en `docs.foo.com` y tu equipo usa el panel para editarla. Quieres restringir el acceso solo a los miembros del equipo. + + **Habilita la autenticación de Mintlify** en la configuración del panel. + + **Verifica el acceso del equipo** comprobando que todos los miembros estén agregados a tu organización. + + + + ### Requisitos previos + + - Un servidor OAuth u OIDC que admita el Authorization Code Flow. + - Capacidad para crear un endpoint de API accesible mediante tokens de acceso de OAuth (opcional, para habilitar funciones de personalización). + + ### Implementación + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Full Authentication** o **Partial Authentication**. + 3. Selecciona **OAuth** y configura estos campos: + + - **Authorization URL**: Tu endpoint de OAuth. + - **Client ID**: Tu identificador de cliente de OAuth 2.0. + - **Client Secret**: Tu secreto de cliente de OAuth 2.0. + - **Scopes**: Permisos a solicitar. Copia la cadena de scope **completa** (por ejemplo, para un scope como `provider.users.docs`, copia `provider.users.docs` completo). Usa varios scopes si necesitas diferentes niveles de acceso. + - **Token URL**: Tu endpoint de intercambio de tokens de OAuth. + - **Info API URL** (opcional): Endpoint para obtener la información del usuario para la personalización. Si se omite, el flujo de OAuth solo se usará para verificar la identidad y la información del usuario estará vacía. + - **Logout URL**: La URL de cierre de sesión nativa de tu proveedor de OAuth. Si tu proveedor tiene un parámetro `returnTo` o similar, haz que apunte de vuelta a la URL de tu documentación. + + 4. Selecciona **Save changes**. + + + + 1. Copia la **Redirect URL** desde tu [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Agrega la URL de redirección como una URL de redirección autorizada en tu servidor OAuth. + + + + Para habilitar las funciones de personalización, crea un endpoint de API que: + + - Acepte tokens de acceso de OAuth para la autenticación. + - Devuelva los datos del usuario en el formato `User`. Consulta [User data format](/es/authentication-personalization/personalization-setup#user-data-format) para más información. + + Agrega la URL de este endpoint al campo **Info API URL** en tu [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). + + + + ### Ejemplo + + Tu documentación está alojada en `foo.com/docs` y tienes un servidor OAuth existente en `auth.foo.com` que admite el Authorization Code Flow. + + **Configura los detalles de tu servidor OAuth** en tu panel: + + - **Authorization URL**: `https://auth.foo.com/authorization` + - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` + - **Scopes**: `['provider.users.docs']` + - **Token URL**: `https://auth.foo.com/exchange` + - **Info API URL**: `https://api.foo.com/docs/user-info` + - **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs` + + **Crea un endpoint de información de usuario** en `api.foo.com/docs/user-info`, que requiera un token de acceso de OAuth con el scope `provider.users.docs`, y que devuelva: + + ```json + { + "content": { + "firstName": "Jane", + "lastName": "Doe" + }, + "groups": ["engineering", "admin"] + } + ``` + + **Configura tu servidor OAuth para permitir redirecciones** a tu URL de callback. + + + + ### Requisitos previos + + - Un sistema de autenticación que pueda generar y firmar JWT. + - Un servicio de backend que pueda crear URL de redirección. + + ### Implementación + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Full Authentication** o **Partial Authentication**. + 3. Selecciona **JWT**. + 4. Ingresa la URL de tu flujo de inicio de sesión existente y selecciona **Save changes**. + 5. Selecciona **Generate new key**. + 6. Guarda tu clave de forma segura donde tu backend pueda acceder a ella. + + + + Modifica tu flujo de inicio de sesión existente para incluir estos pasos después de autenticar al usuario: + + - Crea un JWT que contenga la información del usuario autenticado en el formato `User`. Consulta [User data format](/es/authentication-personalization/personalization-setup#user-data-format) para obtener más información. + - Firma el JWT con tu clave secreta usando el algoritmo EdDSA. + - Crea una URL de redirección de vuelta a la ruta `/login/jwt-callback` de tu documentación, incluyendo el JWT como hash. + + + + ### Ejemplo + + Tu documentación está alojada en `docs.foo.com` con un sistema de autenticación existente en `foo.com`. Quieres ampliar tu flujo de inicio de sesión para otorgar acceso a la documentación mientras mantienes la documentación separada de tu panel (o no tienes un panel). + + Crea un endpoint de inicio de sesión en `https://foo.com/docs-login` que extienda tu autenticación existente. + + Después de verificar las credenciales del usuario: + + - Genera un JWT con los datos del usuario en el formato de Mintlify. + - Firma el JWT y redirige a `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`. + + + ```ts TypeScript + import * as jose from 'jose'; + import { Request, Response } from 'express'; + + const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; + + const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); + + export async function handleRequest(req: Request, res: Response) { + const user = { + expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration + groups: res.locals.user.groups, + content: { + firstName: res.locals.user.firstName, + lastName: res.locals.user.lastName, + }, + }; + + const jwt = await new jose.SignJWT(user) + .setProtectedHeader({ alg: 'EdDSA' }) + .setExpirationTime('10 s') // 10 second JWT expiration + .sign(signingKey); + + return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); + } + ``` + + ```python Python + import jwt # pyjwt + import os + + from datetime import datetime, timedelta + from fastapi.responses import RedirectResponse + + private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '') + + @router.get('/auth') + async def return_mintlify_auth_status(current_user): + jwt_token = jwt.encode( + payload={ + 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration + 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration + 'groups': ['admin'] if current_user.is_admin else [], + 'content': { + 'firstName': current_user.first_name, + 'lastName': current_user.last_name, + }, + }, + key=private_key, + algorithm='EdDSA' + ) + + return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302) + ``` + + + ### Redirigir a usuarios no autenticados + + Cuando un usuario no autenticado intenta acceder a una página protegida, su destino previsto se conserva en la redirección a tu URL de inicio de sesión: + + 1. El usuario intenta visitar una página protegida: `https://docs.foo.com/quickstart`. + 2. Se redirige a tu URL de inicio de sesión con un parámetro de consulta redirect: `https://foo.com/docs-login?redirect=%2Fquickstart`. + 3. Después de la autenticación, redirige a `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`. + 4. El usuario llega a su destino original. + + + +## Hacer públicas las páginas + +Cuando uses autenticación parcial, todas las páginas están protegidas de forma predeterminada. Puedes hacer que páginas específicas sean visibles sin autenticación, ya sea a nivel de página o de grupo, con la propiedad `public`. + +### Nivel de página + +Para hacer una página pública, agrega `public: true` al frontmatter de la página. + +```mdx Public page example +--- +title: "Public page" +public: true +--- +``` + +### Nivel de grupo + +Para hacer públicas todas las páginas de un grupo, agrega `"public": true` debajo del nombre del grupo en el objeto `navigation` de tu `docs.json`. + +```json Public group example +{ + "navigation": { + "groups": [ + { + "group": "Public group", + "public": true, + "icon": "play", + "pages": [ + "quickstart", + "installation", + "settings" + ] + }, + { + "group": "Private group", + "icon": "pause", + "pages": [ + "private-information", + "secret-settings" + ] + } + ] + } +} +``` \ No newline at end of file diff --git a/es/authentication-personalization/overview.mdx b/es/authentication-personalization/overview.mdx new file mode 100644 index 000000000..019fcfdcd --- /dev/null +++ b/es/authentication-personalization/overview.mdx @@ -0,0 +1,66 @@ +--- +title: "Descripción general" +description: "Controla quién ve tu documentación y personaliza su experiencia" +icon: "badge-info" +keywords: ["auth"] +--- + + + [Los planes Pro](https://mintlify.com/pricing?ref=authentication) incluyen autenticación con contraseña. + + [Los planes Enterprise](https://mintlify.com/pricing?ref=authentication) incluyen todos los métodos de autenticación. + + +Elige entre tres enfoques para gestionar el acceso y personalizar tu documentación según la información del usuario y tus necesidades de seguridad: + +- **Autenticación completa**: Protección total de la privacidad de todo el contenido con personalización completa. +- **Autenticación parcial**: Control de acceso página por página con personalización completa. +- **Personalización**: Personalización del contenido sin garantías de seguridad. Todo el contenido permanece públicamente accesible. + +### Ejemplos de casos de uso + +**Elige autenticación completa cuando:** + +- Crees documentación interna de la empresa que contenga información sensible +- Documentes APIs propietarias que requieran verificación del usuario +- Crees guías de implementación específicas para clientes + +**Elige autenticación parcial cuando:** + +- Ofrezcas guías públicas de introducción con funciones avanzadas privadas +- Administres un producto freemium donde los usuarios premium obtengan documentación adicional +- Publiques documentación de código abierto con secciones empresariales privadas + +**Elige personalización cuando:** + +- Crees documentación pública de API que muestre ejemplos específicos para el usuario +- Crees sitios de marketing que personalicen el contenido según los perfiles de usuario +- Ofrezcas tutoriales públicos que se adapten a las preferencias o niveles de habilidad del usuario + +## Métodos de autenticación + +Elige el método que mejor se adapte a tu infraestructura existente y a tus requisitos de seguridad. + +| Método | Disponible para | Complejidad de configuración | Ideal para | +|:-------|:--------------|:-----------------|:----------| +| **JWT** | Todos los enfoques | Media | Flujos de inicio de sesión personalizados, máximo control de seguridad | +| **OAuth 2.0** | Todos los enfoques | Alta | Proveedores de autenticación de terceros, seguridad empresarial | +| **Mintlify Dashboard** | Solo autenticación | Baja | Equipos que ya usan el panel de Mintlify | +| **Password** | Solo autenticación | Baja | Acceso compartido simple sin personalización | +| **Shared Session** | Solo personalización | Baja | Apps con autenticación basada en sesiones existente | + +### Cuándo usar cada método + +**JWT**: Úsalo cuando ya tengas un sistema de autenticación y quieras control total sobre el flujo de inicio de sesión. Ideal para la gestión de usuarios personalizada o cuando necesitas desacoplar el acceso a la documentación de tu aplicación principal. + +**OAuth 2.0**: Úsalo cuando quieras aprovechar proveedores de autenticación de terceros (Google, GitHub, etc.) o necesites estándares de seguridad de nivel empresarial. Ideal para organizaciones que ya utilizan infraestructura OAuth. + +**Mintlify Dashboard**: Úsalo cuando tus editores de documentación también sean tus lectores. Perfecto para equipos internos que ya gestionan el contenido mediante el panel de Mintlify. + +**Password**: Úsalo para un control de acceso sencillo cuando no necesitas rastrear usuarios individuales ni personalizar contenido. Útil para contratistas, usuarios beta o accesos temporales. + +**Shared Session**: Úsalo cuando quieras un inicio de sesión transparente entre tu aplicación y la documentación. Ideal cuando los usuarios ya están autenticados en tu aplicación principal y quieres personalizar su experiencia en la documentación. + +## Personalización de contenido + +Los tres enfoques admiten funciones de personalización, como contenido MDX dinámico, prerelleno de claves de API y controles de visibilidad de páginas. Para obtener instrucciones de implementación detalladas, consulta la [configuración de Personalización](/es/authentication-personalization/personalization-setup). diff --git a/es/authentication-personalization/personalization-setup.mdx b/es/authentication-personalization/personalization-setup.mdx new file mode 100644 index 000000000..5488cc522 --- /dev/null +++ b/es/authentication-personalization/personalization-setup.mdx @@ -0,0 +1,370 @@ +--- +title: "Configuración de personalización" +description: "Permite que los usuarios inicien sesión para una experiencia de documentación personalizada" +icon: "user-cog" +--- + +La personalización adapta tu documentación para cada usuario cuando inicia sesión. Por ejemplo, puedes autocompletar sus claves de API, mostrar contenido específico para su plan o rol, u ocultar secciones a las que no necesitan acceder. + +## Funciones de personalización + +Personaliza el contenido con estas capacidades de personalización. + +### Autorrelleno de claves de API + +Completa automáticamente los campos del área de pruebas de API con valores específicos del usuario devolviendo nombres de campo que coincidan en tus datos de usuario. Para que el autorrelleno funcione, los nombres de los campos en tus datos de usuario deben coincidir exactamente con los nombres del área de pruebas de API. + +### Contenido MDX dinámico + +Muestra contenido dinámico según información del usuario, como el nombre, el plan o la organización, usando la variable `user`. + +```jsx +Welcome back, {user.firstName}! Your {user.org?.plan} plan includes... +``` + +Consulta la sección [Formato de datos del usuario](es/#user-data-format) a continuación para ver ejemplos detallados y orientación de implementación. + +### Visibilidad de páginas + +Restringe qué páginas son visibles para tus usuarios agregando campos `groups` al frontmatter de tus páginas. De forma predeterminada, todas las páginas son visibles para todos los usuarios. + +Los usuarios solo verán las páginas de los `groups` a los que pertenecen. + +```mdx +--- +title: "Managing your users" +description: "Adding and removing users from your organization" +groups: ["admin"] +--- +``` + +## Formato de datos del usuario + +Al implementar la Personalización, tu sistema devuelve datos del usuario en un formato específico que habilita la personalización del contenido. Estos datos pueden enviarse como un objeto JSON en bruto o dentro de un JWT firmado, según tu método de intercambio (handshake). La estructura de los datos es la misma en ambos casos. + +```tsx +type User = { + expiresAt?: number; + groups?: string[]; + content?: Record; + apiPlaygroundInputs?: { + header?: Record; + query?: Record; + cookie?: Record; + server?: Record; + }; +}; +``` + + + Tiempo de expiración de la sesión en **segundos desde la época (epoch)**. Si el usuario carga una página después de este tiempo, sus datos almacenados se eliminan automáticamente y debe volver a autenticarse. + Para intercambios con JWT: Esto difiere del claim `exp` del JWT, que determina cuándo un JWT se considera inválido. Configura el claim `exp` del JWT con una duración corta (10 segundos o menos) por seguridad. Usa `expiresAt` para la duración real de la sesión (de horas a semanas). + + + + Lista de grupos a los que pertenece el usuario. Las páginas con `groups` coincidentes en su frontmatter son visibles para este usuario. + + **Ejemplo**: Un usuario con `groups: ["admin", "engineering"]` puede acceder a páginas etiquetadas con los grupos `admin` o `engineering`. + + + + Datos personalizados accesibles en tu contenido `MDX` mediante la variable `user`. Úsalos para personalización dinámica en toda tu documentación. + + **Ejemplo básico**: + + ```json + { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } + ``` + + **Uso en `MDX`**: + + ```mdx + Welcome back, {user.firstName}! Your {user.plan} plan includes... + ``` + + Con los datos de `user` del ejemplo, se renderizaría como: Welcome back, Ronan! Your Enterprise plan includes... + + **Renderizado condicional avanzado**: + + ```jsx + Authentication is an enterprise feature. { + user.org === undefined + ? <>To access this feature, first create an account at the Mintlify dashboard. + : user.org.plan !== 'enterprise' + ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See our pricing page for information about upgrading. + : <>To request this feature for your enterprise org, contact your admin. + } + ``` + + + La información en `user` solo está disponible para usuarios con sesión iniciada. Para usuarios cerrados, el valor de `user` será `{}`. Para evitar que la página falle para usuarios sin sesión, usa siempre encadenamiento opcional en los campos de `user`. Por ejemplo, `{user.org?.plan}`. + + + + + Valores específicos del usuario que rellenan previamente los campos del Área de pruebas de API. Ahorra tiempo a los usuarios al autocompletar sus datos cuando prueban APIs. + + **Ejemplo**: + + ```json + { + "header": { "X-API-Key": "user_api_key_123" }, + "server": { "subdomain": "foo" }, + "query": { "org_id": "12345" } + } + ``` + + Si un usuario realiza solicitudes en un subdominio específico, puedes enviar `{ server: { subdomain: 'foo' } }` como un campo `apiPlaygroundInputs`. Este valor se rellenará previamente en cualquier página de API con el valor de `subdomain`. + + Los campos `header`, `query` y `cookie` solo se rellenarán previamente si forman parte de tu [esquema de seguridad de OpenAPI](https://swagger.io/docs/specification/authentication/). Si un campo está en las secciones `Authorization` o `Server`, se rellenará previamente. Crear un parámetro de encabezado estándar llamado `Authorization` no habilitará esta función. + + +### Ejemplo de datos de usuario + +```json +{ + "expiresAt": 1735689600, + "groups": ["admin", "beta-users"], + "content": { + "firstName": "Jane", + "lastName": "Smith", + "company": "TechCorp", + "plan": "Enterprise", + "region": "us-west" + }, + "apiPlaygroundInputs": { + "header": { + "Authorization": "Bearer abc123", + "X-Org-ID": "techcorp" + }, + "server": { + "environment": "production", + "region": "us-west" + } + } +} +``` + +## Configuración de la personalización + +Selecciona el método de handshake que deseas configurar. + + + + ### Requisitos previos + + - Un sistema de inicio de sesión que pueda generar y firmar JWT + - Un servicio de backend que pueda crear URL de redirección + + ### Implementación + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Personalization**. + 3. Selecciona **JWT**. + 4. Ingresa la URL de tu flujo de inicio de sesión existente y selecciona **Save changes**. + 5. Selecciona **Generate new key**. + 6. Guarda tu clave de forma segura donde pueda accederla tu backend. + + + + Modifica tu flujo de inicio de sesión existente para incluir estos pasos después de que el usuario inicie sesión: + + - Crea un JWT que contenga la información del usuario autenticado en el formato `User`. Consulta la sección [User data format](es/#user-data-format) más arriba para obtener más información. + - Firma el JWT con la clave secreta usando el algoritmo ES256. + - Crea una URL de redirección de vuelta a tu documentación, incluyendo el JWT como hash. + + + + ### Ejemplo + + Tu documentación está alojada en `docs.foo.com`. Quieres que tu documentación esté separada de tu panel (o no tienes un panel) y habilitar la Personalización. + + Genera un secreto de JWT. Luego crea un endpoint de inicio de sesión en `https://foo.com/docs-login` que inicie un flujo de inicio de sesión hacia tu documentación. + + Después de verificar las credenciales del usuario: + + - Genera un JWT con los datos del usuario en el formato de Mintlify. + - Firma el JWT y redirige a `https://docs.foo.com#{SIGNED_JWT}`. + + ```ts + import * as jose from 'jose'; + import { Request, Response } from 'express'; + + const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; + + const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); + + export async function handleRequest(req: Request, res: Response) { + const user = { + expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), + groups: res.locals.user.groups, + content: { + firstName: res.locals.user.firstName, + lastName: res.locals.user.lastName, + }, + }; + + const jwt = await new jose.SignJWT(user) + .setProtectedHeader({ alg: 'ES256' }) + .setExpirationTime('10 s') + .sign(signingKey); + + return res.redirect(`https://docs.foo.com#${jwt}`); + } + ``` + + ### Conservar anclas de página + + Para redirigir a los usuarios a secciones específicas después del inicio de sesión, usa este formato de URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. + + **Ejemplo**: + + - URL original: `https://docs.foo.com/quickstart#step-one` + - URL de redirección: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` + + + + ### Requisitos previos + + - Un servidor OAuth que admita el flujo de código de autorización (Auth Code) con PKCE + - Capacidad para crear un endpoint de API accesible mediante tokens de acceso de OAuth + + ### Implementación + + + + Crea un endpoint de API que: + + - Acepte tokens de acceso de OAuth para la autenticación. + - Devuelva datos del usuario en el formato `User`. Consulta la sección [Formato de datos de usuario](es/#user-data-format) más arriba para obtener más información. + - Defina los scopes de acceso. + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Personalization**. + 3. Selecciona **OAuth** y configura estos campos: + + - **Authorization URL**: Tu endpoint de autorización de OAuth. + - **Client ID**: Tu identificador de cliente de OAuth 2.0. + - **Scopes**: Permisos a solicitar. Copia la cadena de scope **completa** (por ejemplo, para un scope como `provider.users.docs`, copia el `provider.users.docs` completo). Debe coincidir con los scopes del endpoint que configuraste en el primer paso. + - **Token URL**: Tu endpoint de intercambio de tokens de OAuth. + - **Info API URL**: Endpoint para obtener datos del usuario para la personalización. Creado en el primer paso. + + 4. Selecciona **Save changes** + + + + 1. Copia la **Redirect URL** desde tu [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Agrega esta URL como una URL de redirección autorizada en la configuración de tu servidor OAuth. + + + + ### Ejemplo + + Tu documentación está alojada en `foo.com/docs` y tienes un servidor OAuth existente que admite el flujo PKCE. Quieres personalizar tu documentación según los datos del usuario. + + **Crea un endpoint de información de usuario** en `api.foo.com/docs/user-info`, que requiera un token de acceso de OAuth con el scope `provider.users.docs` y responda con los datos personalizados del usuario: + + ```json + { + "content": { + "firstName": "Jane", + "lastName": "Doe" + }, + "groups": ["engineering", "admin"] + } + ``` + + **Configura los detalles de tu servidor OAuth** en tu panel: + + - **Authorization URL**: `https://auth.foo.com/authorization` + - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` + - **Scopes**: `['docs-user-info']` + - **Token URL**: `https://auth.foo.com/exchange` + - **Info API URL**: `https://api.foo.com/docs/user-info` + + **Configura tu servidor OAuth** para permitir redirecciones a tu URL de callback. + + + + ### Requisitos previos + + - Un panel o portal de usuario con autenticación de sesión basada en cookies. + - Capacidad para crear un endpoint de API en el mismo origen o subdominio que tu panel. + - Si tu panel está en `foo.com`, la **URL de la API** debe comenzar con `foo.com` o `*.foo.com`. + - Si tu panel está en `dash.foo.com`, la **URL de la API** debe comenzar con `dash.foo.com` o `*.dash.foo.com`. + - Tu documentación está alojada en el mismo dominio o subdominio que tu panel. + - Si tu panel está en `foo.com`, tu **documentación** debe estar alojada en `foo.com` o `*.foo.com`. + - Si tu panel está en `*.foo.com`, tu **documentación** debe estar alojada en `foo.com` o `*.foo.com`. + + ### Implementación + + + + Crea un endpoint de API que: + + - Use tu autenticación de sesión existente para identificar a los usuarios + - Devuelva datos de usuario en el formato `User` (consulta la sección [Formato de datos de usuario](es/#user-data-format) anterior) + - Si el dominio de la API y el dominio de la documentación **no coinciden exactamente**: + + - Agrega el dominio de la documentación al encabezado `Access-Control-Allow-Origin` de tu API (no debe ser `*`). + - Establece el encabezado `Access-Control-Allow-Credentials` de tu API en `true`. + + + Habilita los encabezados CORS solo en este endpoint específico, no en toda tu API del panel. + + + + + 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Selecciona **Personalization**. + 3. Selecciona **Shared Session**. + 4. Ingresa tu **Info API URL**, que es el endpoint del primer paso. + 5. Ingresa tu **Login URL**, donde los usuarios inician sesión en tu panel. + 6. Selecciona **Save changes**. + + + + ### Ejemplos + + #### Panel en subdominio, documentación en subdominio + + Tienes un panel en `dash.foo.com`, que utiliza autenticación de sesión basada en cookies. Las rutas de la API de tu panel están alojadas en `dash.foo.com/api`. Quieres configurar la personalización para tu documentación alojada en `docs.foo.com`. + + Proceso de configuración: + + 1. Crea el endpoint `dash.foo.com/api/docs/user-info` que identifique a los usuarios mediante autenticación de sesión y responda con sus datos de usuario. + 2. Agrega encabezados CORS solo para esta ruta: + - `Access-Control-Allow-Origin`: `https://docs.foo.com` + - `Access-Control-Allow-Credentials`: `true` + 3. Configura la URL de la API en la configuración de autenticación: `https://dash.foo.com/api/docs/user-info`. + + #### Panel en subdominio, documentación en raíz + + Tienes un panel en `dash.foo.com`, que utiliza autenticación de sesión basada en cookies. Las rutas de la API de tu panel están alojadas en `dash.foo.com/api`. Quieres configurar la personalización para tu documentación alojada en `foo.com/docs`. + + Proceso de configuración: + + 1. Crea el endpoint `dash.foo.com/api/docs/user-info` que identifique a los usuarios mediante autenticación de sesión y responda con sus datos de usuario. + 2. Agrega encabezados CORS solo para esta ruta: + - `Access-Control-Allow-Origin`: `https://foo.com` + - `Access-Control-Allow-Credentials`: `true` + 3. Configura la URL de la API en la configuración de autenticación: `https://dash.foo.com/api/docs/user-info`. + + #### Panel en raíz, documentación en raíz + + Tienes un panel en `foo.com/dashboard`, que utiliza autenticación de sesión basada en cookies. Las rutas de la API de tu panel están alojadas en `foo.com/api`. Quieres configurar la personalización para tu documentación alojada en `foo.com/docs`. + + Proceso de configuración: + + 1. Crea el endpoint `foo.com/api/docs/user-info` que identifique a los usuarios mediante autenticación de sesión y responda con sus datos de usuario. + 2. Configura la URL de la API en la configuración de autenticación: `https://foo.com/api/docs/user-info` + + + No se necesita configuración de CORS, ya que el panel y la documentación comparten el mismo dominio. + + + diff --git a/es/changelog.mdx b/es/changelog.mdx new file mode 100644 index 000000000..2896b88dc --- /dev/null +++ b/es/changelog.mdx @@ -0,0 +1,652 @@ +--- +title: "Actualizaciones del producto" +description: "Nuevas actualizaciones y mejoras" +rss: true +noindex: true +--- + + + ## Optimizaciones de rendimiento y compilación + + - La transpilación de MDX ahora se realiza en el momento del despliegue en lugar de en cada carga de página en entornos serverless de NextJS sin caché, mejorando el tiempo hasta el primer byte para páginas no cacheadas. + - El hashing basado en contenido evita la retranspilación cuando MDX no ha cambiado, reduciendo los tiempos del flujo de actualización en ~50% para clientes con grandes volúmenes de páginas (los despliegues de más de 5 minutos deberían reducirse aproximadamente a la mitad) + - La vista de despliegues de previsualización en el panel ahora es más rápida gracias a índices de base de datos y paralelización de consultas en nuestro backend + - Redujimos el tamaño de página eliminando datos duplicados de `navigation` en la carga útil `rsc` de cada página; las mejoras de rendimiento son más notables con muchos volúmenes de páginas o estructuras de navegación complejas + - Un prefetching más agresivo permite cargas instantáneas de página con mayor frecuencia + + ## Mejoras en el API playground y OpenAPI + + - La conversión de OpenAPI a MCP se trasladó al backend, lo que permite que los servidores MCP alojados contengan herramientas (pronto habrá documentación y opciones de configuración más claras) + - Se agregó compatibilidad con Ruby al API playground + - Agregamos una función para que ahora puedas [especificar páginas de API usando solo tu docs.json](/es/api-playground/openapi-setup#auto-populate-api-pages) sin crear nuevos archivos MDX. + - Compatibilidad con páginas de [`webhook`](/es/api-playground/openapi-setup#webhooks) en la navegación de la documentación a partir de especificaciones OpenAPI + - Contexto del modelo de IA optimizado eliminando los anclajes de los enlaces de Markdown al navegar a Anthropic, OpenAI u otros proveedores + + ## Mejoras del Editor web + + - La creación y el cambio de nombre de archivos ahora guardan los cambios al hacer clic fuera, en lugar de requerir presionar la tecla Enter + - Se corrigió la navegación de ramas donde cambiar la URL a una rama específica redirigía a la última rama activa en lugar del destino previsto + - Se codifican correctamente en la URL los títulos de ramas que contienen `/` para evitar rupturas de navegación + - Se corrigió el atajo de enlace `Ctrl+K` en el Editor del panel de monorepositorio, que anteponía la ruta del repositorio de docs y creaba enlaces rotos + + ## Analíticas e integraciones con LLM + + - Compatibilidad con `llms.txt` y `llms-full.txt` personalizados: agrégalos a la raíz del repositorio de docs para servirlos en los endpoints `/llms.txt` y `/llms-full.txt` para la personalización de LLM + - Se agregó la [integración de analíticas de Hightouch](/es/integrations/analytics/hightouch#hightouch) + - Seguimiento de analíticas del Menú contextual mejorado (visualización en el panel próximamente) + - Se agregaron pruebas e2e para `llms.txt` y `llms-full.txt` para garantizar su correcta entrega + + ## Mejoras de componentes y estilos + + - Compatibilidad con classnames personalizados en etiquetas `h{1-4}` para aplicar estilos de encabezado personalizados + - Se corrigió que las etiquetas `h{1-4}` se renderizaran como componentes `Heading` con chips en el modo de página personalizada + - Se agregaron selectores CSS a [breadcrumbs](/es/navigation#breadcrumbs) para segmentación CSS personalizada + - Se corrigieron imágenes de Open Graph estiradas analizando dimensiones para mantener proporciones a 56px de altura + - Se corrigió `VSCode` a `VS Code` en el Menú contextual cuando está habilitado + - Se corrigió que los encabezados dentro de componentes personalizados aparecieran en la tabla de contenidos junto con los encabezados semánticos + + ## Correcciones de errores y confiabilidad + + - Se corrigieron problemas de renderizado de PDF con ciertos títulos de página, saneando caracteres que causaban errores de generación + - Se resolvió el error de la CLI `Cannot convert undefined or null to object` al encontrar archivos JSON de OpenAPI vacíos + - Se corrigió que los metatags de Open Graph personalizados en `docs.json` fueran sobrescritos por los generados + - Se corrigieron los clics del botón del feed RSS al aterrizar en enlaces de anclaje, usando origin + pathname para los enlaces RSS + - Se mejoró la velocidad de descarga de la CLI eliminando sourcemaps + + ## Mejoras técnicas + + - Se agregaron pruebas visuales al pipeline de CI para detección temprana de regresiones + - Se mejoraron el manejo de errores y las capacidades de depuración + - Cobertura de pruebas integral para nuevas funciones y casos borde + + + + ## Mejoras en la autenticación + + - Acceso público a nivel de grupo: haz públicos grupos completos de páginas mediante `docs.json` para no necesitar `public: true` en cada página ([más información](https://mintlify.com/docs/authentication-personalization/authentication-setup#group-level)) + - Compatibilidad con [`logoutURL` en la configuración de OAuth](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation-3) para eliminar cookies upstream y completar el cierre de sesión + - En caso de errores de OAuth, los usuarios se redirigen a la `logoutURL` especificada para reiniciar el flujo de autenticación + - Se corrigió un destello de error 500 durante los flujos OAuth/JWT antes del callback + - Eliminación automática de `https://` de las URL en la configuración de autenticación OAuth/JWT para evitar errores de configuración + + ## Mejoras en el API playground + + - Nuevo [endpoint de Search API](https://mintlify.com/docs/api-reference/assistant/search) para que puedas crear agentes y servidores MCP sobre tu documentación + - Los archivos `openapi` y `asyncapi` ahora se sirven en sus rutas especificadas (p. ej., `https://mydocsurl.extension/{openapi-or-file-name}.json`) + - Ahora puedes usar el [campo `x-mint` en tus archivos OpenAPI](https://mintlify.com/docs/api-playground/openapi-setup#x-mint-extension) para sobrescribir campos generados, personalizar el contenido del preámbulo o cambiar las URL de los endpoints en los ejemplos de código + - [`x-mcp` ahora es `x-mint.mcp`](https://mintlify.com/docs/api-playground/openapi-setup#mcp) en configuraciones de OpenAPI para controlar qué rutas se exponen como herramientas MCP + + ## Actualizaciones del Assistant + + - Se corrigió un problema por el que el menú de acciones (con opciones como copiar y pulgar arriba) de los mensajes antiguos desaparecía cuando llegaban nuevos mensajes en streaming + - Se corrigió la accesibilidad de páginas anidadas `/mcp/...` después del [lanzamiento de servidores MCP alojados](https://mintlify.com/docs/ai/model-context-protocol#accessing-your-mcp-server) de la semana pasada + + ## Rendimiento y confiabilidad + + - Todos los recursos de imagen y video presentes en tu repo de docs ahora se sirven en la ruta adecuada en tu dominio. Por ejemplo, si tienes `/assets/marketing/my-logo.png` en tu repo, estará disponible en `https://mydocsurl.extension/assets/marketing/my-logo.png`. + - El campo de correo electrónico en el inicio de sesión del panel de Mintlify ahora tiene autofocus para que puedas empezar a escribir de inmediato (mejora de calidad de vida) + - Tanto dominios personalizados como subdominios en Redis para mejorar el rendimiento en los tiempos de carga de navegación (~50 ms de reducción de latencia) + - Se agregó lógica de reintento para exportaciones a PDF para mejorar la confiabilidad + - Se corrigió que el popup de consentimiento de cookies reapareciera después de aceptar o descartar: ahora se respeta la primera selección + - Se corrigió copiar una página al portapapeles en Safari especificando un `type` MIME en `navigator.write` + + ## Mejoras técnicas + + - Correcciones de la CLI para Windows y pnpm, además de pruebas de CI para prevenir regresiones + - Salida de registro de errores mejorada: una mejora de calidad de vida para nuestro equipo de ingeniería al depurar + - Correcciones menores en la acción de CI de enlaces rotos cuando faltan archivos de `contentDirectory` + - Se corrigió una regresión causada por las correcciones de la vista previa protegida por autenticación de la semana pasada, donde la pestaña activa no se establecía correctamente en la interfaz de navegación + - Se corrigió que el color de fondo claro del tema no se aplicara a los íconos de las pestañas activas + - Se corrigió un problema por el que cambiar el tipo de autenticación en el panel se actualizaba y luego volvía al tipo guardado previamente: ahora la nueva selección persiste después de guardar + - Mejoras internas de DX para clientes empresariales con bibliotecas de UI personalizadas: ahora nos es más fácil incluir tus componentes y atender solicitudes en plazos más cortos + + + + ## Mejoras de autenticación + + - Mejoras en el desarrollo local de autenticación, lo que permite desarrollar más rápido funciones de autenticación y corregir errores en esta área del producto + - Despliegues de vista previa ahora disponibles para sitios protegidos por autenticación + - Se corrigió el comportamiento de redirección para retornar correctamente a los usuarios a su página original después de autenticarse + - Se corrigió la visualización del botón de cierre de sesión para la autenticación completa (antes solo funcionaba para la Autenticación parcial) + + ## Mejoras del API playground + + - Se corrigió la carga de archivos `multipart/form-data` en el API playground + - Se corrigió el comportamiento de los enlaces ancla para que, al hacer clic, actualicen la URL sin desplazarse al inicio de la página + - Se corrigieron problemas de enlaces ancla en pestañas anidadas + + ## Actualizaciones del Assistant + + - Nueva Assistant API para integrarlo en tus propios productos, compatible con AI SDK + - Se agregó un botón para copiar en las respuestas del chat + - Se corrigió un problema al reintentar mensajes en el Assistant + - Mejoras en el prompt predeterminado del Assistant para que sea menos verboso por defecto + + ## Rendimiento y confiabilidad + + - La búsqueda ahora se siente más ágil y precisa al abortar solicitudes con debounce mientras escribes + - Aprovisionamiento de recursos para una nueva CDN: se espera que los tiempos de carga de imágenes y páginas mejoren pronto + - Se corrigieron errores al renderizar diagramas Mermaid complejos como gráficos GANTT + - Se corrigieron errores de la CLI en Windows para mejorar la estabilidad y se agregaron pruebas para prevenir regresiones + + ## Mejoras técnicas + + - Se agregó OpenTelemetry para trazas en la aplicación de NextJS a fin de mejorar el tiempo hasta el primer byte para los clientes + - Migramos de Octokit a GitHub API Client para mejorar la latencia en la experiencia del Editor web + - Se corrigieron etiquetas meta duplicadas para OpenGraph + - Se actualizó MongoDB de la versión 6 a la 7 para mejorar el rendimiento y añadir nuevas funciones + + + + ## Slack app + + - Acceso sin fricción: el bot responde a DMs, @menciones y cualquier pregunta en tu canal `#ask-ai` + - Configuración con un clic: instálalo directamente desde tu panel de Mintlify en segundos + - Respuestas contextuales: busca en toda tu documentación para proporcionar respuestas relevantes y precisas + - Reduce interrupciones de soporte: convierte las preguntas diarias en respuestas instantáneas de autoservicio + + Obtén más información en nuestra [guía de Slack app](/es/ai/slack-app). + + ## Servidores MCP alojados + + Implementa servidores alojados de Model Context Protocol (MCP) directamente a través de Mintlify para integrarte con herramientas de IA como Claude, Cursor y otras. Más información en nuestra [guía de MCP](/es/ai/model-context-protocol). + + Ayuda a los usuarios a conectar rápidamente tu servidor MCP con Cursor o VS Code desde cualquier página de tu documentación mediante el Menú contextual. Consulta [Menú contextual](/es/ai/contextual-menu) para más información. + + ## Mejoras en bloques de código + + - Resaltado de sintaxis mejorado + - Se agregaron más opciones de personalización, incluidas el modo enfoque, bloques de código expandibles, adaptación a modo oscuro y claro, menú desplegable de lenguaje, numeración de líneas e íconos + + + + ## Actualizaciones del Assistant de IA + + - Mayor precisión mediante RAG agente con llamadas a herramientas + - Proporciona enlaces navegables a las páginas de referencia para que los usuarios vayan directamente a la fuente de las respuestas + - Atajo para copiar ejemplos de código generados por el Assistant + - Atajo "Ask AI" en bloques de código de la documentación para generar explicaciones del Assistant + + Obtén más información en la [documentación del Assistant](/es/guides/assistant). + + ## Registros de cambios suscribibles + + - Genera automáticamente un feed RSS a partir de páginas de registro de cambios + - Integra actualizaciones habilitadas por RSS con Slack, correo electrónico y otras herramientas + + Más información en nuestra nueva [guía de Changelog](/es/guides/changelogs) + + + + ## Actualizaciones de estabilidad del API playground + + - Busca para encontrar un endpoint + - Indica un endpoint obsoleto con una etiqueta + - Oculta páginas de API autogeneradas de la navegación + - Sube archivos multipart o de formulario + + Más información en la [documentación del API playground.](/es/api-playground/) + + ## `mint update` + + Ahora puedes usar `mint update` para actualizar tu CLI. + + + + ## Editor web 3.0 + + + ![Webeditor3 Jpe](/images/webeditor3.jpeg) + + + Se renovó por completo la usabilidad del editor WYSIWYG. + + **Mejoras importantes** + + - Busca nombres de archivos con el atajo ⌘ + P + - Las páginas cargan 10 veces más rápido + - Cargas más rápidas al buscar una rama + - Pestaña de opciones de página para configurar el diseño, el título y los metadatos para SEO + - Barra flotante de herramientas al resaltar texto + + **Correcciones adicionales** + + - Corregido el margen superior de los componentes del registro de cambios + - Mayor fiabilidad del comportamiento del clic derecho + - Después de publicar, permanecerás en la misma página en lugar de ir a un estado vacío + - Colores estandarizados en los iconos de archivos + - Mayor fiabilidad tras seleccionar ramas nuevas varias veces seguidas + - Se eliminó el modo Diff + - Más consistencia al crear una carpeta nueva desde el menú desplegable + - Se corrigió que las citas en bloque crearan más citas en bloque al intentar deseleccionarlas + + ## Traducciones con IA en beta + + + ![AI Translations graphic](/images/changelog/translations.png) + + + Traduce toda tu documentación con IA. [Más información.](es/navigation#localization) + + ## Exportar documentación a PDF en beta + + Exporta toda tu documentación, un subdirectorio o una sola página como PDF. + + ## Compatibilidad con hooks de React + + Aporta interactividad a tu documentación. Todos los hooks estándar de React están disponibles automáticamente en tus archivos MDX. [Más información.](es/react-components) + + + + ## Generador de servidores MCP + + + ![screenshot of MCP server generator](/images/changelog/mcpgenerator.png) + + + Genera servidores MCP para que las aplicaciones de IA puedan interactuar con tu documentación o APIs. El contenido escrito se genera automáticamente como un servidor MCP y puedes generar un servidor MCP desde tu especificación de OpenAPI con un solo clic. + Consulta la [documentación para empezar con MCP.](/es/ai/model-context-protocol) + + ## Mejoras + + - Etiqueta las actualizaciones del registro de cambios para que los usuarios finales puedan filtrarlas + - Sonnet-3.7 compatible con AI Chat. Configura tu modelo preferido desde el panel + - Cambia el nombre de tu despliegue directamente en los ajustes del panel + + ## Correcciones de errores + + - Se corrigieron las imágenes OG + - Se corrigió la inconsistencia de estilo del icono para anclas sin contenedor + - Ajustes de estilo menores en el borde del panel para mejor respuesta en móvil-tableta-escritorio + - Muestra ejemplos de código incluso en modo simple para el API playground + - Compatibilidad con el atajo "command + k" para buscar en el editor web + - Los bloques de código dentro de los callouts se expanden para ocupar todo el ancho del área del callout + + + + ## Nuevo esquema de configuración `docs.json` + + + ![docs.json screenshot](/images/changelog/docsjson.png) + + + Hemos introducido un nuevo esquema `docs.json` como reemplazo de `mint.json`, para admitir un mejor versionado multinivel, facilitar la comprensión visual y usar una terminología más coherente. Para obtener más información sobre los cambios, [consulta nuestro blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json). + + Actualiza de `mint.json` a `docs.json` con los siguientes pasos: + + 1. Asegúrate de tener la última versión de la CLI + + ```bash + npm i mint@latest -g + ``` + + 1. En tu repositorio de documentación, ejecuta + + ```bash + mint upgrade + ``` + + 1. Elimina tu antiguo archivo `mint.json` y sube tus cambios + + ## Checks de CI + + Ejecuta lint automáticamente en tu documentación para encontrar enlaces rotos, detectar problemas de ortografía y gramática, o aplicar estilos de escritura con tu propia configuración de Vale. Más información en nuestras [docs](es/settings/ci). + + ## Compatibilidad .md para LLMs + + Todas las páginas de documentación ahora están disponibles automáticamente como archivos Markdown en texto plano: solo agrega `.md` a la URL. Esto facilita que los LLMs ingieran páginas individuales de tu documentación. + + ## Más temas + + + ![graphic with text "Themes v2"](/images/changelog/themes.png) + + + Nuevos [temas preconstruidos](es/themes) para modificar el look & feel de tu documentación. Configúralos a través de tu [archivo docs.json](es/settings). + + Ahora disponibles: + + - Maple + - Palm + - Willow + + ## Otras mejoras + + - [Guía de redacción técnica:](https://mintlify.com/guides/introduction) Buenas prácticas para escribir documentación técnica, incluida la investigación de audiencia, tipos de contenido y consejos de redacción. + - [Componente Dropdown](es/navigation#dropdowns): Organiza la navegación con un menú desplegable, además de pestañas y anclas. + - [AI syntax fixer](https://x.com/ricardonunez_io/status/1892334887644123192): El Editor web detectará si hay un error de análisis y usará IA para sugerir correcciones. + + + + ## Mejoras del Assistant (asistente de IA) + + - Nueva interfaz con página de chat dedicada y prompts prellenados + - Mejoras de estabilidad, p. ej., correcciones de errores al editar el archivo equivocado o ninguno + - Conocimiento más sólido para agregar y editar componentes + - Edición mejorada del archivo `docs.json` + + ## Autenticación parcial + + Personaliza el acceso a cualquier página o sección de contenido según los permisos del usuario. Permite conectarte con tu propio sistema de autenticación. + + ## API playground renovado + + Hemos renovado el diseño y el rendimiento del [API playground](/es/api-playground/). Las actualizaciones incluyen: + + - Expansión de detalles más sencilla para obtener una vista general de un campo + - Diseño anidado más intuitivo, p. ej., agregar o eliminar elementos + - Tiempos de respuesta más rápidos + + ## Mejoras de calidad + + - Compatibilidad para exigir autenticación para acceder a despliegues de vista previa + + + + ## Autenticación + + + ![Authentication screenshot](/images/changelog/authentication.png) + + + Haz privada tu documentación configurando autenticación mediante JWT, OAuth o una contraseña universal. Con esta privacidad, puedes crear una base de conocimiento interna o evitar que la competencia vea tu documentación. + + + + ## Redactor de IA + + + ![AI Assistant](/images/changelog/ai-assistant.jpg) + + + Ahora puedes pedirle a la IA que haga cambios en tu documentación, con el contexto de toda la documentación existente. Escribe una indicación y el redactor propondrá cambios generando un pull request. + + ## Mejora de la integración con GitLab + + Hemos mejorado la compatibilidad de sincronización con GitLab, habilitando actualizaciones automáticas y despliegues de vista previa. Consulta nuestra [documentación sobre GitLab](/es/settings/gitlab) para empezar. + + ## Editor web + + + ![Web Editor](/images/changelog/webeditor.jpg) + + + Hemos renovado nuestro Editor web para que ahora puedas actualizar la documentación con una experiencia totalmente WYSIWYG, manteniendo la sincronización con Markdown. + + Consulta nuestra [documentación para comenzar con el Editor web](/es/editor). + + ## Compatibilidad con /llms.txt + + + ![llms.txt support](/images/changelog/llms.jpg) + + + Todas las instancias de documentación ahora se alojan automáticamente en /llms.txt y /llms-full.txt para que los LLM puedan ingerir tu documentación con facilidad. Para más información, consulta la [documentación sobre el nuevo estándar llms.txt.](https://llmstxt.org) + + ## Localización + + Ahora puedes localizar tu documentación, de forma similar al versionado. Agrega un `locale` a una versión y el contenido fijo en Mintlify, como “Was this page helpful?”, también coincidirá con ese locale. + + ### Mejoras de calidad + + - Devolver resultados de chat y búsqueda basados en la versión que el usuario está leyendo + - Autenticar a los usuarios con OAuth, además de JWT o tokens de sesión compartida. + + + + ## Registro de cambios + + Lanzamos un nuevo [Componente Update](/es/components/update) para facilitar la visualización y comunicación de actualizaciones (como esta) a tus usuarios. + + + ![Changelog](/images/changelog/changelog.jpg) + + + ## Resaltado de líneas de código + + Ahora puedes resaltar líneas de código en tu documentación para enfatizar y llamar la atención sobre partes importantes añadiendo un comentario especial después del identificador del lenguaje. Usa llaves `{}` y especifica números de línea o rangos separados por comas. + + ```javascript Line Highlighting Example {1,3-5} + const greeting = "Hello, World!"; + function sayHello() { + console.log(greeting); + } + sayHello(); + ``` + + ````mdx + ```javascript Line Highlighting Example {1,3-5} + const greeting = "Hello, World!"; + function sayHello() { + console.log(greeting); + } + sayHello(); + ``` + ```` + + ## Bloques de código en modo claro + + Los bloques de código ahora tienen una variante en modo claro que puedes habilitar añadiendo lo siguiente a tu `docs.json`: + + ```json + "codeBlock": { + "mode": "auto" + } + ``` + + ## Footer avanzado + + + ![Advanced Footer](/images/changelog/advanced-footer.gif) + + + Ahora puedes agregar más enlaces al footer estándar. Esta mejora + aporta más consistencia entre las landing pages y la documentación, o mayor personalización + si quieres destacar páginas específicas como redes sociales o páginas de estado. + + ## Filtrar la búsqueda según el usuario actual + + Cuando la Personalización está habilitada, los resultados de búsqueda se filtran según el usuario que ha iniciado sesión para que solo vea el contenido relevante. + + ## Prompts personalizados para el chat de IA + + Ahora puedes personalizar los prompts para el chat de IA. Ponte en contacto con [support](mailto:support@mintlify.com) si deseas personalizar los prompts. + + ## Mejoras en el panel + + - Se añadió la opción de cambiar el dominio personalizado a /docs directamente desde la configuración del panel. + - Se unificaron las páginas de inicio de sesión y registro para reducir la fricción y la confusión. + - Se implementó el flujo de inicio de sesión por descubrimiento para que los usuarios que son miembros de varias organizaciones puedan cambiar entre ellas. + - Se añadió el inicio de sesión con Google OAuth. + - Se añadió la opción de agregar un nuevo despliegue desde la configuración del panel. + + ## Correcciones de errores + + - Ahora se pueden usar barras iniciales en la navegación. + - Ahora se pueden editar archivos CSS y JS en el Editor web. + - Se corrigió que `suggestEdit` no apareciera incluso cuando estaba habilitado. + - Se corrigió la navegación por teclado para Search y Chat, de modo que ahora puedes usar las teclas de flecha arriba y abajo para recorrer los resultados. + - No permitir que los motores de búsqueda rastreen páginas protegidas por autenticación de usuario. + - Revalidar la caché cuando se elimina una organización. + - Ahora usamos el analizador Scalar OpenAPI para procesar definiciones de OpenAPI, lo que mejora el rendimiento, corrige problemas de parseo y ofrece mejores mensajes de error. + - Ahora se admiten descripciones de nivel superior en las páginas de referencia de API autogeneradas a partir de definiciones de OpenAPI. + - Agregada compatibilidad con estilo inline para iconos. + - Se corrigió el pop-in del CSS personalizado en la documentación. + - Mostrar correctamente el estilo de código en línea junto con enlaces. + - Mantener la posición de desplazamiento cuando haces clic en el botón de retroceso del navegador. + + + + ## Fuentes personalizadas + + + ![Custom Fonts](/images/changelog/custom-fonts.jpeg) + + + Personaliza la tipografía de tu documentación con tu propia fuente alojada en un CDN o eligiendo entre Google Fonts para que tu doc se alinee con tu marca. + + ## Imágenes en componentes Card + + Agrega la propiedad `img` a una card para mostrar una imagen en la parte superior. Obtén más información [aquí](/es/components/cards#image-card). + + ## Mejoras en la velocidad de actualización + + + ![Performance Improvements](/images/changelog/performance-improvements.png) + + + Para proyectos grandes (~3,000 archivos), el paso de descarga para las actualizaciones de la documentación ahora es + \~440x más rápido: una reducción del 99.8% en el tiempo. En general, las descargas de archivos durante + las actualizaciones ahora son ~5.5x más rápidas: una reducción del 81.8% en el tiempo. + + ## Mejoras de SEO + + + ![SEO Improvements](/images/changelog/seo-improvements.jpeg) + + + Corregimos el diseño móvil y de escritorio de nuestra documentación para que sea más compatible con SEO, incluyendo la adición de etiquetas aria adecuadas a la barra de navegación y a los elementos de alternancia. + + ## Mejoras en el panel + + - Migración a App Router en el panel. + - La analítica de búsqueda ahora está disponible en el panel. + - Se agregó la funcionalidad para eliminar una organización en el panel. + - Se lanzó la interfaz de conexión con GitLab. + - Corrección de datos analíticos incorrectos. + - Ahora los complementos se pueden comprar directamente desde el panel. + + ## Correcciones de errores + + - Se corrigió un error por el cual la barra superior no se extendía al ancho de la pantalla cuando estaba en modo personalizado y el diseño de la barra lateral era `sidenav`. + - Corrección del posicionamiento relativo del widget de IA. + + ## Más + + - **Solución de problemas para páginas de API**: las páginas de API pueden ser complejas, por lo que enumeramos + problemas comunes para ayudarte a resolverlos rápidamente — + [Lee la documentación](/es/api-playground/troubleshooting) + + + + ## Páginas de referencia de OpenAPI + + - Los endpoints definidos por OpenAPI que son complejos y recursivos ahora son un 98% + más pequeños. + - Ahora mostramos + [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/) + en las páginas de OpenAPI. + + ## Carga de archivos en el API playground + + De forma predeterminada, las solicitudes del API playground pasan por un proxy de Mintlify. Ahora puedes usar + `disableProxy` para desactivar este comportamiento y admitir tipos de solicitud como + la carga de archivos. + + - [Más información sobre configuraciones de API](es/settings#api-configurations) + + ## Mejoras de SEO en móviles + + Corregimos el diseño móvil de nuestra documentación para que sea más compatible con SEO, + incluyendo la adición de etiquetas aria adecuadas a los elementos. + + ## Formulario de soporte + + Agregamos un formulario de soporte más detallado al panel de Mintlify. Ahora puedes + enviar un formulario para ponerte en contacto con nosotros. + + ## Correcciones de errores + + - Se corrigió un error en la funcionalidad de integración con Segment. + - Ahora mostramos mensajes de error más granulares para permisos de GitHub al + interactuar con el editor. + - Se corrigieron errores por los que la navegación no se expandía correctamente cuando se usaba un enlace directo. + + + + ## Widget de IA + + + ![AI Widget](/images/changelog/widget.png) + + + Para usuarios `Pro`, presentamos Mintlify Widget, una extensión de tu documentación para + responder las preguntas de tus usuarios cuando y donde las hagan. Puedes agregar este + chatbot con IA a cualquier página web: tu página de inicio, dentro de tu producto o + en tus páginas de documentación existentes. + + - [Lee el anuncio en el blog](https://mintlify.com/blog/widget) + + ## Plan Pro + + También actualizamos nuestros planes de precios para ofrecer mayor personalización y escalabilidad. + + - [Lee el anuncio en el blog](https://mintlify.com/blog/pro-plan) + + ## Sincronización de ejemplos de código en el API playground + + Cuando navegas por la documentación de API, el ejemplo de código seleccionado ahora se sincroniza entre tus páginas. + + ## Insights + + Actualmente en beta, esta función resume preguntas y patrones comunes de los usuarios + en informes fáciles de digerir, con sugerencias impulsadas por IA sobre cómo mejorar tu + producto. + + + + ## Aspectos destacados de la semana de lanzamiento + + - Temas: Personaliza el estilo con temas preconfigurados. Solo agrega el tema Quill, Prism o Venus a tu archivo `docs.json` y se actualizará el estilo de tu documentación. + - Search V2: consulta directamente descripciones y títulos de endpoints de OpenAPI para llegar a las páginas de Referencia de API, elimina páginas ocultas de los resultados y aprovecha nuestra barra de búsqueda con UI actualizada. + - Ramificación en el Editor web: crea ramas en nuestro Editor web sin un IDE. + - Personalización de usuario: autentica usuarios con Shared Session o JWT para mostrarles contenido personalizado, como autocompletar claves de API o mostrar contenido específico para clientes. + - Mejoras de automatización de OpenAPI: para autopoblar páginas del API playground, puedes agregar un campo `openapi` a un objeto en los arrays de tabs o anchors en el `docs.json`. + + + + ## Okta SSO + + Ahora admitimos inicio de sesión mediante Okta SAML y OIDC. + + ## Mintlify REST API + + Activa actualizaciones de tu documentación de forma programática. + + + + ## Modo personalizado + + Agrega una configuración a los metadatos para eliminar todos los elementos excepto la barra superior. + Ejemplos de uso: + + - Crea una página de aterrizaje global personalizada con componentes personalizados + - Agrega videos a pantalla completa o galerías de imágenes + - Inserta elementos de demostración iFrame personalizados para añadir interactividad a tu documentación + + Revisa nuestra [documentación de Custom Mode](es/pages#custom-mode). + + + + ## Mintlify MDX para VSCode + + Inserta snippets de nuestros componentes y avisos preconstruidos sin salir de VSCode. [Instala la extensión aquí](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). + + + + ## Mejoras de calidad + + - Mejoras del panel: visualiza registros de actualizaciones para ver qué cambió y el estado de una actualización, alterna entre proyectos de Mintlify para administrar despliegues + - Versionado con tabs totalmente compatible + - Redirecciones con comodín ahora compatibles + - Detección de errores en la CLI: ahora mostramos la posición del frontmatter no válido cuando hay problemas de parsing durante el desarrollo local + + + + ## Aspectos destacados de la semana de lanzamiento + + - Despliegues de vista previa: cuando creas un pull request, generaremos un enlace único que muestra una vista previa en vivo de cómo se ve tu documentación en producción. Puedes compartir este enlace con tus compañeros de equipo. + - Snippets V2: ahora admitimos componentes y variables totalmente reutilizables para los snippets. + - Motor MDX de código abierto: exponemos dos APIs —getCompiledMdx y MDXComponent— para que puedas acceder al markdown de Mintlify y al resaltado de sintaxis de código. [Las contribuciones al proyecto](https://github.com/mintlify/mdx) son bienvenidas. + - Insights de chat de IA: segmenta el historial de chat por fecha y aumenta la cuota de AI Chat desde el panel; también puedes ver con qué frecuencia aparece una consulta específica. + diff --git a/es/code.mdx b/es/code.mdx new file mode 100644 index 000000000..45d9e7246 --- /dev/null +++ b/es/code.mdx @@ -0,0 +1,337 @@ +--- +title: "Código" +description: "Mostrar código en línea y bloques de código" +icon: "code" +--- + +## Agregar ejemplos de código + +Puedes agregar snippets en línea o bloques de código. Los bloques de código admiten opciones meta para el resaltado de sintaxis, títulos, resaltado de líneas, íconos y más. + +### Código en línea + +Para indicar que una `palabra` o `frase` es código, enciérrala entre comillas invertidas (\`). + +```mdx +To denote a `word` or `phrase` as code, enclose it in backticks (`). +``` + +### Bloques de código + +Usa [bloques de código con vallas](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) encerrando el código entre tres comillas invertidas. Los bloques de código se pueden copiar y, si tienes el Assistant habilitado, los usuarios pueden pedirle a la IA que explique el código. + +Especifica el lenguaje de programación para el resaltado de sintaxis y para habilitar las opciones meta. Agrega cualquier opción meta, como un título o un ícono, después del lenguaje. + +```java HelloWorld.java lines icon="java" +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + +````mdx +```java HelloWorld.java lines icon="java" +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` +```` + +## Opciones de bloques de código + +Puedes agregar opciones meta a tus bloques de código para personalizar su apariencia. + + + Debes especificar un lenguaje de programación para un bloque de código antes de agregar cualquier otra opción meta. + + +### Sintaxis de las opciones + +- **Opciones de cadena y booleanas**: Envuélvelas con `""`, `''` o sin comillas. +- **Opciones de expresión**: Envuélvelas con `{}`, `""` o `''`. + +### Resaltado de sintaxis + +Activa el resaltado de sintaxis especificando el lenguaje de programación después de las comillas invertidas de apertura de un bloque de código. + +Usamos [Shiki](https://shiki.style/) para el resaltado de sintaxis y admitimos todos los lenguajes disponibles. Consulta la lista completa de [lenguajes](https://shiki.style/languages) en la documentación de Shiki. + +```java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + +````mdx +```java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` +```` + +### Título + +Agrega un título para etiquetar tu ejemplo de código. Usa `title="Your title"` o una cadena en una sola línea. + +```javascript Code Block Example +const hello = "world"; +``` + +````mdx +```javascript Code Block Example +const hello = "world"; +``` +```` + +### Ícono + +Agrega un ícono a tu bloque de código usando la propiedad `icon`. Consulta [Icons](/es/components/icons) para ver todas las opciones disponibles. + +```javascript icon="square-js" +const hello = "world"; +``` + +````mdx +```javascript icon="square-js" +const hello = "world"; +``` +```` + +### Resaltado de líneas + +Resalta líneas específicas en tus bloques de código usando `highlight` con los números de línea o rangos que quieras resaltar. + +```javascript Line Highlighting Example highlight= {1-2,5} +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` + +````mdx +```javascript Line Highlighting Example highlight={1-2,5} +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` +```` + +### Enfoque de líneas + +Enfoca líneas específicas en tus bloques de código usando `focus` con números de línea o rangos. + +```javascript Line Focus Example focus= {2,4-5} +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` + +````mdx +```javascript Line Focus Example focus={2,4-5} +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` +```` + +### Mostrar números de línea + +Muestra los números de línea en el lado izquierdo de tu bloque de código usando `lines`. + +```javascript Show Line Numbers Example lines +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` + +````mdx +```javascript Show Line Numbers Example lines +const greeting = "Hello, World!"; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` +```` + +### Expandible + +Permite a los usuarios expandir y contraer bloques de código largos usando `expandable`. + +```python Expandable Example expandable +from datetime import datetime, timedelta +from typing import Dict, List, Optional +from dataclasses import dataclass + +@dataclass +class Book: + title: str + author: str + isbn: str + checked_out: bool = False + due_date: Optional[datetime] = None + +class Library: + def __init__(self): + self.books: Dict[str, Book] = {} + self.checkouts: Dict[str, List[str]] = {} # usuario -> lista de ISBN + + def add_book(self, book: Book) -> None: + if book.isbn in self.books: + raise ValueError(f"El libro con ISBN {book.isbn} ya existe") + self.books[book.isbn] = book + + def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None: + if patron not in self.checkouts: + self.checkouts[patron] = [] + + book = self.books.get(isbn) + if not book: + raise ValueError("Libro no encontrado") + + if book.checked_out: + raise ValueError("El libro ya está prestado") + + if len(self.checkouts[patron]) >= 3: + raise ValueError("El usuario alcanzó el límite de préstamos") + + book.checked_out = True + book.due_date = datetime.now() + timedelta(days=days) + self.checkouts[patron].append(isbn) + + def return_book(self, isbn: str) -> float: + book = self.books.get(isbn) + if not book or not book.checked_out: + raise ValueError("Libro no encontrado o no prestado") + + late_fee = 0.0 + if datetime.now() > book.due_date: + days_late = (datetime.now() - book.due_date).days + late_fee = days_late * 0.50 + + book.checked_out = False + book.due_date = None + + # Quitar de los préstamos del usuario + for patron, books in self.checkouts.items(): + if isbn in books: + books.remove(isbn) + break + + return late_fee + + def search(self, query: str) -> List[Book]: + query = query.lower() + return [ + book for book in self.books.values() + if query in book.title.lower() or query in book.author.lower() + ] + +def main(): + library = Library() + + # Agregar algunos libros + books = [ + Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"), + Book("1984", "George Orwell", "978-0-452-28423-4"), + ] + + for book in books: + library.add_book(book) + + # Ejemplo de préstamo y devolución + library.checkout_book("978-0-261-10295-4", "patron123") + late_fee = library.return_book("978-0-261-10295-4") + print(f"Multa por retraso: ${late_fee:.2f}") + +if __name__ == "__main__": + main() +``` + +````mdx +```python Expandable Example expandable +from datetime import datetime, timedelta +from typing import Dict, List, Optional +from dataclasses import dataclass + +# ... + +if __name__ == "__main__": + main() +``` +```` + +### Ajuste de línea + +Activa el ajuste de texto para líneas largas usando `wrap`. Esto evita el desplazamiento horizontal y facilita la lectura de líneas extensas. + +```javascript Wrap Example wrap +const greeting = "Hello, World! I am a long line of text that will wrap to the next line."; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` + +````mdx +```javascript Wrap Example wrap +const greeting = "Hello, World! I am a long line of text that will wrap to the next line."; +function sayHello() { + console.log(greeting); +} +sayHello(); +``` +```` + +### Diff + +Muestra un diff visual de líneas añadidas o eliminadas en tus bloques de código. Las líneas añadidas se resaltan en verde y las eliminadas en rojo. + +Para crear diffs, añade estos comentarios especiales al final de las líneas en tu bloque de código: + +- `// [!code ++]`: Marca una línea como añadida (resaltado en verde). +- `// [!code --]`: Marca una línea como eliminada (resaltado en rojo). + +Para varias líneas consecutivas, especifica el número de líneas después de los dos puntos: + +- `// [!code ++:3]`: Marca la línea actual más las dos siguientes como añadidas. +- `// [!code --:5]`: Marca la línea actual más las cuatro siguientes como eliminadas. + +La sintaxis de comentarios debe coincidir con tu lenguaje de programación (por ejemplo, `//` para JavaScript o `#` para Python). + +```js Diff Example icon="code" lines +const greeting = "Hello, World!"; // [!code ++] +function sayHello() { + console.log("Hello, World!"); // [!code --] + console.log(greeting); // [!code ++] +} +sayHello(); +``` + +````text +```js Diff Example icon="code" lines +const greeting = "Hello, World!"; // [!code ++] +function sayHello() { + console.log("Hello, World!"); // [!code --] + console.log(greeting); // [!code ++] +} +sayHello(); +``` +```` \ No newline at end of file diff --git a/es/components/accordions.mdx b/es/components/accordions.mdx new file mode 100644 index 000000000..68cd59019 --- /dev/null +++ b/es/components/accordions.mdx @@ -0,0 +1,102 @@ +--- +title: "Acordeones" +description: "Componentes desplegables para mostrar y ocultar contenido" +icon: "chevron-down" +--- + +import IconsOptional from "/snippets/icons-optional.mdx"; + +Los acordeones permiten a los usuarios desplegar y contraer secciones de contenido. Usa acordeones para la divulgación progresiva y para organizar la información. + +## Acordeón individual + + + Puedes incluir cualquier contenido aquí, incluidos otros componentes, como código: + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + +````mdx Accordion example + + Puedes incluir cualquier contenido aquí, incluidos otros componentes, como código: + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + +```` + +## Grupos de acordeones + +Agrupa acordeones relacionados con ``. Esto crea una sección coherente de acordeones que se pueden expandir o contraer individualmente. + + + + Puedes incluir otros componentes dentro de los acordeones. + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + + Añade iconos para que los acordeones sean más distintivos y fáciles de explorar visualmente. + + + + Mantén el contenido relacionado organizado en grupos. + + + +````mdx Accordion Group Example + + + You can put other components inside Accordions. + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + + Add icons to make accordions more visually distinct and scannable. + + + + Keep related content organized into groups. + + +```` + +## Propiedades + + + Título en la vista previa del Accordion. + + + + Detalle debajo del título en la vista previa del Accordion. + + + + Indica si el Accordion está abierto de forma predeterminada. + + + diff --git a/es/components/callouts.mdx b/es/components/callouts.mdx new file mode 100644 index 000000000..a9379cab0 --- /dev/null +++ b/es/components/callouts.mdx @@ -0,0 +1,51 @@ +--- +title: "Avisos" +description: "Usa avisos para añadir contexto llamativo a tu contenido" +icon: "info" +--- + +Los avisos se pueden estilizar como Nota, Advertencia, Información, Sugerencia o Confirmación: + +Esto añade una nota en el contenido + +```mdx +Esto añade una nota en el contenido +``` + +Esto muestra una advertencia a tener en cuenta + +```mdx +Esto muestra una advertencia a tener en cuenta +``` + +Esto destaca información importante + +```mdx +Esto destaca información importante +``` + +Esto sugiere una sugerencia útil + +```mdx +Esto sugiere una sugerencia útil +``` + +Esto indica un estado confirmado + +```mdx +Esto indica un estado confirmado +``` + +Este es un aviso de peligro + +```jsx +Este es un aviso de peligro +``` + + + +```mdx Callout Example +Esto añade una nota en el contenido +``` + + diff --git a/es/components/cards.mdx b/es/components/cards.mdx new file mode 100644 index 000000000..7cf2d6650 --- /dev/null +++ b/es/components/cards.mdx @@ -0,0 +1,132 @@ +--- +title: "Tarjetas" +description: "Destaca puntos clave o enlaces con diseños e íconos personalizables" +icon: "square-mouse-pointer" +--- + +import IconsOptional from "/snippets/icons-optional.mdx"; + +Usa tarjetas para crear contenedores visuales de contenido. Las tarjetas son contenedores flexibles que pueden incluir texto, íconos, imágenes y enlaces. + +## Tarjeta básica + + + Así es como se usa una tarjeta con un ícono y un enlace. Al hacer clic en esta tarjeta, + irás a la página Columns. + + +```mdx Card example + + Así es como se usa una tarjeta con un ícono y un enlace. Al hacer clic en esta tarjeta, + irás a la página Columns. + +``` + +## Variaciones de tarjetas + +Las tarjetas ofrecen varias opciones de diseño y estilo para adaptarse a distintas necesidades de contenido. + +### Diseño horizontal + +Añade la propiedad `horizontal` para mostrar tarjetas en un diseño horizontal más compacto. + + + Este es un ejemplo de una tarjeta horizontal. + + +```mdx Horizontal card example + + This is an example of a horizontal card. + +``` + +### Tarjetas con imagen + +Añade la propiedad `img` para mostrar una imagen en la parte superior de la tarjeta. + + + Este es un ejemplo de una tarjeta con imagen. + + +```mdx Image card example + + This is an example of a card with an image. + +``` + +### Tarjetas de enlace con CTA personalizados + +Puedes personalizar el texto de la llamada a la acción y controlar si aparece una flecha. De forma predeterminada, las flechas solo se muestran en los enlaces externos. + + + Este es un ejemplo de una tarjeta con un ícono y un enlace. Al hacer clic en esta tarjeta, irás a la página Columns. + + +```mdx Link card example + + This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page. + +``` + +## Agrupar tarjetas + +Usa el [componente Columns](/es/components/columns) para organizar varias tarjetas lado a lado. + + + + Esta es la primera tarjeta. + + + + Esta es la segunda tarjeta. + + + +```mdx Ejemplo de Columns + + + Esta es la primera tarjeta. + + + Esta es la segunda tarjeta. + + +``` + +## Propiedades + + + El título que se muestra en la tarjeta + + + + + + Color del icono como código hexadecimal (p. ej., `#FF6B6B`). + + + + URL a la que navegar cuando se hace clic en la tarjeta. + + + + Mostrar la tarjeta en un diseño horizontal compacto. + + + + URL o ruta local de una imagen que se muestra en la parte superior de la tarjeta. + + + + Texto personalizado para el botón de acción. + + + + Mostrar u ocultar el icono de flecha del enlace. + diff --git a/es/components/code-groups.mdx b/es/components/code-groups.mdx new file mode 100644 index 000000000..c489fc423 --- /dev/null +++ b/es/components/code-groups.mdx @@ -0,0 +1,98 @@ +--- +title: "Grupos de código" +description: "Muestra varios ejemplos de código en un mismo componente" +icon: "group" +--- + +Usa el componente `CodeGroup` para mostrar varios bloques de código en una interfaz con pestañas, lo que permite a los usuarios comparar implementaciones en distintos lenguajes de programación o ver enfoques alternativos para la misma tarea. + + + +```javascript helloWorld.js +console.log("Hello World"); +``` + +```python hello_world.py +print('Hello World!') +``` + +```java HelloWorld.java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + + + +## Creación de grupos de código + +Para crear un grupo de código, envuelve varios bloques de código con etiquetas ``. Cada bloque de código debe incluir un título, que se usará como etiqueta de pestaña. + +````mdx + + +```javascript helloWorld.js +console.log("Hello World"); +``` + +```python hello_world.py +print('Hello World!') +``` + +```java HelloWorld.java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + + +```` + +## Menú desplegable de idiomas + +Puedes sustituir las pestañas de un grupo de código por un menú desplegable para alternar entre idiomas usando la prop `dropdown`. + + + +```javascript helloWorld.js +console.log("Hello World"); +``` + +```python hello_world.py +print('Hello World!') +``` + +```java HelloWorld.java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + + + +````mdx highlight=1 + + +```javascript helloWorld.js +console.log("Hello World"); +``` + +```python hello_world.py +print('Hello World!') +``` + +```java HelloWorld.java +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +``` + +```` diff --git a/es/components/columns.mdx b/es/components/columns.mdx new file mode 100644 index 000000000..bdefea11c --- /dev/null +++ b/es/components/columns.mdx @@ -0,0 +1,38 @@ +--- +title: "Columnas" +description: "Mostrar tarjetas una junto a otra en un formato de cuadrícula" +icon: "columns-2" +keywords: ["grupos de tarjetas"] +--- + +El componente `Columns` te permite agrupar varios componentes `Card`. Se usa con mayor frecuencia para colocar varias tarjetas en una cuadrícula especificando el número de columnas. + + + + Neque porro quisquam est qui dolorem ipsum quia dolor sit amet + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit + + + + + +```mdx Card Group Example + + + Neque porro quisquam est qui dolorem ipsum quia dolor sit amet + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit + + +``` + + + +### Props + + + Número de columnas por fila + diff --git a/es/components/examples.mdx b/es/components/examples.mdx new file mode 100644 index 000000000..5a1b2eb37 --- /dev/null +++ b/es/components/examples.mdx @@ -0,0 +1,47 @@ +--- +title: "Ejemplos" +description: "Muestra bloques de código en la barra lateral derecha en dispositivos de escritorio" +icon: 'between-horizontal-start' +--- + +Los componentes `` y `` muestran bloques de código en la barra lateral derecha para crear un diseño de dos columnas que mantiene los ejemplos visibles mientras los usuarios se desplazan por tu contenido. Estos componentes están pensados para la documentación de API, pero funcionan en todas las páginas. + +Casos de uso comunes: + +- Documentación de endpoints de API con ejemplos de solicitud y respuesta +- Ejemplos de configuración junto con texto explicativo +- Ejemplos de código que los usuarios consultan mientras siguen instrucciones +- Ejemplos de antes y después en tutoriales + +En dispositivos móviles, los componentes `` y `` se muestran como bloques de código convencionales y se pueden omitir al desplazarse. + +## RequestExample + +Usa `` para anclar ejemplos de código en la barra lateral derecha. Este componente funciona de forma similar al componente [CodeGroup](/es/components/code-groups), pero muestra el código en la barra lateral en lugar de dentro del contenido. + +Puedes incluir varios bloques de código dentro de un único ``. Cada bloque de código debe tener un atributo title. + +````mdx RequestExample + + +```bash Request + curl --request POST \ + --url https://dog-api.kinduff.com/api/facts +``` + + +```` + +## ResponseExample + +El componente `` ancla ejemplos de código en la barra lateral derecha, debajo de cualquier contenido `` en la misma página. + +````mdx ResponseExample + + +```json Response +{ "status": "success" } +``` + + +```` diff --git a/es/components/expandables.mdx b/es/components/expandables.mdx new file mode 100644 index 000000000..f9d7d0a6c --- /dev/null +++ b/es/components/expandables.mdx @@ -0,0 +1,45 @@ +--- +title: "Desplegables" +description: "Alternar para mostrar propiedades anidadas" +icon: "list-tree" +--- + +Usa desplegables para mostrar y ocultar contenido anidado dentro de los campos de respuesta. Los desplegables son especialmente útiles para mostrar propiedades complejas de objetos en la documentación de API. + + + + + + El nombre completo del usuario + + + + Si el usuario tiene más de 21 años + + + + + +```mdx Expandable example + + + + El nombre completo del usuario + + + + Si el usuario tiene más de 21 años + + + +``` + +## Propiedades + + + El nombre del objeto que se mostrará. + + + + Configúrelo en `true` para que el panel expandible se abra al cargar la página. + diff --git a/es/components/fields.mdx b/es/components/fields.mdx new file mode 100644 index 000000000..c05204d2b --- /dev/null +++ b/es/components/fields.mdx @@ -0,0 +1,100 @@ +--- +title: "Campos" +description: "Configura parámetros para tus referencias de API o SDK" +icon: "letter-text" +--- + +Utiliza campos para documentar parámetros y respuestas de la API. Hay dos tipos de campos: de parámetro y de respuesta. + +## Campo de parámetro + +El componente `` se utiliza para definir parámetros para tus API o SDK. Al agregar un `ParamField` se añade automáticamente un [Área de pruebas de API](/es/api-playground/overview). + + + Un ejemplo de un campo de parámetro + + +```mdx + + Un ejemplo de un campo de parámetro + +``` + +### Propiedades + + + Indica si el parámetro es de tipo query, path, body o header. Luego se especifica el + nombre del parámetro. + + + + Tipo esperado del valor del parámetro. + + Admite `number`, `string`, `boolean`, `object`. + + Los arreglos se pueden definir usando el sufijo `[]`. Por ejemplo, `string[]`. + + + + Indica si el parámetro es obligatorio. + + + + Indica si el parámetro está en desuso. + + + + Valor predeterminado que se establece cuando el valor de la solicitud está vacío + + + + Texto del placeholder para la entrada en el área de pruebas. + + + + Descripción del parámetro (con soporte para Markdown). + + +## Campo de respuesta + +El componente `` define los valores de retorno de una API. + + + Un ejemplo de campo de respuesta + + +```mdx + + Un ejemplo de campo de respuesta + +``` + +### Propiedades + + + El nombre del valor de respuesta. + + + + Tipo esperado del valor de respuesta. Puede ser cualquier cadena arbitraria. + + + + El valor predeterminado. + + + + Indica si el campo es obligatorio. + + + + Indica si el campo está obsoleto. + + + + Etiquetas que se muestran antes del nombre del campo. + + + + Etiquetas que se muestran después del nombre del campo. + diff --git a/es/components/frames.mdx b/es/components/frames.mdx new file mode 100644 index 000000000..531ddcb5b --- /dev/null +++ b/es/components/frames.mdx @@ -0,0 +1,41 @@ +--- +title: "Marcos" +description: "Usa el componente Frame para envolver imágenes u otros componentes en un contenedor." +icon: 'frame' +--- + +Los marcos son muy útiles si quieres centrar una imagen. + + + + + +## Leyendas + +Puedes añadir contexto adicional a una imagen usando la prop opcional `caption`. + + + + + +## Props + + + Texto opcional de pie de foto que se mostrará centrado debajo de tu componente. + + + + +```mdx Frame + + + +``` + +```mdx Frame with Captions + + + +``` + + diff --git a/es/components/icons.mdx b/es/components/icons.mdx new file mode 100644 index 000000000..9a3edc22a --- /dev/null +++ b/es/components/icons.mdx @@ -0,0 +1,37 @@ +--- +title: "Íconos" +description: "Usa íconos de bibliotecas populares" +icon: "flag" +--- + +import IconsRequired from "/snippets/icons-required.mdx"; + +Usa íconos de Font Awesome, Lucide, SVG, URL externas o archivos de tu proyecto para mejorar tu documentación. + + + +```mdx Ejemplo de Icon + +``` + +## Iconos en línea + +Los iconos se colocan en línea cuando se usan dentro de un párrafo. + + La documentación que quieres, sin complicaciones. + +```markdown Inline icon example + La documentación que quieres, sin complicaciones. +``` + +## Propiedades + + + + + El color del icono como código hexadecimal (por ejemplo, `#FF5733`). + + + + El tamaño del icono en píxeles. + diff --git a/es/components/mermaid-diagrams.mdx b/es/components/mermaid-diagrams.mdx new file mode 100644 index 000000000..04e6625c6 --- /dev/null +++ b/es/components/mermaid-diagrams.mdx @@ -0,0 +1,63 @@ +--- +title: "Mermaid" +description: "Mostrar diagramas con Mermaid" +icon: "waypoints" +--- + +[Mermaid](https://mermaid.js.org/) te permite crear diagramas de flujo, de secuencia, de Gantt y otros diagramas usando texto y código. + +Para ver la lista completa de tipos de diagramas compatibles y su sintaxis, consulta la [documentación de Mermaid](https://mermaid.js.org/intro/). + + + +````mdx Ejemplo de diagrama de flujo en Mermaid +```mermaid + flowchart LR + subgraph subgraph1 + direction TB + top1[top] --> bottom1[bottom] + end + subgraph subgraph2 + direction TB + top2[top] --> bottom2[bottom] + end + %% ^ Estos subgráficos son idénticos, excepto por los enlaces hacia ellos: + + %% Enlace *a* subgraph1: se mantiene la dirección de subgraph1 + outside --> subgraph1 + %% Enlace *dentro de* subgraph2: + %% subgraph2 hereda la dirección del gráfico de nivel superior (LR) + outside ---> top2 +``` +```` + + + +```mermaid + flowchart LR + subgraph subgraph1 + direction TB + top1[top] --> bottom1[bottom] + end + subgraph subgraph2 + direction TB + top2[top] --> bottom2[bottom] + end + %% ^ Estos subgráficos son idénticos, excepto por los enlaces hacia ellos: + + %% Enlace *a* subgraph1: se mantiene la dirección de subgraph1 + outside --> subgraph1 + %% Enlace *dentro de* subgraph2: + %% subgraph2 hereda la dirección del gráfico de nivel superior (LR) + outside ---> top2 +``` + +## Sintaxis + +Para crear un diagrama de Mermaid, escribe la definición de tu diagrama dentro de un bloque de código de Mermaid. + +````mdx +```mermaid +// Tu código de diagrama de Mermaid aquí +``` +```` diff --git a/es/components/panel.mdx b/es/components/panel.mdx new file mode 100644 index 000000000..05ed5b44e --- /dev/null +++ b/es/components/panel.mdx @@ -0,0 +1,21 @@ +--- +title: "Panel" +description: "Especifica el contenido del panel lateral derecho" +icon: "panel-right" +--- + +Puedes usar el componente `` para personalizar el panel lateral derecho de una página con cualquier componente que quieras. + +Si una página incluye un componente ``, los componentes [RequestExample](/es/components/examples#request-example) y [ResponseExample](/es/components/examples#response-example) deben estar dentro de ``. + +Los componentes dentro de un `` reemplazarán la tabla de contenidos de la página. + +```mdx + + Fija información en el panel lateral. O agrega cualquier otro componente. + +``` + + + Fija información en el panel lateral. O agrega cualquier otro componente. + diff --git a/es/components/responses.mdx b/es/components/responses.mdx new file mode 100644 index 000000000..bc23b614f --- /dev/null +++ b/es/components/responses.mdx @@ -0,0 +1,56 @@ +--- +title: 'Campos de respuesta' +description: 'Mostrar valores de respuesta de la API' +--- + +El componente `` está diseñado para definir los valores de retorno de una API. Muchas docs también usan `` en páginas cuando necesitas enumerar los tipos de algo. + + + Un ejemplo de campo de respuesta + + +```mdx + + Un ejemplo de campo de respuesta + +``` + +## Props + + + El nombre del valor de la respuesta. + + + + Tipo esperado del valor de la respuesta; puede ser cualquier cadena arbitraria. + + + + El valor predeterminado. + + + + Mostrar "required" junto al nombre del campo. + + + + Indica si un campo está en desuso o no. + + + + Etiquetas que se muestran antes del nombre del campo + + + + Etiquetas que se muestran después del nombre del campo + + + + +```mdx Response Field Example + + Ejemplo de un campo de respuesta + +``` + + diff --git a/es/components/steps.mdx b/es/components/steps.mdx new file mode 100644 index 000000000..ae81b24f6 --- /dev/null +++ b/es/components/steps.mdx @@ -0,0 +1,65 @@ +--- +title: "Steps" +description: "Secuencia contenido con el componente Steps" +icon: "list-todo" +--- + +import IconsOptional from "/snippets/icons-optional.mdx"; + +Usa Steps para mostrar una serie de acciones o eventos secuenciales. Puedes agregar tantos pasos como necesites. + + + + Estas son instrucciones o contenido que solo aplican al primer paso. + + + Estas son instrucciones o contenido que solo aplican al segundo paso. + + + Estas son instrucciones o contenido que solo aplican al tercer paso. + + + +```mdx Steps example + + + These are instructions or content that only pertain to the first step. + + + These are instructions or content that only pertain to the second step. + + + These are instructions or content that only pertain to the third step. + + +``` + +## Propiedades de Steps + + + Una lista de componentes `Step`. + + + + El tamaño de los títulos del paso. Puede ser `p`, `h2` o `h3`. + + +## Propiedades individuales del paso + + + El contenido de un paso, ya sea texto plano o componentes. + + + + + + El título es el texto principal del paso y aparece junto al indicador. + + + + El número del paso. + + + + El tamaño de los títulos del paso. Uno de `p`, `h2` o `h3`. + diff --git a/es/components/tabs.mdx b/es/components/tabs.mdx new file mode 100644 index 000000000..98d9eedd6 --- /dev/null +++ b/es/components/tabs.mdx @@ -0,0 +1,69 @@ +--- +title: "Pestañas" +description: "Alterna el contenido con el componente Tabs" +icon: "panel-top" +--- + +Usa pestañas para organizar contenido en varios paneles entre los que los usuarios pueden cambiar. Puedes agregar tantas pestañas como necesites e incluir otros componentes dentro de cada una. + + + + ☝️ Bienvenido al contenido que solo puedes ver dentro de la primera pestaña. + + Puedes agregar cualquier número de componentes dentro de las pestañas. Por ejemplo, un bloque de código: + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + ✌️ Aquí encontrarás contenido que solo aparece dentro de la segunda pestaña. + + ¡Esta tiene un icono ! + + + 💪 Aquí encontrarás contenido que solo aparece dentro de la tercera pestaña. + + + +````mdx Tabs example + + + ☝️ Welcome to the content that you can only see inside the first tab. + + You can add any number of components inside of tabs. For example, a code block: + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + ✌️ Here's content that's only inside the second tab. + + This one has a icon! + + + 💪 Here's content that's only inside the third tab. + + +```` + +## Propiedades + + + El título de la pestaña. Los títulos cortos facilitan la navegación. + + + + Un icono de [Font Awesome](https://fontawesome.com/icons), un icono de [Lucide](https://lucide.dev/icons), una URL a un icono o una ruta relativa a un icono. + + + + Solo para iconos de Font Awesome: uno de `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. + diff --git a/es/components/tooltips.mdx b/es/components/tooltips.mdx new file mode 100644 index 000000000..974e7c393 --- /dev/null +++ b/es/components/tooltips.mdx @@ -0,0 +1,17 @@ +--- +title: "Tooltips" +description: "Muestra una definición al pasar el cursor sobre el texto" +icon: "message-square" +--- + +Los tooltips son una forma de mostrar una definición al pasar el cursor sobre el texto. + +Pasa el cursor sobre mí y mira un tooltip en acción + + + +```mdx Tooltip Example +Pasa el cursor sobre mí +``` + + diff --git a/es/components/update.mdx b/es/components/update.mdx new file mode 100644 index 000000000..bc4d0c471 --- /dev/null +++ b/es/components/update.mdx @@ -0,0 +1,47 @@ +--- +title: "Actualización" +description: "Sigue los cambios y actualizaciones" +icon: "list-collapse" +--- + +Usa el componente `Update` para mostrar entradas del registro de cambios, actualizaciones de versión y notas de lanzamiento con un formato coherente. + + + ## Actualización de ejemplo + + Puedes añadir cualquier cosa aquí, como una captura de pantalla, un fragmento de código o una lista de cambios. + + + + + + ### Novedades + + - Diseño adaptable + - Ancla para cada actualización + - Entrada de RSS generada para cada actualización + + +## Cómo usar + +```mdx Update example + + Esta es una actualización con una etiqueta, una descripción y una etiqueta. + +``` + +Usa varios componentes `Update` para crear [registros de cambios](/es/guides/changelogs). + +## Props + + + Etiqueta de la actualización. Aparece a la izquierda de la actualización y crea un enlace ancla. Las etiquetas deben ser únicas. + + + + Etiquetas de la actualización. Se muestran como filtros en el panel lateral derecho. + + + + Descripción de la actualización. Aparece debajo de la etiqueta y las etiquetas. + diff --git a/es/contact-support.mdx b/es/contact-support.mdx new file mode 100644 index 000000000..994443055 --- /dev/null +++ b/es/contact-support.mdx @@ -0,0 +1,25 @@ +--- +title: "Contactar al soporte" +icon: "circle-help" +description: "Estamos aquí para ayudarte a sacar el máximo partido a Mintlify" +--- + +## Consulta nuestra documentación + +Selecciona Command + I para iniciar un chat con nuestro Assistant de IA entrenado con nuestra documentación. + +## Mira tutoriales en video + +Visita nuestro canal de [YouTube](https://www.youtube.com/@GetMintlify/videos) para encontrar tutoriales y guías sobre el uso de Mintlify. + +## Soporte por mensajes + +Envíanos un mensaje desde tu [panel](https://dashboard.mintlify.com/) seleccionando **Support** en la barra lateral. + + +Nuestro objetivo es responder a todas las solicitudes en un plazo de 24 horas, pero pueden producirse demoras en períodos de alta demanda. + + +## Soporte por correo electrónico + +Si no puedes acceder a tu panel, escríbenos a support@mintlify.com. diff --git a/es/editor.mdx b/es/editor.mdx new file mode 100644 index 000000000..12648c499 --- /dev/null +++ b/es/editor.mdx @@ -0,0 +1,348 @@ +--- +title: "Editor web" +description: "Crea tu documentación con el Editor web de Mintlify" +icon: "mouse-pointer-2" +--- + +Interfaz del Editor web de Mintlify en modo claro + +Interfaz del Editor web de Mintlify en modo oscuro + +## Introducción + +El Editor web es una interfaz visual para crear, editar y revisar documentación directamente en tu navegador. + +- **Edición visual**: Realiza cambios en tu documentación usando un editor WYSIWYG (lo que ves es lo que obtienes) que muestra cómo se verá tu contenido al publicarse. +- **Sincronización con Git**: Todos los cambios se sincronizan automáticamente con tu repositorio de Git para mantener el control de versiones. +- **Colaboración en tiempo real**: Varios miembros del equipo pueden trabajar en la documentación simultáneamente, con cambios visibles para todos. +- **Sin configuración**: Comienza a escribir de inmediato desde tu panel. + +### Flujo del Editor web + +Así es como normalmente trabajarás en el Editor web: + + + + Crea una rama o realiza cambios directamente en tu rama de despliegue. + + + + Navega a un archivo existente o crea uno nuevo. + + + + Realiza cambios en el Editor web usando el modo visual o el modo Markdown. + + + + Mira cómo se verán tus cambios en el modo visual. + + + + Si estás trabajando en tu rama de despliegue, publica tus cambios directamente desde el Editor web. En otras ramas, publica tus cambios mediante una pull request. + + + +## Modos del editor + +El Editor web tiene dos modos para adaptarse a distintas preferencias y necesidades de edición. + +Puedes alternar entre modos en cualquier momento usando el interruptor en la esquina superior derecha de la barra de herramientas del editor. + + + Iconos de alternancia de modo resaltados en el Editor web de Mintlify + + Iconos de alternancia de modo resaltados en el Editor web de Mintlify + + +### Modo visual + +El modo visual ofrece una experiencia WYSIWYG en la que los cambios que realizas en el editor son los que se publicarán en tu sitio de documentación. Este modo es ideal cuando quieres ver en tiempo real cómo se verán tus cambios. + + + Modo de edición visual en el Editor web de Mintlify + + Modo de edición visual en el Editor web de Mintlify + + +### Modo Markdown + +El modo Markdown ofrece acceso directo al código `MDX` subyacente de tu documentación. `MDX` combina la sintaxis de Markdown con componentes de React, lo que te da control total sobre la estructura de tu contenido. Este modo es ideal cuando necesitas un control preciso de las propiedades de los componentes o cuando prefieres escribir en sintaxis Markdown. + + + Modo Markdown en el Editor web de Mintlify + + Modo Markdown en el Editor web de Mintlify + + +## Fundamentos de Git + +El Editor web realiza operaciones de Git en segundo plano. Comprender estos conceptos te ayudará a trabajar de forma más efectiva con el Editor web y a colaborar con miembros del equipo que trabajan en sus entornos locales. + + + + La fuente de tu documentación donde se almacenan todos los archivos y su historial. El Editor web se conecta a tu repositorio para acceder y modificar el contenido. + + + + Una instantánea de tus cambios guardada en un momento específico. + + + + Un espacio de trabajo separado para realizar cambios sin afectar tu documentación en producción. Piénsalo como un entorno seguro para experimentos y actualizaciones más grandes. + + + + La rama principal que contiene el contenido de tu documentación en vivo. Los cambios en esta rama se publican automáticamente en tu sitio de documentación. A menudo llamada `main`. + + + + Una forma de proponer la fusión de los cambios de tu rama en tu documentación en vivo. Permite la revisión y la discusión antes de que los cambios se publiquen. Comúnmente llamado PR. + + + + Un diff (o diferencia) muestra los cambios específicos entre dos versiones de un archivo. Al revisar pull requests, los diffs resaltan lo que se ha agregado, eliminado o modificado. + + + +### Lo que automatiza el Editor web + +El Editor web se conecta a tu repositorio de Git a través de nuestra [GitHub App](/es/settings/github) o la [integración con GitLab](/es/settings/gitlab) y gestiona Git automáticamente. Cuando: + +- **Abres un archivo**: Obtiene la versión más reciente de tu repositorio. +- **Haces cambios en un archivo**: Registra tus cambios como un borrador que puede convertirse en un commit. +- **Guardas cambios**: Crea un commit con tus cambios. +- **Creas una rama**: Crea una nueva rama en tu repositorio. +- **Publicas en tu rama de despliegue**: Crea un commit y hace push directamente a tu rama de despliegue. +- **Publicas en otras ramas**: Crea un commit y abre un pull request. + +### Cuándo usar ramas + +Las ramas te permiten trabajar en cambios sin afectar el contenido de tu sitio en vivo. Cuando tus cambios estén listos, puedes fusionarlos en tu rama de despliegue con un pull request. + +**Mejor práctica: trabaja siempre desde ramas.** Esto garantiza que tu documentación en vivo se mantenga estable y habilita flujos de revisión adecuados. + +## Crear una rama + +1. Selecciona el nombre de la rama en la barra de herramientas del editor (normalmente `main` de forma predeterminada). +2. Selecciona **New Branch**. +3. Ingresa un nombre descriptivo para tu rama, como `update-getting-started` o `fix-installation-steps`. +4. Selecciona **Create Branch**. + + + Es posible que debas seleccionar tu nueva rama en el menú desplegable si el editor no cambia a ella automáticamente. + + +### Guardar cambios en una rama + +Para guardar tus cambios en una rama, selecciona el botón **Save Changes** en la esquina superior derecha del editor. Esto crea un commit con tus cambios y lo envía a tu rama. + +### Cambiar de rama + +1. Selecciona el nombre de la rama actual en la barra de herramientas del editor. +2. Selecciona la rama a la que deseas cambiar en el menú desplegable. + + + Cualquier cambio no guardado se perderá al cambiar de rama. Asegúrate de guardar o publicar tu trabajo antes de cambiar. + + +## Realizar cambios + +Edita contenido existente, crea páginas nuevas y organiza la estructura de tu sitio en el Editor web. + +### Navegación de archivos + +Usa el explorador de archivos de la barra lateral para recorrer tu documentación, o presiona Command + P (Ctrl + P en Windows) para buscar archivos. + +### Edición de contenido + +Realiza cambios en tus páginas usando el modo visual o el modo Markdown. + +En el modo visual, presiona / para abrir el menú desplegable de componentes. Agrega bloques de contenido, avisos, bloques de código y otros componentes para personalizar tu documentación. + + + El menú de componentes desplegado resaltado en el Editor web de Mintlify + + El menú de componentes desplegado resaltado en el Editor web de Mintlify + + +### Creación de páginas nuevas + +1. Selecciona el ícono **Create a new file** en el explorador de archivos. + Menú de archivos en el Editor web. + +Menú de archivos en el Editor web en modo oscuro. + +1. Ingresa un nombre de archivo. +2. Presiona Enter para crear el archivo. + +Tu nueva página se abrirá en el editor, lista para que agregues contenido. + +### Actualizar la navegación + +Agrega, elimina y reordena páginas en tu navegación editando tu archivo `docs.json`: + +1. Ve a tu `docs.json` en el explorador de archivos. +2. Actualiza la propiedad `navigation` para obtener la estructura de navegación que deseas. Consulta [Navigation](/es/navigation) para más información. + +Este ejemplo muestra cómo agregar una página de Temas al grupo Profile. + +```json title="Adding a Themes page" highlight="18" +{ + "navigation": { + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart", + "installation" + ] + }, + { + "group": "Profile", + "pages": [ + "settings", + "account-types", + "dashboard", + "themes" + ] + } + ] + } +} +``` + +## Publicar cambios + +Selecciona el botón **Publicar** para guardar tus cambios y hacerlos disponibles. + +Cómo se publican tus cambios depende de la rama en la que estés trabajando: + +- **Rama de producción**: Actualiza tu sitio en vivo de inmediato. +- **Otras ramas**: Crea una pull request para que puedas revisar los cambios antes de publicarlos. + + + El botón Publicar resaltado en el Editor web de Mintlify + + El botón Publicar resaltado en el Editor web de Mintlify + + +## Pull requests y revisión de cambios + +Los pull requests te permiten proponer cambios desde tu rama para que otras personas los revisen antes de fusionarlos en tu documentación en producción. Esto ayuda a garantizar que tus cambios sean correctos y le da a tu equipo la oportunidad de colaborar en el contenido. + + + Incluso si trabajas solo, los pull requests son útiles para previsualizar los cambios antes de publicarlos y mantener un historial claro de actualizaciones. + + +### Crear un pull request desde una rama + +Cuando estés listo para publicar los cambios desde tu rama: + +1. Asegúrate de que todos tus cambios estén guardados en tu rama. +2. Selecciona **Publish Pull Request** en la esquina superior derecha del editor. +3. Agrega un título y una descripción para tu pull request. Un buen título y una buena descripción ayudan a los revisores a entender los cambios que realizaste. +4. Selecciona **Publish Pull Request**. + + + Botón Publish pull request resaltado en el Editor web de Mintlify + + Botón Publish pull request resaltado en el Editor web de Mintlify + + +El Editor web creará un pull request en tu repositorio de Git y te proporcionará un enlace para verlo. + +### Revisar pull requests + +Una vez creado tu pull request: + +1. **Revisa tus cambios**: Tú y los miembros de tu equipo pueden revisar el pull request en tu proveedor de Git, como GitHub o GitLab. +2. **Haz cambios adicionales**: Después de la revisión, realiza los cambios en el Editor web. Al guardar, se actualizará el pull request. +3. **Fusiona cuando esté listo**: Cuando el pull request esté listo, fusiónalo para desplegar los cambios en tu sitio de documentación en producción. + +## Atajos de teclado + +El Editor web admite todos los atajos de teclado comunes, como copiar, pegar, deshacer y seleccionar todo, además de los siguientes atajos: + +| Comando | macOS | Windows | +|:--------|:------|:--------| +| **Buscar archivos** | Cmd + P | Control + P | +| **Agregar enlace al texto seleccionado** | Cmd + K | Control + K | +| **Insertar salto de línea** | Cmd + Enter | Control + Enter | +| **Negrita** | Cmd + B | Control + B | +| **Cursiva** | Cmd + I | Control + I | +| **Subrayado** | Cmd + U | Control + U | +| **Tachado** | Cmd + Shift + S | Control + Shift + S | +| **Código** | Cmd + E | Control + E | +| **Texto normal** | Cmd + Alt + 0 | Control + Alt + 0 | +| **Encabezado 1** | Cmd + Alt + 1 | Control + Alt + 1 | +| **Encabezado 2** | Cmd + Alt + 2 | Control + Alt + 2 | +| **Encabezado 3** | Cmd + Alt + 3 | Control + Alt + 3 | +| **Encabezado 4** | Cmd + Alt + 4 | Control + Alt + 4 | +| **Lista numerada** | Cmd + Shift + 7 | Control + Shift + 7 | +| **Lista con viñetas** | Cmd + Shift + 8 | Control + Shift + 8 | +| **Cita en bloque** | Cmd + Shift + B | Control + Shift + B | +| **Subíndice** | Cmd + , | Control + , | +| **Superíndice** | Cmd + . | Control + . | + +## Solución de problemas + +Aquí encontrarás soluciones a problemas comunes que puedes encontrar con el Editor web. + + + + **Posibles causas:** + + - El despliegue aún está en curso + - Problemas de caché en tu navegador + + **Soluciones:** + + 1. Revisa el estado del despliegue en tu panel de Mintlify. + 2. Prueba a forzar la recarga de tu navegador (Ctrl + F5 o Cmd + Shift + R). + 3. Borra la caché de tu navegador. + + + + **Posibles causas:** + + - Permisos insuficientes en el repositorio de Git + - Problemas de autenticación con tu proveedor de Git + + **Soluciones:** + + 1. Verifica que tienes el acceso correcto al repositorio. + 2. Comprueba si tu integración con Git está configurada correctamente. + 3. Revisa la documentación de [permisos del editor](/es/advanced/dashboard/permissions). + + + + **Posibles causas:** + + - Problemas de conectividad de red + - Repositorios de documentación muy grandes + + **Soluciones:** + + 1. Revisa tu conexión a internet. + 2. Recarga la página e inténtalo de nuevo. + 3. Contacta con soporte si el problema persiste. + + diff --git a/es/guides/analytics.mdx b/es/guides/analytics.mdx new file mode 100644 index 000000000..1877b7530 --- /dev/null +++ b/es/guides/analytics.mdx @@ -0,0 +1,51 @@ +--- +title: "Analytics" +description: "Consulta información sobre el rendimiento de tu documentación en tu panel" +icon: "chart-line" +--- + +La página de Analytics ofrece información sobre el desempeño de tu documentación, lo que te ayuda a identificar oportunidades de mejora y a hacer un seguimiento de los cambios a lo largo del tiempo. + +## Acceso a la analítica + +Ve a la pestaña **Analytics** en tu [panel](https://dashboard.mintlify.com/products/analytics). + +Usa el selector de rango para ajustar el período de tiempo de los datos mostrados. + +## Pestañas de analíticas + +El panel de analíticas tiene tres secciones principales: + +### Resumen +Consulta el tráfico y otras métricas de alto nivel sobre tu documentación. + +- **Visitantes**: Visitantes únicos. +- **Vistas**: Total de vistas de página. +- **Acciones**: Recuento combinado de llamadas a la API, clics en enlaces de la barra de navegación y clics en botones de CTA. +- **Páginas populares**: Páginas más visitadas con número de vistas. +- **Referencias**: Principales fuentes de tráfico que dirigen usuarios a tu documentación. + +### Comentarios +Supervisa la satisfacción del usuario a través de los datos de votación: + +- **Gustó a los lectores**: Páginas con la mayor cantidad de comentarios positivos (votos con pulgar arriba). +- **Necesita mejoras**: Páginas con la mayor cantidad de comentarios negativos (votos con pulgar abajo). + +Para ver los datos de comentarios, primero debes habilitar los comentarios desde la página de [Complementos](https://dashboard.mintlify.com/products/addons) en tu panel. + +### Búsqueda +Comprende cómo los usuarios buscan dentro de tu documentación. + +- **Consultas totales**: Volumen de búsquedas. +- **Búsquedas principales**: Términos más buscados. +- **Búsquedas con baja confianza**: Consultas que pueden no haber encontrado resultados relevantes. + +## Mejora tu documentación con analíticas + +Usa tus analíticas para mejorar la experiencia de uso de tu documentación: + +**Revisa el contenido popular**: Asegúrate de que tus páginas más visitadas tengan información actual y precisa, y considera ampliar los temas que mejor funcionan. + +**Atiende los comentarios**: Investiga las páginas con evaluaciones negativas para identificar y resolver los puntos de dolor de los usuarios. + +**Optimiza para la búsqueda**: Revisa las principales consultas de búsqueda para que las páginas relevantes sean fáciles de encontrar y estén actualizadas. Presta atención a las búsquedas con baja confianza que puedan indicar vacíos de contenido. diff --git a/es/guides/assistant.mdx b/es/guides/assistant.mdx new file mode 100644 index 000000000..1cb563c56 --- /dev/null +++ b/es/guides/assistant.mdx @@ -0,0 +1,93 @@ +--- +title: "Asistente" +description: "Ayuda a tus usuarios a tener éxito con tu producto y a encontrar respuestas más rápido" +icon: "bot" +--- + + + El Asistente se habilita automáticamente en los [planes Pro y Enterprise](https://mintlify.com/pricing?ref=assistant). + + +## Acerca del asistente + +El asistente responde preguntas sobre tu documentación mediante consultas en lenguaje natural. Está integrado directamente en tu sitio de documentación, brindando a los usuarios acceso inmediato a ayuda contextual. + +El asistente utiliza RAG agentivo (generación aumentada por recuperación) con ejecución de herramientas, impulsado por Claude Sonnet 4. Cuando los usuarios hacen preguntas, el asistente: + +- **Busca y recupera** contenido relevante de tu documentación para ofrecer respuestas precisas. +- **Cita las fuentes** y proporciona enlaces navegables que llevan a los usuarios directamente a las páginas de referencia. +- **Genera ejemplos de código que se pueden copiar** para ayudar a los usuarios a implementar soluciones a partir de tu documentación. + +Puedes ver el uso del asistente en tu panel para comprender el comportamiento de los usuarios y la eficacia de la documentación. Exporta y analiza los datos de las consultas para ayudar a identificar: + +- Preguntas frecuentes que podrían necesitar mejor cobertura. +- Lagunas de contenido donde los usuarios tienen dificultades para encontrar respuestas. +- Temas populares que podrían beneficiarse de contenido adicional. + +## Uso del asistente + +Los usuarios pueden acceder al asistente de dos maneras: + +- **Atajo de teclado**: Command + I (Ctrl + I en Windows) +- **Botón del asistente** junto a la barra de búsqueda + Barra de búsqueda y botón del asistente en modo claro. + Barra de búsqueda y botón del asistente en modo oscuro. + +Ambos métodos abren un panel de chat en el lado derecho de tu documentación. Los usuarios pueden hacer cualquier pregunta y el asistente buscará en tu documentación una respuesta. Si no encuentra información relevante, el asistente indicará que no puede responder la pregunta. + +## Hacer que el contenido sea apto para ingesta por IA + +Estructura tu documentación para ayudar al Asistente a ofrecer respuestas precisas y relevantes. Una organización clara y un contexto completo benefician tanto a las personas lectoras como a la comprensión de la IA. + + + - Usa marcado semántico. + - Escribe encabezados descriptivos para las secciones. + - Crea una jerarquía lógica de la información. + - Mantén un formato coherente en toda tu documentación. + - Incluye metadatos completos en el frontmatter de la página. + - Divide los bloques largos de texto en párrafos más cortos. + + + + - Define términos específicos y siglas la primera vez que aparezcan. + - Proporciona suficiente contenido conceptual sobre características y procedimientos. + - Incluye ejemplos y casos de uso. + - Agrega referencias cruzadas a temas relacionados. + - Añade [páginas ocultas](/es/guides/hidden-pages) con contexto adicional que las personas usuarias no necesiten, pero a las que el Asistente pueda remitirse. + + +## Exportar y analizar consultas + +Revisa y exporta consultas desde tu panel para entender cómo las personas interactúan con tu documentación e identificar oportunidades de mejora. Algunas formas en que el análisis de consultas puede ayudarte a mejorar tu documentación: + +- Identifica brechas de contenido donde las consultas frecuentes reciben respuestas insuficientes. +- Descubre patrones de comportamiento de los usuarios y necesidades de información comunes a partir de los temas y patrones en las consultas. +- Prioriza las páginas de alto tráfico para mejorar su precisión y calidad. + +Puedes explorar consultas desde tu [panel](https://dashboard.mintlify.com/products/assistant), pero para obtener insights más potentes te recomendamos exportar un archivo `CSV` con tus consultas, respuestas y fuentes para analizarlo con tu herramienta de IA preferida. + +1. Ve a la [página del Asistente](https://dashboard.mintlify.com/products/assistant) en tu panel. +2. Selecciona **Export to CSV**. +3. Analiza los datos exportados con tu herramienta preferida. + + + - Resume los temas más comunes de las consultas. + - Enumera las consultas que no tuvieron fuentes citadas. + - Encuentra patrones en interacciones fallidas. + diff --git a/es/guides/auth0.mdx b/es/guides/auth0.mdx new file mode 100644 index 000000000..5c479a892 --- /dev/null +++ b/es/guides/auth0.mdx @@ -0,0 +1,58 @@ +--- +title: "Uso de Auth0 con el handshake de OAuth" +description: "Si Auth0 es la fuente de verdad para los datos de tus usuarios, puedes configurar Mintlify como una aplicación cliente de OAuth para autenticar a tus usuarios." +--- + + + **Aviso de seguridad**: Aunque proporcionamos esta guía para ayudarte a integrar Auth0 con Mintlify, consulta con tu equipo de seguridad antes de implementar cualquier solución de autenticación. Mintlify no se hace responsable de ningún problema de seguridad que pueda surgir de tu implementación específica. + + +## Descripción general + +Esta guía te guía paso a paso para configurar Auth0 como proveedor de autenticación para tu documentación de Mintlify. Al finalizar, tus usuarios podrán iniciar sesión en tu documentación con sus credenciales de Auth0. + + + + Inicia sesión en tu panel de Auth0 y navega a **Applications** > **Applications**. Haz clic en el botón **Create Application**, asigna un nombre a tu aplicación (p. ej., “Mintlify”) y selecciona **Regular Web Applications** como tipo de aplicación. Luego, haz clic en **Create**. + + ![Creating a new application in Auth0](/images/guides/auth0/auth0-create-application.png) + + + Después de crear tu aplicación, se te dirigirá a la página de configuración de la aplicación. Aquí encontrarás las credenciales esenciales necesarias para la integración con OAuth: + + ![Auth0 client settings page](/images/guides/auth0/auth0clientsettings.png) + + Toma nota de la siguiente información: + - **Domain**: El dominio de tu tenant de Auth0 (p. ej., `your-tenant.auth0.com`) + - **Client ID**: El identificador público de tu aplicación + - **Client Secret**: La clave secreta de tu aplicación (manténla segura) + + Necesitarás estos valores para configurar Mintlify en el siguiente paso. + + + Ve a tu Panel de Mintlify y entra en **Settings** > **Authentication**. Selecciona **OAuth** como método de autenticación y verás el formulario de configuración de OAuth: + + ![Mintlify OAuth client settings](/images/guides/auth0/mintlifyoauthclientsettings.png) + + Completa el formulario con los siguientes valores: + + - **Authorization URL**: `https://YOUR_AUTH0_DOMAIN/authorize` (reemplaza `YOUR_AUTH0_DOMAIN` por tu dominio real de Auth0 del paso 2) + - **Client ID**: Ingresa el Client ID de tu aplicación de Auth0 + - **Client Secret**: Ingresa el Client Secret de tu aplicación de Auth0 + - **Scopes**: Déjalo en blanco a menos que tengas scopes personalizados definidos en Auth0 + - **Token URL**: `https://YOUR_AUTH0_DOMAIN/oauth/token` (reemplaza `YOUR_AUTH0_DOMAIN` por tu dominio real de Auth0) + + Después de completar estos datos, haz clic en **Save changes** para guardar tu configuración de OAuth. + + + Mintlify generará una URL de redirección única que Auth0 debe reconocer para que el flujo de OAuth funcione correctamente. + + Copia la URL de redirección desde la sección de Authentication en tu Panel de Mintlify: + ![Mintlify redirect URL](/images/guides/auth0/mintlifyredirecturl.png) + + Regresa a la página de configuración de tu aplicación en Auth0, desplázate hasta la sección **Application URIs** y pega la URL de redirección en el campo **Allowed Callback URLs**: + ![Auth0 redirect URL configuration](/images/guides/auth0/auth0redirecturl.png) + + Haz clic en **Save Changes** al final de la página de Auth0 para aplicar esta configuración. + + \ No newline at end of file diff --git a/es/guides/changelogs.mdx b/es/guides/changelogs.mdx new file mode 100644 index 000000000..0b25d875e --- /dev/null +++ b/es/guides/changelogs.mdx @@ -0,0 +1,136 @@ +--- +title: "Registro de cambios" +description: "Publica actualizaciones de producto en tu documentación con un canal RSS al que los usuarios pueden suscribirse" +icon: "newspaper" +--- + +Crea un registro de cambios para tu documentación agregando el [Componente de actualización](/es/components/update) a una página. + +Consulta el [registro de cambios de Mintlify](/es/changelog) como ejemplo: en cada actualización puedes incluir enlaces, imágenes, texto y demostraciones de tus nuevas funciones. + +## Configurar tu registro de cambios + + + + 1. Crea una nueva página en tu documentación, como `changelog.mdx` o `updates.mdx`. + 2. Agrega la página del registro de cambios a tu esquema de navegación en `docs.json`. + + + + Agrega un `Update` por cada entrada del registro de cambios. + + Incluye información relevante como lanzamientos de funciones, correcciones de errores u otros anuncios. + + + +```mdx Example changelog.mdx +--- +title: "Registro de cambios" +description: "Actualizaciones del producto y anuncios" +--- + + Se añadió un nuevo sabor Wintergreen. + + Se publicó una nueva versión del sabor Spearmint, ahora con un 10% más de menta. + + + + Se publicó una nueva versión del sabor Spearmint. + +``` + +## Personalizar tu registro de cambios + +Controla cómo las personas navegan por tu registro de cambios y se mantienen al día con la información de tu producto. + +### Tabla de contenido + +Cada propiedad `label` de un `Update` crea automáticamente una entrada en la tabla de contenido de la barra lateral derecha. Esta es la navegación predeterminada para tu registro de cambios. + + + Registro de cambios con tabla de contenido mostrada en modo claro. + + Registro de cambios con tabla de contenido mostrada en modo oscuro. + + +### Filtros por etiquetas + +Agrega `tags` a tus componentes `Update` para reemplazar la tabla de contenido con filtros por etiquetas. Los usuarios pueden filtrar el registro de cambios seleccionando una o más etiquetas: + +```mdx Tag filters example wrap + + Added a new Wintergreen flavor. + + Released a new version of the Spearmint flavor, now with 10% more mint. + + + + Released a new version of the Spearmint flavor. + + + + Deprecated the Peppermint flavor. + + Released a new version of the Spearmint flavor. + +``` + + + Registro de cambios en modo claro con el filtro de la etiqueta Peppermint seleccionado. + + Registro de cambios en modo oscuro con el filtro de la etiqueta Peppermint seleccionado. + + + + La tabla de contenido y los filtros del registro de cambios se ocultan al usar los modos de página `custom`, `center` o `wide`. Más información sobre [modos de página](/es/pages#page-mode). + + +### Registros de cambios con suscripción + +Usar componentes `Update` crea un feed RSS al que te puedes suscribir en la URL de tu página con `/rss.xml` añadido. Por ejemplo, `mintlify.com/docs/changelog/rss.xml`. + +Las entradas se agregan al feed RSS cuando se publican nuevos componentes `Update` y cuando se añaden nuevos encabezados dentro de etiquetas `` existentes. + +Los encabezados de nivel superior de los componentes `Update` se usan como títulos de las entradas del feed RSS, y estas enlazan a sus anclas de encabezado en tu documentación. + +```xml Example RSS feed + + + + <![CDATA[Product updates]]> + + https://mintlify.com/docs + RSS for Node + Mon, 21 Jul 2025 21:21:47 GMT + + + https://mintlify.com/docs + + <![CDATA[June 2025]]> + https://mintlify.com/docs/changelog#june-2025 + https://mintlify.com/docs/changelog#june-2025 + Mon, 23 Jun 2025 16:54:22 GMT + + + +``` + +Los feeds RSS pueden integrarse con Slack, correo electrónico u otras herramientas de suscripción para notificar a los usuarios sobre cambios en el producto. Algunas opciones incluyen: + +- [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) +- [Email](https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email) a través de Zapier +- Bots de Discord como [Readybot](https://readybot.io) o [RSS Feeds to Discord Bot](https://rss.app/en/bots/rssfeeds-discord-bot) + +Para facilitar el descubrimiento del feed RSS, puedes mostrar un botón con el ícono de RSS que enlace al feed en la parte superior de la página. Agrega `rss: true` al frontmatter de la página: + +```mdx +--- +rss: true +--- +``` + + + Página de registro de cambios en modo claro con el botón del feed RSS habilitado. + + Página de registro de cambios en modo oscuro con el botón del feed RSS habilitado. + diff --git a/es/guides/claude-code.mdx b/es/guides/claude-code.mdx new file mode 100644 index 000000000..2f8bddad8 --- /dev/null +++ b/es/guides/claude-code.mdx @@ -0,0 +1,134 @@ +--- +title: "Claude Code" +description: "Configura Claude Code para ayudar a escribir, revisar y actualizar tu documentación" +icon: "asterisk" +--- + +Claude Code es una herramienta de línea de comandos con capacidades de agente que puede ayudarte a mantener tu documentación. Puede redactar contenido nuevo, revisar páginas existentes y mantener la documentación actualizada. + +Puedes entrenar a Claude Code para que comprenda tus estándares y flujos de trabajo de documentación añadiendo un archivo `CLAUDE.md` a tu proyecto y afinándolo con el tiempo. + +## Primeros pasos + +**Requisitos previos:** +- Suscripción activa a Claude (Pro, Max o acceso por API) + +**Configuración:** +1. Instala Claude Code: + ```bash + npm install -g @anthropic-ai/claude-code + ``` +2. Ve a tu directorio de documentación. +3. (Opcional) Agrega el archivo `CLAUDE.md` que aparece a continuación a tu proyecto. +4. Ejecuta `claude` para empezar. + +## Plantilla de CLAUDE.md + +Guarda un archivo `CLAUDE.md` en la raíz de tu directorio de documentación para ayudar a Claude Code a comprender tu proyecto. Este archivo entrena a Claude Code en tus estándares de documentación, preferencias y flujos de trabajo. Consulta [Manage Claude's memory](https://docs.anthropic.com/en/docs/claude-code/memory) en la documentación de Anthropic para más información. + +Copia este ejemplo de plantilla o ajústalo según las especificaciones de tu documentación: + +```mdx +# Mintlify documentation + +## Working relationship +- Puedes cuestionar ideas; esto puede llevar a una mejor documentación. Cita fuentes y explica tu razonamiento cuando lo hagas +- SIEMPRE pide aclaraciones en lugar de asumir +- NUNCA mientas, adivines ni inventes información + +## Project context +- Formato: archivos MDX con frontmatter YAML +- Configuración: docs.json para navegación, tema y ajustes +- Componentes: componentes de Mintlify + +## Content strategy +- Documenta lo justo para que el usuario tenga éxito: ni demasiado, ni demasiado poco +- Prioriza la precisión y la usabilidad de la información +- Procura que el contenido sea perenne cuando sea posible +- Busca información existente antes de añadir contenido nuevo. Evita la duplicación salvo por un motivo estratégico +- Revisa los patrones existentes para mantener la coherencia +- Empieza haciendo los cambios más pequeños razonables + +## docs.json + +- Consulta el [esquema de docs.json](https://mintlify.com/docs.json) al crear el archivo docs.json y la navegación del sitio + +## Frontmatter requirements for pages +- title: Título de página claro y descriptivo +- description: Resumen conciso para SEO/navegación + +## Writing standards +- Voz en segunda persona ("tú") +- Prerrequisitos al inicio del contenido procedimental +- Prueba todos los ejemplos de código antes de publicar +- Alinea el estilo y formato con las páginas existentes +- Incluye casos de uso básicos y avanzados +- Etiquetas de lenguaje en todos los bloques de código +- Texto alternativo en todas las imágenes +- Rutas relativas para enlaces internos + +## Git workflow +- NUNCA uses --no-verify al hacer commits +- Pregunta cómo manejar los cambios sin confirmar antes de empezar +- Crea una nueva rama cuando no exista una clara para los cambios +- Haz commits con frecuencia durante el desarrollo +- NUNCA omitas ni desactives los hooks de pre-commit + +## Do not +- Omitir el frontmatter en cualquier archivo MDX +- Usar URLs absolutas para enlaces internos +- Incluir ejemplos de código no probados +- Hacer suposiciones: pide aclaraciones siempre +``` + +## Prompts de ejemplo + +Una vez que tengas Claude Code configurado, prueba estos prompts para ver cómo puede ayudar con tareas comunes de documentación. Puedes copiar y pegar estos ejemplos directamente o adaptarlos a tus necesidades específicas. + +### Convertir notas en documentación pulida +Convierte borradores en páginas Markdown bien formateadas con componentes y frontmatter. + +**Prompt de ejemplo:** +```text wrap +Convierte este texto en una página MDX con el formato correcto: [pega tu texto aquí] +``` + +### Revisar la documentación para mantener la coherencia +Obtén sugerencias para mejorar el estilo, el formato y el uso de componentes. + +**Prompt de ejemplo:** +```text wrap +Revisa los archivos en docs/ y sugiere mejoras para la coherencia y la claridad +``` + +### Actualizar la documentación cuando cambian las características +Mantén la documentación actualizada cuando tu producto evolucione. + +**Prompt de ejemplo:** +```text wrap +Nuestra API ahora requiere un parámetro de versión. Actualiza la documentación para incluir version=2024-01 en todos los ejemplos +``` + +### Generar ejemplos de código completos +Crea ejemplos en varios lenguajes con manejo de errores. + +**Prompt de ejemplo:** +```text wrap +Crea ejemplos de código para [tu endpoint de API] en JavaScript, Python y cURL, con manejo de errores +``` + +## Ampliar Claude Code + +Además de interactuar manualmente con Claude Code, puedes integrarlo en tus flujos de trabajo existentes. + +### Automatización con GitHub Actions +Ejecuta Claude Code automáticamente cuando haya cambios en el código para mantener la documentación actualizada. Puedes activar revisiones de documentación en pull requests o actualizar ejemplos cuando se detecten cambios en la API. + +### Flujos de trabajo multiinstancia +Usa sesiones separadas de Claude Code para distintas tareas: una para redactar contenido nuevo y otra para revisión y control de calidad. Esto ayuda a mantener la consistencia y a detectar problemas que una sola sesión podría pasar por alto. + +### Colaboración en equipo +Comparte tu archivo `CLAUDE.md` afinado con tu equipo para garantizar estándares de documentación consistentes entre todos los colaboradores. Los equipos suelen desarrollar prompts y flujos de trabajo específicos del proyecto que pasan a formar parte de su proceso de documentación. + +### Comandos personalizados +Crea comandos de barra reutilizables en `.claude/commands/` para tareas frecuentes de documentación específicas de tu proyecto o equipo. diff --git a/es/guides/cursor.mdx b/es/guides/cursor.mdx new file mode 100644 index 000000000..9dd27f600 --- /dev/null +++ b/es/guides/cursor.mdx @@ -0,0 +1,427 @@ +--- +title: "Cursor" +description: "Configura Cursor como tu asistente de redacción" +icon: "box" +--- + +Convierte a Cursor en un experto en documentación que conozca tus componentes, tu guía de estilo y tus mejores prácticas. + +## Uso de Cursor con Mintlify + +Las reglas de Cursor proporcionan un contexto persistente sobre tu documentación, lo que garantiza sugerencias más coherentes que se ajusten a tus estándares y estilo. + +- **Reglas de proyecto**: se almacenan en el repositorio de tu documentación y se comparten con tu equipo. +- **Reglas de usuario**: se aplican a tu entorno personal de Cursor. + +Recomendamos crear reglas de proyecto para tu documentación, de modo que todas las personas colaboradoras tengan acceso a las mismas reglas. + +Crea archivos de reglas en el directorio `.cursor/rules` de tu repositorio de documentación. Consulta la [documentación de Cursor Rules](https://docs.cursor.com/context/rules) para ver las instrucciones completas de configuración. + +## Regla de proyecto de ejemplo + +Esta regla proporciona a Cursor el contexto necesario para formatear correctamente los componentes de Mintlify y seguir las mejores prácticas de redacción técnica. + +Puedes usar este ejemplo tal cual o personalizarlo para tu documentación: + +- **Estándares de redacción**: Actualiza las pautas de lenguaje para alinearlas con tu guía de estilo. +- **Patrones de componentes**: Añade componentes específicos del proyecto o modifica los ejemplos existentes. +- **Ejemplos de código**: Sustituye los ejemplos genéricos por llamadas y respuestas reales de tu API. +- **Preferencias de estilo y tono**: Ajusta la terminología, el formato y otras reglas. + +Añade esta regla, con las modificaciones que necesites, como un archivo `.mdc` en el directorio `.cursor/rules` de tu repositorio de documentación. + +```mdx wrap +# Regla de redacción técnica de Mintlify + +Eres un asistente de escritura con IA especializado en crear documentación técnica excepcional usando componentes de Mintlify y siguiendo las mejores prácticas de redacción técnica del sector. +``` + +## Principios básicos de redacción + +### Requisitos de lenguaje y estilo + +- Usa un lenguaje claro y directo, adecuado para audiencias técnicas +- Escribe en segunda persona ("tú") para instrucciones y procedimientos +- Prefiere la voz activa frente a la pasiva +- Emplea el tiempo presente para estados actuales y el futuro para resultados +- Evita la jerga salvo que sea necesaria y define los términos la primera vez que se usen +- Mantén una terminología consistente en toda la documentación +- Mantén las oraciones concisas aportando el contexto necesario +- Usa una estructura paralela en listas, encabezados y procedimientos + +### Estándares de organización de contenido + +- Empieza por la información más importante (pirámide invertida) +- Usa divulgación progresiva: conceptos básicos antes que los avanzados +- Divide los procedimientos complejos en pasos numerados +- Incluye requisitos previos y contexto antes de las instrucciones +- Indica los resultados esperados para cada paso principal +- Usa encabezados descriptivos y ricos en palabras clave para la navegación y el SEO +- Agrupa la información relacionada de forma lógica con separaciones claras entre secciones + +### Enfoque centrado en el usuario + +- Enfócate en los objetivos y resultados del usuario, no en las funciones del sistema +- Anticipa preguntas comunes y abórdalas proactivamente +- Incluye una sección de solución de problemas para los puntos de falla más probables +- Escribe para facilitar el escaneo con encabezados claros, listas y espacios en blanco +- Incluye pasos de verificación para confirmar el éxito + +## Referencia de componentes de Mintlify + +### docs.json + +- Consulta el [esquema de docs.json](https://mintlify.com/docs.json) al crear el archivo docs.json y la navegación del sitio + +### Componentes de llamado de atención + +#### Note - Información adicional útil + + + Información complementaria que respalda el contenido principal sin interrumpir el flujo + + +#### Tip - Mejores prácticas y consejos + + + Consejos de expertos, atajos o mejores prácticas que aumentan la probabilidad de éxito del usuario + + +#### Warning - Advertencias importantes + + + Información crítica sobre posibles problemas, cambios incompatibles o acciones destructivas + + +#### Info - Información contextual neutral + + + Información de contexto, antecedentes o anuncios neutrales + + +#### Check - Confirmaciones de éxito + + + Confirmaciones positivas, finalizaciones correctas o indicadores de logro + + +### Componentes de código + +#### Bloque de código único + +Ejemplo de un bloque de código único: + +```javascript config.js +const apiConfig = { + baseURL: 'https://api.example.com', + timeout: 5000, + headers: { + 'Authorization': `Bearer ${process.env.API_TOKEN}` + } +}; +``` + +#### Grupo de código con varios lenguajes + +Ejemplo de un grupo de código: + + + ```javascript Node.js + const response = await fetch('/api/endpoint', { + headers: { Authorization: `Bearer ${apiKey}` } + }); + ``` + + ```python Python + import requests + response = requests.get('/api/endpoint', + headers={'Authorization': f'Bearer {api_key}'}) + ``` + + ```curl cURL + curl -X GET '/api/endpoint' \ + -H 'Authorization: Bearer YOUR_API_KEY' + ``` + + +#### Ejemplos de solicitud/respuesta + +Ejemplo de documentación de solicitud/respuesta: + + + ```bash cURL + curl -X POST 'https://api.example.com/users' \ + -H 'Content-Type: application/json' \ + -d '{"name": "John Doe", "email": "john@example.com"}' + ``` + + + + ```json Success + { + "id": "user_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2024-01-15T10:30:00Z" + } + ``` + + +### Componentes estructurales + +#### Pasos para procedimientos + +Ejemplo de instrucciones paso a paso: + + + + Ejecuta `npm install` para instalar los paquetes necesarios. + + + Verifica la instalación ejecutando `npm list`. + + + + + Crea un archivo `.env` con tus credenciales de API. + + ```bash + API_KEY=your_api_key_here + ``` + + + Nunca subas claves de API al control de versiones. + + + + +#### Pestañas para contenido alternativo + +Ejemplo de contenido con pestañas: + + + + ```bash + brew install node + npm install -g package-name + ``` + + + + ```powershell + choco install nodejs + npm install -g package-name + ``` + + + + ```bash + sudo apt install nodejs npm + npm install -g package-name + ``` + + + +#### Acordeones para contenido plegable + +Ejemplo de grupos de acordeón: + + + + - **Bloqueo por firewall**: Asegúrate de que los puertos 80 y 443 estén abiertos + - **Configuración de proxy**: Define la variable de entorno HTTP\_PROXY + - **Resolución DNS**: Prueba usar 8.8.8.8 como servidor DNS + + + + ```javascript + const config = { + performance: { cache: true, timeout: 30000 }, + security: { encryption: 'AES-256' } + }; + ``` + + + +### Tarjetas y columnas para destacar información + +Ejemplo de tarjetas y grupos de tarjetas: + + + Guía completa desde la instalación hasta tu primera llamada a la API en menos de 10 minutos. + + + + + Aprende a autenticar solicitudes usando claves de API o tokens JWT. + + + + Entiende los límites de tasa y las mejores prácticas para volúmenes altos. + + + +### Componentes de documentación de API + +#### Campos de parámetros + +Ejemplo de documentación de parámetros: + + + Identificador único del usuario. Debe ser un UUID v4 válido. + + + + Dirección de correo electrónico del usuario. Debe ser válida y única en el sistema. + + + + Número máximo de resultados a devolver. Rango: 1-100. + + + + Token de tipo Bearer para la autenticación de la API. Formato: `Bearer YOUR_API_KEY` + + +#### Campos de la respuesta + +Ejemplo de documentación de campos de respuesta: + + + Identificador único asignado al usuario recién creado. + + + + Marca de tiempo en formato ISO 8601 del momento en que se creó el usuario. + + + + Lista de permisos asignados a este usuario. + + +#### Campos anidados expandibles + +Ejemplo de documentación de campos anidados: + + + Objeto de usuario completo con todos los datos asociados. + + + + Información del perfil del usuario, incluidos los datos personales. + + + + Nombre del usuario tal como se introdujo durante el registro. + + + + URL de la foto de perfil del usuario. Devuelve null si no se ha configurado un avatar. + + + + + + +### Medios y componentes avanzados + +#### Marcos para imágenes + +Envuelve todas las imágenes en marcos: + + + Panel principal que muestra la vista general de analíticas + + + + Panel de analíticas con gráficos + + +#### Videos + +Usa el elemento de video HTML para contenido de video autoalojado: + +