=== gitblock — GitHub Blocks ===
Contributors: thrijith, abhijitrakas
Donate link: https://thrijith.com
Tags: github, block, profile, repository, developer
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: MIT
License URI: https://opensource.org/licenses/MIT

Show GitHub profiles, organizations and repositories in the block editor, with top languages and contribution graphs.

== Description ==

gitblock adds three blocks to the block editor:

* **GitHub User**: a profile card with bio, company, location, website, join date, repository/follower/following counts, the contribution graph for the last year, pinned or top repositories, top languages and organizations.
* **GitHub Organization**: an organization card with description, location, website, stats, pinned or top repositories, top languages and public members.
* **GitHub Repository**: a repository card with description, topics, website, license, stars, forks, watchers, open issues, a language breakdown and the latest release.

Search for an account or repository right in the block, pick it from the suggestions and the card appears. Every section can be switched on or off in the block settings, and you choose whether to list pinned, most starred or recently updated repositories. Cards follow your theme's colors and fonts, work in light and dark themes and adapt to narrow columns.

Pinned repositories and the contribution graph come from GitHub's GraphQL API, which needs a token. Without one, the most starred repositories are listed instead and the graph is hidden.

GitHub responses are cached (one hour by default, see the `gitblock_cache_ttl` filter), so pages stay fast and well within GitHub's rate limits.

= External service =

This plugin fetches public data from the [GitHub REST and GraphQL APIs](https://docs.github.com/rest) (`api.github.com`) when a block is rendered and when you search for accounts or repositories in the editor. The requested username, organization or repository name, your site's address (in the User-Agent header) and, if you configure one, your GitHub token are sent to GitHub. Avatars are loaded from GitHub in visitors' browsers. See GitHub's [Terms of Service](https://docs.github.com/site-policy/github-terms/github-terms-of-service) and [Privacy Statement](https://docs.github.com/site-policy/privacy-policies/github-general-privacy-statement).

== Installation ==

1. Install and activate the plugin.
2. Optional: add a GitHub token under **Settings → General → GitHub (gitblock)**.
3. Add the **GitHub User**, **GitHub Organization** or **GitHub Repository** block to a post or page.

== Frequently Asked Questions ==

= Do I need a GitHub token? =

Only for pinned repositories and the contribution graph, which use GitHub's GraphQL API. Everything else works without one: GitHub allows 60 requests an hour from your server, which caching usually covers. For those features or on busy sites, [create a fine-grained token](https://github.com/settings/personal-access-tokens/new) with no extra permissions and paste it into Settings → General. You can also define `GITBLOCK_GITHUB_TOKEN` in `wp-config.php` instead.

= Is my token exposed to visitors or editors? =

No. Since 2.0.0 all GitHub requests, including the account search in the editor, are made by your server.

= How do I change the cache duration? =

`add_filter( 'gitblock_cache_ttl', function () { return 6 * HOUR_IN_SECONDS; } );`

= Where is the source code? =

The editor scripts and styles in `build/` are compiled from the human-readable source in the plugin's `src/` folder. To rebuild them, run `npm install && npm run build` in the plugin folder (Node 22 or later).

= How are top languages calculated? =

For users and organizations: by the primary language of their 100 most recently updated public repositories, excluding forks. For a repository: by bytes of code, as reported by GitHub.

= Can I restyle the cards? =

Yes. The cards use CSS custom properties such as `--gitblock-accent`, `--gitblock-radius`, `--gitblock-border` and `--gitblock-graph` (contribution graph color) on `.gitblock-card`.

== Screenshots ==

1. GitHub User card with contribution graph, pinned repositories, top languages and organizations.
2. GitHub Repository card with topics, stats, language breakdown and latest release.
3. GitHub Organization card with most starred repositories, top languages and public members.
4. Every section can be switched on or off; choose pinned, most starred or recently updated repositories.
5. Search for an account or repository right in the block.
6. Optional GitHub token under Settings → General.

== Changelog ==

= 2.0.0 =
* New: GitHub Repository block with topics, stats, language breakdown and latest release.
* New: pinned, most starred or recently updated repositories on user and organization cards.
* New: top languages on user and organization cards.
* New: contribution graph on user cards (needs a GitHub token).
* New: show or hide every card section from the block settings.
* New: redesigned, theme-aware cards that work in light and dark themes and on small screens.
* New: account search with avatars for both the user and organization blocks.
* New: website and bio/description on cards, organization follower and member counts.
* New: block alignment and margin support, block previews in the inserter.
* New: GitHub responses are cached; `gitblock_cache_ttl` filter.
* New: the GitHub token is optional and can be set with the `GITBLOCK_GITHUB_TOKEN` constant.
* Security: the GitHub token is no longer sent to the browser; editor search goes through a REST endpoint.
* Improvement: errors are only shown to editors; visitors never see a broken card.
* Improvement: blocks are registered from block.json (API version 3) and built with current WordPress tooling.
* Improvement: removed the bundled Guzzle and GitHub API libraries, avoiding conflicts with other plugins.
* Fix: dates follow the site's date format and timezone.
* Fix: links point to GitHub profile pages instead of API URLs.
* Requires WordPress 6.6 and PHP 7.4 or later.

= 1.1.0 =
* Convert static blocks to dynamic blocks.
* Coding standard updates.

= 1.0.0 =
* Release plugin with two Github info blocks.

== Upgrade Notice ==

= 2.0.0 =
New repository block, repositories, languages and contribution graph on cards, per-section toggles, redesigned cards, search and caching; the GitHub token is no longer exposed in the editor. Requires WordPress 6.6+ and PHP 7.4+. Existing blocks keep working.
