Skip to content

docs: Reformat documentation with heading hierarchy and Juspay Hyperswitch branding#1

Open
atulp-hyperswitch wants to merge 2 commits intomainfrom
reformat-documentation-rules
Open

docs: Reformat documentation with heading hierarchy and Juspay Hyperswitch branding#1
atulp-hyperswitch wants to merge 2 commits intomainfrom
reformat-documentation-rules

Conversation

@atulp-hyperswitch
Copy link
Copy Markdown
Owner

Summary

This PR reformats 10 documentation files to improve consistency, clarity, and branding according to GitBook documentation standards.

Changes Applied

Rule 1 - Heading Hierarchy

  • Each page has exactly one H1 at the top
  • Converted bold section titles to appropriate heading levels (H2, H3)
  • Fixed heading hierarchy - no skipped levels (e.g., no H2 → H4 jumps)

Rule 2 - Brand Name: "Juspay Hyperswitch"

  • First mention on each page: "Hyperswitch" → "Juspay Hyperswitch"
  • Page titles and H1 headings: Added "Juspay" prefix
  • Product introductions and descriptions: Updated to use "Juspay Hyperswitch"
  • Subsequent mentions on the same page kept as "Hyperswitch" for readability
  • Technical identifiers (code blocks, CLI commands, URLs) left unchanged

Rule 7 - Frontmatter Description

  • Added proper YAML frontmatter with description field to all files
  • Format: [Action verb] [task/topic] to [reader benefit]
  • Length: 15-30 words
  • No full stop at the end
  • Unique descriptions for each page

Files Updated

  1. reconciliation/README.md
  2. reconciliation/getting-started-with-recon.md
  3. ai-powered-cost-observability/README.md
  4. ai-powered-cost-observability/uploading-fee-reports-for-analysis.md
  5. revenue-recovery.md
  6. reconciliation-product/README.md
  7. reconciliation-product/example-e-commerce.md
  8. reconciliation-product/how-reconciliation-works.md
  9. reconciliation-product/roadmap.md
  10. reconciliation-product/statuses-in-reconciliation.md

Testing

  • All files maintain existing content (no information removed)
  • Heading hierarchy validated
  • Frontmatter descriptions follow the required format

Atul P added 2 commits March 23, 2026 13:36
…ms.txt generation

Add description metadata to markdown files to support llms.txt generation:

- Extracted first meaningful paragraph from each file

- Added description field to frontmatter where missing

- Updated 174+ markdown files across the documentation

- Supports better indexing and searchability for LLMs
…nd Juspay Hyperswitch branding

Apply documentation formatting rules:
- Rule 1: Fix heading hierarchy (single H1, proper H2/H3 structure)
- Rule 2: Add Juspay Hyperswitch branding to identity-establishing contexts
- Rule 7: Add proper frontmatter descriptions (15-30 words, action verb format)

Files updated:
- reconciliation/README.md
- reconciliation/getting-started-with-recon.md
- ai-powered-cost-observability/README.md
- ai-powered-cost-observability/uploading-fee-reports-for-analysis.md
- revenue-recovery.md
- reconciliation-product/README.md
- reconciliation-product/example-e-commerce.md
- reconciliation-product/how-reconciliation-works.md
- reconciliation-product/roadmap.md
- reconciliation-product/statuses-in-reconciliation.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant