|
8 | 8 | ## Project context |
9 | 9 | - Format: MDX files with YAML frontmatter |
10 | 10 | - Config: docs.json for navigation, theme, settings |
11 | | -- Components: Tiger Cloud, Tiger Console, TimescaleDB |
| 11 | +- Components: Tiger Cloud, Tiger Console, TimescaleDB, Agentic Postgres |
12 | 12 |
|
13 | 13 | ## Content strategy |
14 | 14 | - Document just enough for user success - not too much, not too little |
|
23 | 23 | - Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation |
24 | 24 |
|
25 | 25 | ## Frontmatter requirements for pages |
26 | | -- title: Clear, descriptive page title |
27 | | -- description: Concise summary for SEO/navigation |
| 26 | +- title: Clear, descriptive page title (meta title max 60 characters for SEO) |
| 27 | +- description: Concise summary for SEO/navigation/search (under 200 characters) |
| 28 | + |
| 29 | +## Page structure requirements |
| 30 | + |
| 31 | +### Regular pages should include: |
| 32 | +- Short intro paragraph that summarizes content in first sentence |
| 33 | +- Visual illustration when helpful |
| 34 | +- Descriptive headers using keywords |
| 35 | +- Step-by-step procedures for actionable content |
| 36 | +- Relevant internal and external links |
| 37 | + |
| 38 | +### API pages should include: |
| 39 | +- Function name as title |
| 40 | +- Brief description |
| 41 | +- Usage samples with code blocks |
| 42 | +- Arguments table with format: | Name | Type | Default | Required | Description | |
| 43 | +- Returns section |
| 44 | + |
| 45 | +### Troubleshooting pages should include: |
| 46 | +- Specific frontmatter fields (title, section, products/topics) |
| 47 | +- Clear problem identification |
| 48 | +- Step-by-step resolution procedures |
28 | 49 |
|
29 | 50 | ## Writing standards |
| 51 | +- Follow the Google Developer Documentation Style Guide with exceptions: |
| 52 | + - Do not capitalize the first word after a colon |
| 53 | + - Use semi-bold for UI elements |
| 54 | +- Write clear, concise, and actionable documentation |
30 | 55 | - Second-person voice ("you") |
31 | 56 | - Prerequisites at start of procedural content |
32 | 57 | - Test all code examples before publishing |
|
35 | 60 | - Language tags on all code blocks |
36 | 61 | - Alt text on all images |
37 | 62 | - Relative paths for internal links |
| 63 | +- If a product or concept is missing from the glossary, add it |
| 64 | + |
| 65 | +## Content reuse and formatting |
| 66 | + |
| 67 | +### Variables and links |
| 68 | +- Use `{VARIABLE_NAME}` syntax for variables (reference snippets/vars.mdx for mappings) |
| 69 | +- Internal links don't require full domain - use relative paths |
| 70 | +- External links input as-is with full URLs |
| 71 | + |
| 72 | +### Supported formatting |
| 73 | +- Tabs for organizing related content |
| 74 | +- Code blocks with language tags |
| 75 | +- Multi-tab code blocks for multiple language examples |
| 76 | +- Tags for categorization |
| 77 | + |
| 78 | +### SEO optimization |
| 79 | +- Use keywords in titles, headers, and intro paragraphs |
| 80 | +- Summarize paragraph contents in first sentence |
| 81 | +- Keep meta descriptions under 200 characters |
| 82 | +- Keep meta titles under 60 characters |
38 | 83 |
|
39 | 84 | ## Git workflow |
40 | 85 | - NEVER use --no-verify when committing |
|
43 | 88 | - Commit frequently throughout development |
44 | 89 | - NEVER skip or disable pre-commit hooks |
45 | 90 |
|
| 91 | +## Templates |
| 92 | + |
| 93 | +- For a new procedural page, use .github/templates/procedure.md as a template |
| 94 | +- For a new integration page, use .github/templates/integration.md as a template |
| 95 | + |
46 | 96 | ## Do not |
47 | 97 | - Skip frontmatter on any MDX file |
48 | 98 | - Use absolute URLs for internal links |
49 | 99 | - Include untested code examples |
50 | | -- Make assumptions - always ask for clarification |
| 100 | +- Make assumptions - always ask for clarification |
| 101 | + |
| 102 | +# Migration |
| 103 | + |
| 104 | +- Check the directory that the files are to move into |
| 105 | +- Update all ${VARIABLES} to use the mintlify variables (reference snippets/vars.mdx for mappings) |
| 106 | +- replace references to import since`<version>` with `<Icon icon="circle-play" iconType="duotone" />` Since `<version>` on its own line after the frontmatter, followed by a newline before content begins |
| 107 | +- replace references to import deprecated`<version>` with `<Icon icon="circle-pause" iconType="duotone" />` Deprecated `<version>` on its own line after the frontmatter, followed by a newline before content begins |
| 108 | +- replace references to import DeprecationNotice with `<Icon icon="circle-pause" iconType="duotone" />` Deprecated on its own line after the frontmatter, followed by a newline before content begins |
| 109 | +- replace references to import sunsetted`<version>` with `<Icon icon="sunset" iconType="duotone" />` Sunsetted `<version>` on its own line after the frontmatter, followed by a newline before content begins |
| 110 | +- replace references to import EarlyAccess`<version>` with `<Icon icon="flask" />` Early access `<version>` on its own line after the frontmatter, followed by a newline before content begins. if there is no version number, don't add one |
| 111 | +- replace references to import Experimental with `<Icon icon="flask" />` Early access on its own line after the frontmatter, followed by a newline before content begins. if there is no version number, don't add one |
| 112 | +- Ask where the other imported files should go in the snippets directory (initially manual, but track patterns to automate over time) |
| 113 | +- Update the metadata in each file, rename the excerpt metadata name as description, and api_name as title |
| 114 | +- Remove api: and version: metadata sections, indent license and type under root level |
| 115 | +- Put the value of stable in a since icon (e.gple., if stable: 1.0.0, add Since 1.0.0 icon), then remove the stable metadata item |
| 116 | +- Remove the first # header from the content (title is handled by frontmatter) |
| 117 | +- Replace `<Highlight>` blocks with `<Info>` blocks (with newlines between tags and text) |
| 118 | +- Change ### Required arguments to ## Arguments with new table format: | Name | Type | Default | Required | Description | |
| 119 | +- Required arguments get ✔ in Required column, - in Default column (unless default specified) |
| 120 | +- Merge Optional arguments section into the same table with ✔ in Required column for optional args |
| 121 | +- Change ### Samples to ## Samples |
| 122 | +- Change **Returns:** to ## Returns with newline before text |
| 123 | +- Update internal links to use the correct Mintlify repository structure |
| 124 | +- Check all content so it will render correctly in Mintlify |
| 125 | +- Update the docs.json to include the files in the structure. The docs.json structure reflects the folder structure - initially ask for placement, but learn patterns over time |
0 commit comments