{"id":40226301,"url":"https://github.com/cloud66/help-content","last_synced_at":"2026-01-19T22:33:41.139Z","repository":{"id":311987870,"uuid":"1042874810","full_name":"cloud66/help-content","owner":"cloud66","description":"help.cloud66.com Content","archived":false,"fork":false,"pushed_at":"2025-12-15T17:37:05.000Z","size":784,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-19T00:24:30.255Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://help.cloud66.com","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud66.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/active-protect.mdx","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-22T18:09:37.000Z","updated_at":"2025-12-15T17:37:09.000Z","dependencies_parsed_at":"2025-12-16T01:04:05.009Z","dependency_job_id":null,"html_url":"https://github.com/cloud66/help-content","commit_stats":null,"previous_names":["cloud66/help-content"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cloud66/help-content","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66%2Fhelp-content","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66%2Fhelp-content/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66%2Fhelp-content/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66%2Fhelp-content/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud66","download_url":"https://codeload.github.com/cloud66/help-content/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66%2Fhelp-content/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28587244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T20:45:59.482Z","status":"ssl_error","status_checked_at":"2026-01-19T20:45:41.500Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-19T22:33:41.078Z","updated_at":"2026-01-19T22:33:41.125Z","avatar_url":"https://github.com/cloud66.png","language":"MDX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloud 66 Documentation Writing Guide\n\nWelcome to the Cloud 66 documentation! This guide will help you write, format, and structure documentation for our products using MDX.\n\n## Quick Start\n\n1. Create MDX files in appropriate product directories: `rails/`, `deploy/`, `sites/`, `node/`, or `common/`\n2. Add proper frontmatter with title, description, lead, and products\n3. Use available components to enhance your content\n4. Test locally with `yarn dev`\n5. Validate with `yarn validate:mdx` before submitting\n\n## File Structure \u0026 Organization\n\n```\n/src/docs/\n├── rails/              # Rails-specific documentation\n├── deploy/             # Deploy-specific documentation \n│   ├── 1/             # Deploy v1 legacy content\n│   └── 2/             # Deploy v2 content (v3 uses base folder)\n├── sites/              # Sites-specific documentation\n├── node/               # Node-specific documentation (legacy product)\n├── common/             # Shared documentation across all products\n└── partials/           # Reusable content snippets (not directly accessible)\n```\n\n### File Naming Conventions\n\n- Use lowercase kebab-case: `building-your-service.mdx`\n- Be descriptive and specific: `connecting-between-containerized-services.mdx`\n- Avoid abbreviations unless well-known: `api-keys.mdx` not `api-keys.mdx`\n\n### Navigation Order Control\n\nUse `_order.yaml` files to control the order of documents within categories:\n\n```yaml\n# /src/docs/getting-started/_order.yaml\n- quick-start\n- deploy-your-first-app\n- migrate-from-heroku\n- migrate-from-forge\n```\n\n**Rules:**\n- Place `_order.yaml` in each category directory\n- List file names (without `.mdx` extension) in desired order\n- Files not listed in `_order.yaml` will appear after ordered files\n- Categories themselves are ordered by the `sequence` field in `/src/config/products.ts`\n\n## MDX Frontmatter\n\nEvery MDX file must include frontmatter metadata at the top:\n\n### Basic Frontmatter\n\n```yaml\n---\ntitle: \"Your Page Title\"\ndescription: \"Brief description for SEO (150-160 characters ideal)\"\nlead: \"Extended description shown at top of page (optional)\"\nproducts: ['rails', 'deploy']\n---\n```\n\n### Product Targeting Options\n\n**Specific products:**\n```yaml\nproducts: ['rails', 'deploy']  # Only accessible on Rails and Deploy\n```\n\n**All products:**\n```yaml\nproducts: 'all'  # Accessible from all product routes\n```\n\n**Common (no products field):**\n```yaml\n# No products field = accessible on all products + /common/ routes\n```\n\n### Version Control (Deploy Only)\n\n**Hide from specific versions:**\n```yaml\nexcludeVersions: ['2']  # Hide from Deploy v2, show on v1 and v3\n```\n\n**Show only in specific versions:**\n```yaml\nincludeVersions: ['1']  # Only show in Deploy v1\n```\n\n**Important:** `excludeVersions` and `includeVersions` are mutually exclusive.\n\n### Multi-Version Documents\n\nFor Deploy product, you can create version-specific content:\n\n```\n/src/docs/category/\n  └── page.mdx           # Default/latest version (v3)\n  └── 1/\n      └── page.mdx       # Version 1 specific content\n  └── 2/\n      └── page.mdx       # Version 2 specific content (optional)\n```\n\nThe system will automatically serve the appropriate version based on the URL.\n\n## Available Components\n\n### Content Organization\n\n#### PerProduct\nShow/hide content based on the active product:\n\n```mdx\n\u003cPerProduct includes={[\"rails\"]}\u003e\nThis content only shows for Rails users.\n\u003c/PerProduct\u003e\n\n\u003cPerProduct includes={[\"deploy\"]}\u003e\nThis content shows for Deploy users.\n\u003c/PerProduct\u003e\n\n\u003cPerProduct excludes={[\"sites\"]}\u003e\nThis content shows for all products except Sites.\n\u003c/PerProduct\u003e\n\n\u003cPerProduct includeVersions={[\"1\"]}\u003e\nThis content only shows for Deploy v1 users.\n\u003c/PerProduct\u003e\n\n\u003cPerProduct excludeVersions={[\"2\"]}\u003e\nThis content shows for all Deploy versions except v2.\n\u003c/PerProduct\u003e\n```\n\n#### Tabs\nCreate tabbed content for different scenarios:\n\n```mdx\n\u003cTabs defaultValue=\"rails\"\u003e\n  \u003cTabsList\u003e\n    \u003cTabsTrigger value=\"rails\"\u003eRails\u003c/TabsTrigger\u003e\n    \u003cTabsTrigger value=\"express\"\u003eExpress\u003c/TabsTrigger\u003e\n    \u003cTabsTrigger value=\"django\"\u003eDjango\u003c/TabsTrigger\u003e\n  \u003c/TabsList\u003e\n  \n  \u003cTabsContent value=\"rails\"\u003e\n    Rails-specific content here.\n  \u003c/TabsContent\u003e\n  \n  \u003cTabsContent value=\"express\"\u003e\n    Express-specific content here.\n  \u003c/TabsContent\u003e\n  \n  \u003cTabsContent value=\"django\"\u003e\n    Django-specific content here.\n  \u003c/TabsContent\u003e\n\u003c/Tabs\u003e\n```\n\n#### FilteredContentBox\nCreate content with a dropdown filter:\n\n```mdx\n\u003cFilteredContentBox labels={[\"AWS\", \"GCP\", \"Azure\"]} defaultFilter=\"AWS\"\u003e\n  \u003cFilteredContent filter=\"AWS\"\u003e\n    AWS-specific instructions here.\n  \u003c/FilteredContent\u003e\n  \n  \u003cFilteredContent filter=\"GCP\"\u003e\n    Google Cloud specific instructions here.\n  \u003c/FilteredContent\u003e\n  \n  \u003cFilteredContent filter=\"Azure\"\u003e\n    Azure-specific instructions here.\n  \u003c/FilteredContent\u003e\n\u003c/FilteredContentBox\u003e\n```\n\n### Alerts \u0026 Callouts\n\n#### Callout\nHighlight important information:\n\n```mdx\n\u003cCallout type=\"info\" title=\"Information\"\u003e\nGeneral information or tips.\n\u003c/Callout\u003e\n\n\u003cCallout type=\"warning\" title=\"Important\"\u003e\nSomething users should be careful about.\n\u003c/Callout\u003e\n\n\u003cCallout type=\"error\" title=\"Warning\"\u003e\nCritical information or potential issues.\n\u003c/Callout\u003e\n```\n\n#### Alert\nBasic alert component:\n\n```mdx\n\u003cAlert\u003e\n  \u003cAlertTitle\u003eNotice\u003c/AlertTitle\u003e\n  \u003cAlertDescription\u003e\n    Basic alert with optional title and description.\n  \u003c/AlertDescription\u003e\n\u003c/Alert\u003e\n```\n\n### Interactive Elements\n\n#### Collapsible\nExpandable content sections:\n\n```mdx\n\u003cCollapsible title=\"Advanced Configuration\"\u003e\n  This content is hidden by default and can be expanded by clicking the title.\n  \n  You can include any markdown or components here.\n\u003c/Collapsible\u003e\n```\n\n#### Hint\nTooltips for additional context:\n\n```mdx\n\u003cHint caption=\"hover me\"\u003e\n  Additional information shown on hover.\n\u003c/Hint\u003e\n```\n\n### Visual Elements\n\n#### Figure\nImages with captions:\n\n```mdx\n\u003cFigure \n  src=\"/path/to/image.png\" \n  alt=\"Descriptive alt text\"\n  caption=\"Optional caption explaining the image\" \n/\u003e\n```\n\n#### Badge\nSmall status indicators:\n\n```mdx\n\u003cBadge variant=\"default\"\u003eNew\u003c/Badge\u003e\n\u003cBadge variant=\"secondary\"\u003eBeta\u003c/Badge\u003e\n\u003cBadge variant=\"destructive\"\u003eDeprecated\u003c/Badge\u003e\n\u003cBadge variant=\"outline\"\u003eOptional\u003c/Badge\u003e\n```\n\n#### Pill\nRounded status indicators:\n\n```mdx\n\u003cPill\u003eStatus\u003c/Pill\u003e\n```\n\n#### Button\nInteractive buttons (use sparingly):\n\n```mdx\n\u003cButton variant=\"default\"\u003ePrimary Action\u003c/Button\u003e\n\u003cButton variant=\"outline\"\u003eSecondary Action\u003c/Button\u003e\n\u003cButton variant=\"ghost\"\u003eSubtle Action\u003c/Button\u003e\n```\n\n### Specialized Components\n\n#### ComponentVersion\nDisplay version-specific information:\n\n```mdx\n\u003cComponentVersion version=\"2.1.0\" /\u003e\n```\n\n#### IpList\nDisplay Cloud 66 IP addresses:\n\n```mdx\n\u003cIpList /\u003e\n```\n\n#### Glyph\nSpecial typography elements:\n\n```mdx\n\u003cGlyph\u003eSpecial symbol or icon\u003c/Glyph\u003e\n```\n\n#### CodeBlock\nEnhanced code blocks with syntax highlighting:\n\n```mdx\n\u003cCodeBlock language=\"bash\" title=\"Installation\"\u003e\nnpm install @cloud66/cli\n\u003c/CodeBlock\u003e\n```\n\n#### PartialWrapper\nWraps imported MDX partials to ensure proper SmartLink functionality:\n\n```mdx\nimport MyPartial from '../partials/_my_partial.mdx';\n\n\u003cPartialWrapper partial={MyPartial} /\u003e\n```\n\n**Required for all partials** - without this wrapper, SmartLink placeholders (`:product`, `:version?`) won't be converted properly.\n\n## Smart Links\n\nLinks automatically adapt to the current product and version context:\n\n```mdx\n[Getting Started](/:product/:version?/getting-started/quick-start)\n[API Reference](/:product/api/overview)\n[Common Guide](/common/shared-guide)\n```\n\n**Placeholders:**\n- `:product` - Current product (rails, deploy, sites, node)\n- `:version` - Current version (includes version in path if set)\n- `:version?` - Optional version (includes version only if viewing a specific version)\n\n## Markdown Features\n\n### Standard Markdown\nAll GitHub Flavored Markdown is supported:\n\n- **Bold** and *italic* text\n- `inline code`\n- [Links](https://cloud66.com)\n- Lists (ordered and unordered)\n- Headers (H1-H6)\n- Tables\n- Blockquotes\n- Horizontal rules\n\n### Code Blocks\nFenced code blocks with syntax highlighting:\n\n```bash\n# This is a bash command\nkubectl get pods\n```\n\n```yaml\n# YAML configuration\napiVersion: v1\nkind: Service\nmetadata:\n  name: my-service\n```\n\n```javascript\n// JavaScript code\nconst config = {\n  apiKey: process.env.API_KEY,\n  timeout: 5000\n};\n```\n\n### Tables\nStandard Markdown tables with enhanced styling:\n\n| Feature | Rails | Deploy | Sites |\n|---------|-------|--------|-------|\n| SSL | ✅ | ✅ | ✅ |\n| Auto-scaling | ✅ | ✅ | ❌ |\n| Databases | ✅ | ✅ | ❌ |\n\n## Importing Partials\n\nReuse content across multiple pages by importing partials. **IMPORTANT:** All partials must be wrapped with `PartialWrapper` for proper SmartLink functionality.\n\n### Correct Usage:\n\n```mdx\nimport GitPartial from '../partials/_git.mdx';\nimport SshKeysPartial from '../partials/_ssh_keys.mdx';\n\n\u003cPartialWrapper partial={GitPartial} /\u003e\n\n## Next Steps\n\n\u003cPartialWrapper partial={SshKeysPartial} /\u003e\n```\n\n### Why PartialWrapper is Required\n\nMDX partials imported as components don't inherit the component overrides from the parent page. Without `PartialWrapper`, SmartLink placeholders like `:product` and `:version?` won't be converted properly.\n\n**❌ Incorrect (will break SmartLink conversion):**\n```mdx\n\u003cGitPartial /\u003e  \u003c!-- Links with :product/:version won't work --\u003e\n```\n\n**✅ Correct (SmartLinks work properly):**\n```mdx\n\u003cPartialWrapper partial={GitPartial} /\u003e\n```\n\n### Nested Partials\n\nPartials that import other partials work automatically when using PartialWrapper:\n\n```mdx\n\u003c!-- /src/docs/partials/_cloud_providers.mdx --\u003e\nimport AwsPartial from './_aws.mdx';\n\n\u003cFilteredContentBox labels={[\"AWS\", \"GCP\"]}\u003e\n  \u003cFilteredContent filter=\"AWS\"\u003e\n    \u003cPartialWrapper partial={AwsPartial} /\u003e\n  \u003c/FilteredContent\u003e\n\u003c/FilteredContentBox\u003e\n```\n\n**Partial naming:** Always prefix with underscore (`_git.mdx`, `_ssh_keys.mdx`)\n\n## Writing Best Practices\n\n### Content Structure\n\n1. **Start with context:** Explain what the reader will learn\n2. **Use clear headings:** Structure content hierarchically\n3. **Include prerequisites:** List what readers need before starting\n4. **Provide examples:** Show real code and configurations\n5. **End with next steps:** Guide readers to related content\n\n### Writing Style\n\n- **Be concise:** Get to the point quickly\n- **Use active voice:** \"Click the button\" not \"The button should be clicked\"\n- **Write for your audience:** Assume technical competency but explain Cloud 66-specific concepts\n- **Be consistent:** Use the same terminology throughout\n\n### Technical Guidelines\n\n- **Test all code:** Ensure examples work as documented\n- **Use realistic examples:** Avoid `foo`, `bar`, `example.com`\n- **Include error handling:** Show what can go wrong and how to fix it\n- **Update regularly:** Remove outdated information\n\n### Accessibility\n\n- **Alt text:** Always include descriptive alt text for images\n- **Link text:** Use descriptive link text, not \"click here\"\n- **Headings:** Use proper heading hierarchy (don't skip levels)\n- **Lists:** Use proper list markup for sequential steps\n\n## SEO Guidelines\n\n### Frontmatter SEO\n\n```yaml\n---\ntitle: \"Specific, descriptive title (50-60 chars)\"\ndescription: \"Clear description with target keywords (150-160 chars)\"\nlead: \"Engaging lead paragraph that expands on the description\"\n---\n```\n\n### Content SEO\n\n- **Use headers:** Structure content with H2, H3, etc.\n- **Internal linking:** Link to related Cloud 66 documentation\n- **Keywords naturally:** Use relevant terms without keyword stuffing\n- **Meta descriptions:** Write compelling descriptions for search results\n\n## Validation \u0026 Testing\n\n### Before Submitting\n\n1. **Test locally:** Run `yarn dev` and verify your content renders correctly\n2. **Validate MDX:** Run `yarn validate:mdx` to check for syntax errors\n3. **Check links:** Run `yarn validate:links` to verify internal links\n4. **Test components:** Ensure all components render and function properly\n5. **Review product targeting:** Verify content appears on correct products\n\n### Common Issues\n\n- **Missing frontmatter:** Every file needs title and description\n- **Broken imports:** Check partial paths are correct\n- **Component props:** Ensure all required props are provided\n- **Link validation:** Use correct paths for internal links\n- **Version conflicts:** Don't use both `includeVersions` and `excludeVersions`\n\n## Getting Help\n\n- **Technical issues:** Check the main project README for development commands\n- **Component questions:** Refer to component source code in `/src/components/`\n- **Style guide:** Follow existing documentation patterns\n- **Questions:** Ask the development team for clarification\n\n---\n\nHappy writing! 🚀","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud66%2Fhelp-content","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud66%2Fhelp-content","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud66%2Fhelp-content/lists"}