docs: audit and improve Gitpay product documentation - #1543
Merged
Conversation
_site/ was a stale, previously-built copy of the site checked directly into gh-pages. It drifted out of sync with the real source (its index.html still carried the old theme's placeholder title/metadata), and GitHub Pages rebuilds the site from source on every deploy anyway, so the committed copy was redundant and misleading during review.
- Replace the unused root of the site (no index.md existed at "/", so
GitHub Pages was serving a stale build with the old theme's default
title, "Docs is a premium documentation Jekyll theme") with a proper
redirect to /en/, plus a visible link to the Portuguese docs.
- Add jekyll-sitemap and jekyll-redirect-from so the site emits a real
sitemap.xml and generates redirect stubs for retired URLs, and add a
robots.txt pointing at it.
- Give the English and Portuguese homepages their own SEO title and
description instead of falling back to identical, English-only
metadata on both.
- Rewrite README.md, which was still the unedited "Docs" theme sales
page (features list, ThemeForest support link), as an actual
contributor guide for this repository.
- Rewrite the Contact pages (EN/BR), which had lorem-ipsum body copy,
a Portuguese title on the English page, a non-functional Formspree
endpoint (an unregistered placeholder address), and an unrelated New
York City map embed.
- Fix thanks.md's broken link (bare "gitpay.me" href, missing scheme)
and mixed-language copy on an English-only page.
- Fix the "edit this page" link on every post, which rendered as a
relative /blob/... URL whenever site.github.repository_url wasn't
populated, and was hardcoded to Portuguese on English pages.
- Redirect the orphaned duplicate /news/ page to /en/news/.
- Disambiguate several docs pages that shared an identical <title>
across different roles ("Getting started" x3, "General questions"
x2, and their Portuguese equivalents).
These were never Gitpay content: they're unedited lorem-ipsum pages
from the original "Docs" theme (installation, collections, drafts,
pages in both languages) and 13 theme demo blog posts dated 2017-05-25
("How To Setup Naked Domain SSL...", authored by "John Black"). None
were linked from navigation, but they were still built and published,
so redirect_from is added on the closest relevant real page (or the
homepage, for the demo posts with no topical equivalent) rather than
leaving the old URLs to 404.
Also removes _docs/en(br)/posts.md, an orphaned page claiming "rewards
can be paid with credit card or PayPal" and linking a pre-React-Router
hash URL (/#/profile/payment-options) — superseded by payments.md,
which now covers all three current providers.
The docs previously described payouts inconsistently: payments.md mentioned Stripe and PayPal, payouts.md and whop-payout-setup.md only covered Stripe and Whop, and disputes-and-refunds.md didn't mention PayPal at all. Verified against the current app (src/providers/ — a Stripe/Whop connector abstraction selected per-payment via PAYMENT_PROVIDER — plus a separate, still-active PayPal integration in src/modules/orders and src/services/payments that predates that abstraction and isn't part of it): - All three providers are real and current, not sequential replacements of each other. Stripe is the default; Whop is a fully supported alternative (onboarding, checkout, payouts, disputes, and refunds all implemented); PayPal remains wired for charging and payouts on some accounts, including a 2024 migration adding a paypal_payout_id column, but isn't part of the newer Stripe/Whop provider abstraction or its architecture doc. - payments.md and payouts.md now list all three consistently. - The existing 8%-platform-fee and Whop dispute/dispute-alert figures in disputes-and-refunds.md matched the app's disputeService.ts / refundBalanceService.ts / extraFeeService.ts exactly, so those are left as-is; a note is added that PayPal-funded payments follow a different, undocumented dispute/refund path. - funding-issues.md gains the task-definition template that used to live on the orphaned, unlinked _docs/usage.md page (redirected here). Exact PayPal fee/timing details and whether PayPal is offered to new accounts couldn't be confirmed from the docs repo alone — see the PR description's "Needs human confirmation" section.
…ne article The blog had, for six professions (freelance developers, designers, growth marketers, content creators, consultants, copywriters), up to five separate posts covering the same "deliver work, send a payment link instead of an invoice" idea — differing mainly in title framing and which keyword they targeted, most explicitly tagged `categories: [Payments, "Programmatic SEO"]`. That's the exact duplicate-content pattern that hurts rather than helps organic search. For designers, consultants, and content creators, an existing substantive (~180-line) article already covered the topic well; the four thin duplicates for each are now redirects into it (redirect_from front matter + jekyll-redirect-from, so old URLs still resolve instead of 404ing). For growth marketers and copywriters, no substantive original existed — all four posts were thin templates. Replaced with one consolidated, audience-specific article each, redirecting the other three. For freelance developers, the original piece is rewritten and broadened into a single cornerstone article, "How to Request Payment After Delivering Software Work," covering both the freelance/invoice-request workflow *and* the GitHub-issue-bounty workflow (fund, claim, PR, release, payout) that the original didn't touch. All five old freelance-developer URLs redirect here. The remaining profession posts (course creators, motion/product/UI designers, SEO consultants, agencies, coaches, illustrators, indie hackers, mentors, photographers, solopreneurs, video editors) and all Portuguese-language duplicates of this same pattern were not touched in this pass — see the PR description for the full list flagged for a follow-up consolidation.
alexanmtz
pushed a commit
to alexanmtz/gitpay
that referenced
this pull request
Sep 6, 2026
The previous attempt at this (in worknenjoy#1543) added .gitignore's _site/ entry but the removal itself got reverted by an in-progress `git reset` while splitting that PR into commits, so the merge ended up re-committing _site/ anyway — with my local validation build's output baked in (Jekyll v3.10.0, localhost:4000 canonical URLs), which is worse than the original stale copy it was meant to replace. This time: a plain `git rm -r --cached _site`, committed immediately, nothing in between to undo it. Verified the diff below is 202 pure deletions with no other changes.
alexanmtz
added a commit
that referenced
this pull request
Sep 6, 2026
… regression (#1546) * Link the refund policy from disputes-and-refunds.md Adds a short "Our refund policy" section stating the general rule (completed/accepted work is non-refundable, with the usual fraud/duplicate/undelivered carve-outs) and points to the Refunds clause now in the Terms of Service (#1545), so the practical debit/credit mechanics on this page sit next to the policy they implement. There's no direct URL for the Terms of Service in the app today — it opens as an in-page dialog from the site footer's "Legal" menu rather than living at its own route — so the link points to gitpay.me with that noted, instead of a fabricated deep link. * Actually stop tracking _site/ this time The previous attempt at this (in #1543) added .gitignore's _site/ entry but the removal itself got reverted by an in-progress `git reset` while splitting that PR into commits, so the merge ended up re-committing _site/ anyway — with my local validation build's output baked in (Jekyll v3.10.0, localhost:4000 canonical URLs), which is worse than the original stale copy it was meant to replace. This time: a plain `git rm -r --cached _site`, committed immediately, nothing in between to undo it. Verified the diff below is 202 pure deletions with no other changes. --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A focused audit-and-fix pass on docs.gitpay.me (this
gh-pagesbranch), grounded in the current app source (worknenjoy/gitpay@master) rather than assumptions. Fixes site metadata that was still showing the original Jekyll theme's placeholder title, corrects payment/payout documentation to reflect that Stripe, Whop, and PayPal all coexist today (not a Whop-replaces-everything migration), removes leftover theme placeholder content, consolidates duplicated "programmatic SEO" posts for six professions into single articles with redirects, and adds one cornerstone article on requesting payment after delivering software work.No application code was touched — this PR only changes the
gh-pagesdocumentation site.Problems found
Metadata / site health
index.md/index.htmlexisted at the true site root (only under/en/and/br/), so GitHub Pages kept serving a stale, previously-built copy with the original theme's title,"Docs is a premium documentation Jekyll theme"— exactly the placeholder the task description described._site/build directory was committed directly togh-pagesand had drifted out of sync with source.README.mdwas still the theme seller's unedited page (feature list, ThemeForest support link).<title>/description metadata.sitemap.xmlorrobots.txt.my_name@gmail.com— never functional), and an irrelevant New York City map embed.thanks.mdhad a broken link (href="gitpay.me", missing scheme) and Portuguese copy on an English-only page./blob/...URL locally (depends onsite.github.repository_url, which isn't always populated) and was hardcoded to Portuguese even on English pages./news/and/en/news/were byte-identical duplicate pages.<title>tags, in both languages.Payment/payout documentation contradictions
payments.mdmentioned Stripe and PayPal;payouts.mdandwhop-payout-setup.mdonly covered Stripe and Whop;disputes-and-refunds.mddidn't mention PayPal. None of these were wrong exactly, but together they read as if the docs disagreed on which providers exist._docs/posts.md) claimed "rewards can be paid with credit card or PayPal" and linked a pre-React-Router hash URL (/#/profile/payment-options— the path itself still resolves, but the page's framing is years out of date next to the current payments.md/payouts.md).Duplicated / superficial content
categories: [Payments, "Programmatic SEO"]and were 30–55 lines of templated content._docs/{en,br}/installation.md,collections.md,drafts.md,pages.mdwere unedited lorem-ipsum pages from the original theme (never linked in navigation).2017-05-25(post,post0–post7,post60–post63) were the theme's own demo blog posts (fake author "John Black", generic titles like "How To Setup Naked Domain SSL With Github Pages"), still being built and published.Missing documentation
funding-issues.md(the "fund a GitHub issue" page) was thin; a genuinely useful task-definition template existed only on an orphaned, unlinked page (usage.md).Evidence used
src/providers/{registry,types,PaymentProvider}.ts,src/providers/{stripe,whop}/*,docs/payments-providers.md(the app's own architecture doc) — confirms Stripe and Whop share one connector abstraction selected viaPAYMENT_PROVIDER, with per-resourceproviderfields so old and new payment requests keep working side by side.src/modules/orders/{orderBuilds,orderPayment}.ts,src/services/payments/authorizations/authorizePaypalPayment.ts,src/services/payments/refunds/refundPaypalPayment.ts,frontend/src/containers/account/payout-settings/payout-settings-paypal.ts, and migration20240607142810-add-paypal-payout-id-to-transfer.js(2024) — PayPal charging and payouts are real, current, separate code, not part of the Stripe/Whop abstraction.src/services/payments/disputes/disputeService.ts,src/services/payments/refunds/refundBalanceService.ts,src/services/payments/fees/extraFeeService.ts(WHOP_DISPUTE_FEE_CENTS=1500,WHOP_DISPUTE_ALERT_FEE_CENTS=2900) — matched the existing docs numbers exactly, so those were left unchanged.payout-settings-whop,whop-identity-panel,whop-payout-method-panel,whop-account-tabs— matchwhop-payout-setup.md's described flow (Identity & business tab, Payout method tab, "Add payout method on Whop").frontend/src/main/routes.tsxusesHashRouter, andfrontend/src/main/routes-sitemap.jsconfirms/use-cases/service-paymentsis a live route — the CTA links used across the profession posts (https://gitpay.me/#/use-cases/service-payments) are current, not stale.bundle exec jekyll build, plainjekyll/jekyll-seo-tag/jekyll-sitemap/jekyll-redirect-from, since the pinnedgithub-pagesgem needs Ruby 2.7 and wouldn't install under Ruby 3.3 here) reproduced the missing-root-page issue and confirmed every fix below.Content changes
Created
_posts/2026-03-30-how-to-request-payment-after-delivering-software-work.md— cornerstone article. Covers both freelance/invoice-replacement delivery and the GitHub-issue-bounty flow, distinguishes a payment request from an invoice without tax/legal claims, includes a concrete example and a common-mistakes checklist, links tofunding-issues,claims,payments,payouts,whop-payout-setup,disputes-and-refunds, and ends with one CTA. Redirects from all 5 old freelance-developer post URLs._posts/2026-03-26-get-paid-growth-marketers.md,_posts/2026-03-26-get-paid-copywriters.md— rewritten in place as single consolidated, audience-specific articles (no substantive original existed for either profession); redirect from their other 3 duplicate URLs each.index.html,robots.txtat site root.Rewritten
README.md,en/contact.md,br/contact.md,thanks.md,_includes/post-meta.html._docs/en/payments.md,_docs/en/payouts.md,_docs/en/disputes-and-refunds.md(PayPal consistency),_docs/{en,br}/funding-issues.md(task-definition template added)._posts/2026-03-16-...designers...md,2026-03-17-...consultants...md,2026-03-19-...content-creators...md— kept as canonical (already substantive), givenredirect_fromfor their 4 duplicate URLs each.Consolidated / redirected (old URL → new canonical, via
redirect_from+jekyll-redirect-from)_docs/{en,br}/{installation,assets,structure}.md→configuration.md;collections.md→getting-started.md;drafts.md→faq.md;pages.md,posts.md→payments.md;usage.md→funding-issues.md.2017-05-25-post*demo posts → homepage (en/index.md)./news/→/en/news/.Intentionally left unchanged
_docs/en/{claims,whop-payout-setup,pull-requests,delivering-work,maintainer,validating-work,releasing-bounties,git-workflow,getting-started-contributor}.mdand role hub pages (sponsor.md,contributor.md,service-provider.md) — read in full, already accurate, specific, and reasonably cross-linked; no factual issues found.Needs human confirmation
disputeService.ts/refundBalanceService.tsexists for PayPal in the code, so the docs now say this "follows PayPal's own process" without specifics — confirm if there's a real internal process worth documenting.WHOP_DISPUTE_ALERT_FEE_CENTS($29) accuracy: the code comment sourcing this constant explicitly says it's "sourced from third-party research, not Whop's own pricing docs" — worth verifying against a real Whop invoice.ruby "2.7.0", but.circleci/config.yml'sdocsjob runscircleci/ruby:2.3.7— these already didn't match before this PR; worth checking whether CI docs builds currently succeed at all.SEO considerations
/news/duplicate) gets aredirect_fromentry rather than being silently removed, so any existing inbound links or indexed pages 200/redirect instead of 404ing./get-paid-growth-marketers/,/get-paid-copywriters/) since no single original among their four thin duplicates deserved to "win"; all four old URLs redirect to the new one.jekyll-sitemapwasn't previously enabled, so none of this was in a sitemap at all before. It is now, and includes the redirect stubs' targets (not the stubs themselves, which arenoindex).Needs follow-up (not done in this PR, to keep the diff reviewable)
redatores,desenvolvedores-freelancer,designers,growth-marketers,copywriters,product-designers,motion-designers,ui-designers, etc.). Recommend the same original-kept-or-consolidated + redirect treatment as a follow-up PR._docs/br/payments.mdgot the redirect-source front matter update but not the same content expansion;_docs/br/payouts.mdand_docs/br/disputes-and-refunds.mdweren't touched at all. These should get the equivalent updates in a follow-up so the languages don't drift further apart.pull-requests.md,delivering-work.md,git-workflow.md,faq.md,faq-contributor.md,maintainer.md) are reachable only via in-content "Next steps" links, not the sidebar (_data/navigation_docs.yml). They aren't broken, but a deliberate IA pass could make them easier to find directly.Validation
bundle exec jekyll build— succeeds, 0 errors (validated with plainjekyll/jekyll-seo-tag/jekyll-sitemap/jekyll-redirect-from/jekyll-feed/kramdown-parser-gfm, since the pinnedgithub-pagesmeta-gem requires Ruby 2.7 and won't install under the Ruby 3.3 available here — flagged above).htmlproofer ./_site --disable-external --checks Links,Scripts,Images— 224 failures → 0 failures after fixes (the "edit this page" link across every post/page, plusthanks.md's broken link)._docs,_posts, and page file — 0 problems.<title>scan across all 276 built pages — 9 groups → 1 remaining (EN/BRFAQpages sharing the literal word "FAQ", different languages and URLs — not a real duplicate-content issue)./redirects to/en/with correct title/description/canonical;/robots.txtand/sitemap.xmlgenerate correctly; everyredirect_fromURL (installation/collections/drafts/pages, the 2017 demo posts, all retired profession-post URLs,/news/) produces a working redirect stub to its new canonical page.markdownlint-clirun against all new/changed Markdown — only pre-existing-styleMD013(line length) warnings, present identically in untouched files (no.markdownlintconfig exists in this repo, so long-line prose is the house style, not a violation).aspell/hunspell) was available in this environment to run automatically; content was proofread manually.🤖 Generated with Claude Code
https://claude.ai/code/session_01PtCXQDsoFovaYbCxvdjua2
Generated by Claude Code