ClearHostTroubleshooting

Getting started

Adding or updating a guide

How the team keeps this handbook up to date.

💡 The full team rules are in CONTRIBUTING.md in the repo. With Claude Code, open the repo and run /add-issue, then describe the case and paste your screenshots; Claude writes the page, blurs the screenshots and links everything up.

Every page on this site is one Markdown file in the content/ folder of the repo. To change a page, edit its file. To add a page, add a new file. The tabs, sidebar, home page, topic pages and search update automatically.

#Where files go

Folder Shows up under
content/start/ Getting started
content/ota/ OTA connections
content/issues/<group>/ Issues & fixes, grouped by topic: pricing, connecting, sync, bookings
content/tutorials/<topic>/ Tutorials, grouped by topic (e.g. rooms-rates/)
public/images/<page-name>/ Screenshots for that page

The file name becomes the web address: content/issues/pricing/price-by-number-of-guests.md is published at /issues/pricing/price-by-number-of-guests/.

Each folder in content/ is a tab in the header, and the sidebar only shows the current tab. A folder one level deeper makes a subsection: its own collapsible heading in the sidebar and a group on the tab's landing page. Give it a proper name under subsections in site.config.js (otherwise the folder name is used).

#Issues are client cases

Each page in Issues & fixes is one real case: what the client asked, what it was, and how we solved it. Use templates/new-issue.md:

  • title: the client's question in their words, so anyone recognises it, e.g. I want a different price for 1, 2 or 3 guests. Put the technical name (OBP) in the description.
  • Folder: the topic it's about (pricing, connecting, sync, bookings), not the OTA.
  • otas: the OTAs it happened on, e.g. [airbnb]. The issue then appears under Known issues at the bottom of that OTA's guide, so don't copy the fix into the OTA page. A one-line tip can stay in the OTA page's Common problems; anything with its own steps or screenshots becomes an issue.

#Connecting pages: tags, topics and keywords

  • tags put a page on a topic page (/topics/obp/) and show it under Related on every page with the same tag. The topics and their names are listed under topics in site.config.js; add a new one there.
  • Each topic also has terms. The first time a page mentions one (e.g. "OBP"), it links to the topic page automatically, and the topic page lists it under Also mentioned in. No need to add those links by hand.
  • keywords are other words people would search for (price per person, single occupancy). They're searched but not shown.

#Starting a new page

Copy templates/new-issue.md (for a problem) or templates/new-ota.md (for a new OTA) into the right folder, rename it, and fill it in. Every file starts with this header:

---
title: Rate not updating on Booking.com
description: One line shown on cards and in search.
order: 5
status: in-progress  # in-progress | complete
updated: 2026-10-30
tags: [full-sync]          # optional: topics from site.config.js
otas: [booking-com]        # optional: OTAs this is about
keywords: [rates stuck]    # optional: extra search words
---
  • status: use in-progress while a guide is unfinished or has steps nobody has confirmed. The page gets an amber In progress label in the sidebar and on the home page, plus a warning banner at the top. Change it to complete once someone has followed the guide start to finish and it worked.
  • order sets the page's position within its section (lower numbers come first).

#Adding screenshots

  1. Take the screenshot and blur hotel names, emails, tokens, IDs and guest details.
  2. Draw a red box around where to click and number the steps (macOS Preview → Markup works fine).
  3. Save it to public/images/<page-name>/step-1-something.png (lowercase, dashes, no spaces).
  4. Add it to the page (images are moved to our CDN later with npm run media:push; it still shows straight away):
![Step 1 - open settings](/images/<page-name>/step-1-something.png)

#Writing tips

  • One action per numbered step, with the button name in bold, exactly as it appears on screen.
  • Put the screenshot directly under the step(s) it shows.
  • Add a Common problems section whenever you fix something new. That section saves the next person the most time.
  • Start a line with > to show a highlighted note box.