Skip to content

docs: publish a project page on GitHub Pages - #38

Merged
Chemaclass merged 1 commit into
mainfrom
docs/github-pages
Aug 1, 2026
Merged

docs: publish a project page on GitHub Pages#38
Chemaclass merged 1 commit into
mainfrom
docs/github-pages

Conversation

@Chemaclass

Copy link
Copy Markdown
Contributor

Summary

Publishes a project page at https://php-lightning.github.io/lnaddress/ and fixes two
stale statements in the architecture doc.

Landing page

docs/index.html — one self-contained file (no CDN, no build step, light and dark
theme), aimed at someone who has never heard of a Lightning Address:

  • What it is — the address is just HTTPS: bob@example.com resolves to
    /.well-known/lnurlp/bob
  • Why self-host — the address lives on your domain, payments settle straight to your
    node, no new stack to operate, several identities per deployment
  • How it works — the four steps of the LNURL-pay flow with the actual request and
    response payloads
  • Quick start — install, both config files, the well-known route
  • Under the hood — the Gacela module flow and how to use the facade without HTTP
  • FAQ — custody, backends other than LNbits, multi-user, browser wallets, what is not
    implemented

.github/workflows/pages.yml deploys docs/ with upload-pages-artifact /
deploy-pages on pushes that touch docs/, and can be triggered manually.
docs/.nojekyll keeps the markdown guides from being run through Jekyll; the page links
to them on GitHub.

Doc corrections

While checking every claim in docs/ against the code:

  • EmptyBackendInvoice was described as the null object used for users without a backend.
    InvoiceFactory::getBackendForUser() always builds LnbitsBackendInvoice, so the class
    is currently unused — the table now says so.
  • The "not implemented" section mentioned an image-metadata TODO that no longer exists
    after the LnurlPayMetadata extraction. Only the LUD-12 commentAllowed TODO remains.

Everything else in the README and docs/ was verified against the current source:
config setters and their defaults, response keys (pr, status, reason), routes,
composer scripts, and the CI job list.

Notes

GitHub Pages must have its source set to GitHub Actions for the workflow to publish.

Test plan

  • composer test-all green (26 tests / 33 assertions)
  • HTML parses with no unclosed tags; all links checked
  • Pages deployment succeeds after merge

Add docs/index.html, a self-contained landing page explaining what the library
does, why self-hosting a Lightning Address is worth it, how the LNURL-pay flow
works and how to configure it, plus a workflow that deploys docs/ to Pages on
every push to main.

Also corrects two stale claims in docs/architecture.md: EmptyBackendInvoice is
not wired into the factory, and the image-metadata TODO no longer exists.
@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Aug 1, 2026
@Chemaclass Chemaclass self-assigned this Aug 1, 2026
@Chemaclass
Chemaclass merged commit 36b786e into main Aug 1, 2026
8 checks passed
@Chemaclass
Chemaclass deleted the docs/github-pages branch August 1, 2026 22:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant