Dashboard
DocsAGENTS
Docs

Repository Instructions

This repo holds the source content for https://docs.botsubscription.com - documentation pages written in Markdown / MDX, plus the screenshots in static/img/.

The folder structure is the site structure - advanced/coupons.mdx publishes to /advanced/coupons/. Images are referenced with an absolute /img/... path.

Before writing, read CONTRIBUTING.md in this repo: it has the frontmatter requirements, the list of MDX components the theme provides, and the image rules. Only components on that list exist - anything else breaks the build.

Validate before committing:

node .github/scripts/validate-content.mjs

Fix everything under Errors. Warnings are the SEO rules below and should be fixed unless there is a good reason not to.

Do not rename files or change the slug of an existing page - that changes a live URL. Do not edit .github/ or .contentrc.json.

Maintainer Preferences

These preferences apply throughout this repository. The API-specific guidance below takes precedence over generic SEO rules when they conflict.

Scope and Authorization

  • The public API reference serves project developers using project API keys. Document the required API-key scopes on each endpoint page.
  • Keep central and customer-scoped endpoints, OAuth/JWT flows, human-admin permissions, and web-UI-only procedures such as imports out of this reference. Do not add explanations comparing these excluded systems with the project API.
  • Exclude endpoints that reject project API keys. Do not offer JWT authentication as a workaround in REST, webhook, or live-update documentation; report missing API-key support to the user.
  • Unannounced features, including the affiliate API, stay out of public documentation until the user approves their inclusion.
  • When asked to review, report findings before editing. Once documentation changes are authorized, carry them through the affected overview, endpoint pages, examples, and contract checks.
  • Backend coordination is for questions and confirmation. Report implementation gaps to the user for planning; do not change backend code or instruct another agent to change it without explicit authorization.
  • Do not commit, push, sync, or deploy unless the user requests it for the current work. Earlier publishing requests are not standing authorization.

Verify the Current Contract

  • For API refreshes, ask the established backend agent what changed before broadly auditing its work. Use focused source checks and runtime tests to resolve uncertainties.
  • Read detailed backend reference pages as well as the main catalog. An internal route's existence alone does not make it part of the public project API.
  • Keep outbound integration webhooks distinct from inbound payment-provider notifications such as /ipn/.
  • Document current behavior. Do not turn reference pages into a changelog with pending changes, future plans, or migration notes for parameters that never shipped.
  • Check uncertainties with the backend rather than guessing. Distinguish backend-confirmed behavior, observed live responses, and offline validation; do not claim one proves another.
  • Prefer consistent contracts across endpoints. If the backend is inconsistent, report the discrepancy, document the verified behavior where relevant, and avoid vague caveats that conceal it.

API Page Structure and Wording

  • Follow the existing resource dropdown and separate endpoint-page structure. Include the method, path, scopes, parameters, request examples, and response samples. Keep a separate overview only when it adds useful shared guidance.
  • Check the website repository's sidebar configuration when adding pages; a link in the API overview does not make an endpoint discoverable in the sidebar.
  • Put realistic, sanitized success and relevant error responses in the API playground's sample-response tabs. Preserve the actual status, envelope, fields, types, nullability, and conditional shapes. Extra or missing fields are documentation mismatches.
  • Use prose to explain behavior and decisions, not to repeat response fields already shown in samples. Avoid concluding sections that merely say "Response data contains".
  • Explain multi-step operations in plain language: what each step does, what to send next, and which values to reuse. Make preparation, activation, and redemption easy to distinguish.
  • Apply shared features such as Idempotency-Key consistently to eligible endpoints, rather than highlighting them on one arbitrary page.
  • Keep overview rules concise. Do not single out arbitrary nested fields already covered by a general rule. Explain meaningful endpoint-specific exceptions on the relevant endpoint pages.
  • Declared date/time fields in REST responses use UTC ISO strings with milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ). Counts and durations remain numeric; opaque metadata retains its original types. Verify request-date formats separately; mention Unix timestamps only when the backend confirms that the input still uses them.
  • Use decimal strings in monetary examples. Verify precision and normalization rules instead of assuming every endpoint or currency has the same limits.
  • Prefer readable duration examples such as "1 month", "2 days", "6 weeks", and "lifetime". Confirm accepted inputs before documenting them; do not promote shorthand aliases or symbols as the recommended format.
  • Link to the authoritative provider-specific requirements rather than duplicating an expanding parameter list on merchant-account installation pages.
  • Favor direct, useful explanations over exhaustive caveats, redundant permission matrices, and unnecessary overviews. Keep technical endpoint titles precise; do not force marketing keywords into them.

Contract Tests and Fixtures

  • Maintain request/response contract coverage for every documented endpoint and relevant webhook behavior. Cover live updates only through supported authentication. Include representative success and error cases, not just routes or empty lists.
  • Use observed responses to improve documentation examples, replacing real identifiers, customer data, and secrets with dummy values that preserve the format.
  • Keep persistent live-test configuration in the ignored .env.contract and credentials in ignored secret files. Never overwrite a configured file with the example. Fail early with clear messages when required configuration is missing.
  • Give every configuration variable a plain-language explanation and a realistic dummy example. Specify whether an ID is an internal UUID or an external Telegram ID / Discord snowflake. Avoid duplicate configuration for the same concept.
  • Make repeated runs automatic: create temporary plans, coupons, payment requests, and merchant accounts where possible; reuse IDs created by earlier lifecycle steps and clean up temporary resources. Do not require fresh expiring IDs on every run.
  • Support multiple configured payment providers. Reuse a local webhook receiver with cloudflared when testing public webhook deliveries instead of requiring a manually supplied public URL.
  • Never delete the reusable API_TARGET_ID. Restore and verify its original state after updates. Run successful target-deletion tests only when a separate API_DISPOSABLE_TARGET_ID is explicitly supplied; otherwise skip them.
  • Do not require target creation or custom-hostname changes for routine runs. Report optional exclusions as skips and distinguish them from failures or untested behavior.
  • Run npm run test:contracts for API content changes, plus relevant harness tests when changing the test suite. Live tests use the configured test environment and respect API_ALLOW_WRITES and the user's authorized scope. Never report offline checks as live API coverage.

Publishing Context

  • This repository contains content; the site generator, theme, API sidebar configuration, and deployment live in the separate website repository.
  • A local hook was configured to sync successful pushes to docs-content/main into the website repository. Check its current configuration and result when publishing is requested; do not assume a push alone proves the public site is updated.
  • The requested automation is local to this computer. Do not replace it with GitHub-hosted sync or add automatic rebuilds/restarts without authorization.

SEO & Content Guidelines (PRIORITY)

Every piece of content must be optimized around these target keywords.

Primary Keywords (High Priority)

  1. telegram subscription bot - Core product offering for Telegram
  2. discord subscription bot - Core product offering for Discord
  3. discord payment bot - Payment functionality for Discord
  4. paid telegram channel bot - Monetization angle for Telegram

Unique Positioning

"subscription bot Telegram Discord" - This is BotSubscription's unique angle. Content should emphasize:

  • Multi-platform support (both Telegram AND Discord)
  • Subscription/membership automation
  • Bot-based payment processing

Content Requirements - Strong focus on SEO

When writing or updating ANY documentation:

  1. Titles - Include at least one primary keyword naturally (e.g., "Set Up Your Telegram Subscription Bot")
  2. Descriptions - Lead with keywords, mention both platforms when relevant
  3. H1/H2 headings - Use keyword variations in section headings
  4. Body content - Naturally weave in keywords; avoid stuffing
  5. Internal links - Use keyword-rich anchor text (e.g., "configure your Discord payment bot" not "click here")

Title Optimization

  • Place primary keywords at the BEGINNING of titles, not the end
  • Bad: "BotSubscription — Paid Memberships for Telegram & Discord"
  • Good: "Telegram & Discord Subscription Bot — BotSubscription"
  • Aim for 50-60 characters including brand name
  • Include both platform names (Telegram, Discord) and product type (subscription bot)

Strong Tags for Keywords

Use <strong> tags to emphasize primary keywords in page content:

  • Wrap keywords like "subscription bot", "Telegram", "Discord" in <strong> tags
  • Place strong tags in the first 100 words where natural
  • Do not overuse; 3-5 strong-tagged keywords per page is sufficient
  • Example: <strong>subscription bot</strong> for <strong>Telegram</strong> and <strong>Discord</strong>

H1 Heading Requirements

  • The H1 MUST contain primary keywords: "subscription" and "bot"
  • Include platform names where natural
  • Good: "The subscription bot for Telegram & Discord"
  • Bad: "Automate Your Paid Community" (missing keywords)

H2/H3 Headings with Keywords

  • Include target keywords naturally in at least 2-3 subheadings per page
  • Good examples: "5-Minute Bot Setup", "Automated Subscription Renewals", "One subscription bot, two platforms"
  • Avoid generic headings like "Features" or "How It Works" when keyword variants fit naturally

Image SEO

  • Alt text: Include keywords naturally; describe what's visible + why it matters (aim ≤125 chars)
    • Example: alt="BotSubscription - Telegram and Discord subscription bot"
  • Title attribute: Include keywords; can be similar to alt text
    • Example: title="Telegram Discord subscription bot"
  • Filenames: lowercase-hyphens; include platform + feature
    • Example: telegram-subscription-bot-dashboard.png
  • Every <img> should have both alt and title attributes with relevant keywords

Sentence Length

  • Target 15-18 words average per sentence
  • Too high (25+ words): Break long sentences into shorter ones
  • Too low (under 10 words): Combine choppy sentences using conjunctions
  • Balance readability with natural flow; vary sentence length for rhythm

Anchor Text Rules

  • Every link MUST have descriptive anchor text (for accessibility and SEO)
  • NEVER use duplicate anchor text on the same page
  • If the same destination appears multiple times (nav, mobile menu, footer), vary the anchor
  • Use descriptive anchors that indicate destination, not "click here" or "learn more"
  • For icon-only links, add screen-reader text: <span class="sr-only">Link description</span>

Always format external links with proper attributes:

<a href="https://example.com" target="_blank" rel="nofollow noopener noreferrer">descriptive anchor</a>
  • Include 2-5 relevant internal links per page
  • RAG-verify each target exists before linking
  • If a relevant page cannot be verified, add a TODO comment instead of a broken link: 
    {/* TODO link: "Anchor text" -> /suggested-slug */}

Keyword Variations to Use

  • Telegram: subscription bot, paid channel bot, membership bot, payment bot
  • Discord: subscription bot, payment bot, paid server bot, membership bot
  • Combined: subscription bot for Telegram and Discord, multi-platform subscription bot

User-Friendly First, Keywords Second

Keywords must always make sense in context. Never force awkward phrasing just to include a keyword.

Examples of what NOT to write:

  • "Running a paid Telegram channel bot" (doesn't make grammatical sense)
  • "Run Discord payment bot from one account" (awkward)
  • "What This Subscription Bot Does" (robotic heading)

Examples of natural keyword usage:

  • "BotSubscription is a Telegram subscription bot that..." (keyword as noun)
  • "Set up your Discord payment bot in minutes" (keyword as object)
  • "Features" or "Core Features" (user-friendly heading, keywords in body)

The rule: If a sentence sounds awkward when read aloud, rewrite it. A user-friendly sentence without a keyword is better than an awkward sentence with one.

What to Avoid

  • Generic phrases like "membership management" without platform context
  • Overusing "BotSubscription" as the only keyword
  • Titles/descriptions that don't mention Telegram or Discord
  • Content that focuses on only one platform when both apply
  • Forcing keywords into unnatural sentence structures
  • Robotic or awkward headings just to include keywords
Last updated: