|
| 1 | +# Docs Site Fixes — Unresolved Jira Tickets |
| 2 | + |
| 3 | +The following issues were filed by Josh Hill (IT) against the Kintsugi docs site |
| 4 | +(`docs.trykintsugi.com`) and have **not yet been resolved** by the recent overhaul. |
| 5 | +Please address each one. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## SE-65 — Duplicate H1 Tags |
| 10 | + |
| 11 | +**Root cause:** Mintlify auto-generates an `<h1>` from the frontmatter `title` field. |
| 12 | +Any `# Heading` in the MDX body becomes a *second* H1 on the rendered page. |
| 13 | + |
| 14 | +### Files to fix |
| 15 | + |
| 16 | +**`docs/sdks/python.mdx`** — line 6 has `# Python SDK` which duplicates the frontmatter title. |
| 17 | +Change it to `## Python SDK` **OR** delete it entirely (the frontmatter title already renders as H1). |
| 18 | + |
| 19 | +**`docs/sdks/ruby.mdx`** — line 6 has `# Ruby SDK`. Same fix: downgrade to `##` or remove. |
| 20 | + |
| 21 | +> The other bare `#` lines in those files (`# Initialize the client`, `# Calculate tax`, etc.) |
| 22 | +> are **inside fenced code blocks** and are fine — don't touch them. |
| 23 | +
|
| 24 | +--- |
| 25 | + |
| 26 | +## SE-63 — Broken External Link to Old Support Docs |
| 27 | + |
| 28 | +**File:** `docs/file-upload.mdx` (lines 14 and 16) |
| 29 | + |
| 30 | +Both occurrences link to: |
| 31 | +``` |
| 32 | +https://help.trykintsugi.com/en/articles/11146254-uploading-sales-transactions-via-csv-in-kintsugi |
| 33 | +``` |
| 34 | + |
| 35 | +This is the "old support docs" external link flagged as broken. Options: |
| 36 | +1. **Verify the URL is live** — if the Intercom/help article still exists, keep it. |
| 37 | +2. **Replace with the correct URL** if the article was moved or deleted. |
| 38 | +3. **Remove the external reference entirely** if the content has been migrated into this docs site. |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## SE-60 / SE-61 — Duplicate Title Tags & Duplicate Meta Descriptions |
| 43 | + |
| 44 | +**Root cause:** `docs.json` has two API reference tabs — `"API Reference"` (under `reference/api/`) and `"API Reference - Partners"` (under `reference/partners/`) — that mirror each other almost entirely. Mintlify generates page titles and meta descriptions from the page slug + OpenAPI operation names, so ~35+ pages end up with **identical `<title>` and `<meta name="description">` tags** across the two tabs. |
| 45 | + |
| 46 | +Examples of duplicated slugs: |
| 47 | +- `reference/api/tax-estimation/estimate-tax` ↔ `reference/partners/tax-estimation/estimate-tax` |
| 48 | +- `reference/api/transactions/create-transaction` ↔ `reference/partners/transactions/create-transaction` |
| 49 | +- (and ~30 more) |
| 50 | + |
| 51 | +### How to fix |
| 52 | + |
| 53 | +In Mintlify you can set `seo.title` and `seo.description` overrides per page group. In `docs.json`, add a `seo` block to each tab that disambiguates the titles: |
| 54 | + |
| 55 | +```json |
| 56 | +{ |
| 57 | + "tab": "API Reference", |
| 58 | + "seo": { |
| 59 | + "titleTemplate": "%s — Kintsugi API" |
| 60 | + }, |
| 61 | + "pages": [...] |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "tab": "API Reference - Partners", |
| 68 | + "seo": { |
| 69 | + "titleTemplate": "%s — Kintsugi Partners API" |
| 70 | + }, |
| 71 | + "pages": [...] |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +If Mintlify's current version supports `seo.titleTemplate` per tab, this resolves both SE-60 and SE-61 in one change. Check the Mintlify docs for the exact key name — it may be `titleSuffix` or similar. |
| 76 | + |
| 77 | +Alternatively, if you want a bigger structural fix: consolidate the two tabs into one using |
| 78 | +[Mintlify versioning or a conditional `x-internal` tag](https://mintlify.com/docs) so the same endpoint pages aren't duplicated under two paths. |
| 79 | + |
| 80 | +--- |
| 81 | + |
| 82 | +## SE-59 — 4xx Pages (Orphaned / Missing Pages) |
| 83 | + |
| 84 | +The navigation in `docs.json` appears complete — all listed pages have corresponding `.mdx` files. |
| 85 | +However, there are **6 MDX files that exist but are not linked from navigation**, which could |
| 86 | +account for old URLs that now return 404 or are unreachable: |
| 87 | + |
| 88 | +| File | Note | |
| 89 | +|------|------| |
| 90 | +| `docs/flashbacks.mdx` | References "Kintsugi Sheets" — an old product. Should be **deleted** or redirected. If there's a live URL for this page, add a Mintlify redirect to a relevant current page. | |
| 91 | +| `docs/rate-limiting.mdx` | Legitimate content, just missing from nav. Add it under the "Advanced" group in `docs.json`. | |
| 92 | +| `docs/woocommerce-integration.mdx` | Integration page not in nav. Add to navigation or confirm it should be removed. | |
| 93 | +| `docs/stripe-integration.mdx` | Same as above. | |
| 94 | +| `docs/shopify-integration.mdx` | Same as above. | |
| 95 | +| `docs/sdks/examples.mdx` | SDK examples, not linked from the SDK group in nav. Add under `docs/sdks/` group or merge content into `docs/sdks/quick-start.mdx`. | |
| 96 | + |
| 97 | +### Adding redirects for removed/moved pages |
| 98 | + |
| 99 | +If any of these files are being **deleted** (especially `flashbacks.mdx`), add a redirect in |
| 100 | +`docs.json` so the old URL doesn't 404: |
| 101 | + |
| 102 | +```json |
| 103 | +"redirects": [ |
| 104 | + { |
| 105 | + "source": "/docs/flashbacks", |
| 106 | + "destination": "/docs/getting-started" |
| 107 | + } |
| 108 | +] |
| 109 | +``` |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +## SE-62 — Temporary Redirects Need Review |
| 114 | + |
| 115 | +There is **no redirect configuration in `docs.json`**. Josh flagged that several temporary |
| 116 | +redirects on the live site all point to the same destination despite having unrelated source URLs. |
| 117 | + |
| 118 | +This is likely managed in the **Mintlify dashboard** (Settings → Redirects) rather than in code. |
| 119 | +Action: log into the Mintlify dashboard and audit the redirect rules. Remove or update any |
| 120 | +temporary redirects that are stale or pointing to incorrect destinations. |
| 121 | + |
| 122 | +If you want to move redirect management into version control, add a `"redirects"` array to |
| 123 | +`docs.json` and remove the dashboard-managed ones. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## Summary Checklist |
| 128 | + |
| 129 | +- [ ] **SE-65** — Remove/downgrade `# Python SDK` in `docs/sdks/python.mdx` (line 6) |
| 130 | +- [ ] **SE-65** — Remove/downgrade `# Ruby SDK` in `docs/sdks/ruby.mdx` (line 6) |
| 131 | +- [ ] **SE-63** — Verify or fix the `help.trykintsugi.com` link in `docs/file-upload.mdx` (lines 14, 16) |
| 132 | +- [ ] **SE-60/61** — Add `seo.titleTemplate` (or equivalent) to the two API reference tabs in `docs.json` to de-duplicate titles and meta descriptions |
| 133 | +- [ ] **SE-59** — Delete `docs/flashbacks.mdx` (old product, wrong brand) + add redirect |
| 134 | +- [ ] **SE-59** — Add `docs/rate-limiting` to navigation (Advanced group) |
| 135 | +- [ ] **SE-59** — Decide fate of `docs/woocommerce-integration`, `docs/stripe-integration`, `docs/shopify-integration`, `docs/sdks/examples` — add to nav or delete + redirect |
| 136 | +- [ ] **SE-62** — Audit redirects in Mintlify dashboard; move to `docs.json` if desired |
0 commit comments