=== PlanetFOSS ===
Contributors: chrissss
Tags: linux, open source, news, widget, block
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.2.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

What the Linux and open source news are talking about, counted by PlanetFOSS: a topic card below your posts and a news list for your sidebar.

== Description ==

[PlanetFOSS](https://planetfoss.net/) reads close to 200 Linux and open source sources in German and English, sorts every report into topics and counts them. This plugin brings those numbers to your blog.

**Topic card below posts.** A post tagged "KDE Plasma" gets the PlanetFOSS topic KDE Plasma: a short intro, how many reports from how many sources appeared in the last 30 days, a small daily chart, the biggest version topics and a link to all reports.

**Linux news for the sidebar.** The topics with the most reports in the last 24 hours and in the last 7 days, each with a seven-day sparkline – plus links to the weekly review and the logbook.

= Fits your theme =

* Font, text colour and link colour come from your theme. Lines and muted text are mixed from the text colour, so light and dark themes work without settings.
* Sizes in em: the card follows the font size of the place it sits in.
* Every rule uses a single class. Bare theme rules for `h2` or `ul` do not break it, and any rule of yours that names a class wins.
* Custom properties for quick changes: `--planetfoss-accent`, `--planetfoss-line`, `--planetfoss-muted`, `--planetfoss-surface`, `--planetfoss-border`, `--planetfoss-radius`, `--planetfoss-pad`, `--planetfoss-link`, `--planetfoss-mono`.
* Block style "Plain" (no box), plus the usual block settings for colour, typography, border and spacing.
* Turn the stylesheet off completely and style the BEM classes (`planetfoss__…`) yourself.

= Works without setup =

* Topics are matched automatically: a tag or category whose slug or name equals a PlanetFOSS topic. If your blog is itself a PlanetFOSS source, PlanetFOSS's own sorting of your posts is used first.
* Pick a topic by hand in the block settings when the automatic match is not what you want.
* Blocks for the block editor and block themes, a classic widget, shortcodes, and an optional card below every post.

= Honest links, no tracking of readers =

* The plugin shows only what PlanetFOSS itself produces: topic names, intros, counts. Never headlines of other sites.
* Every link goes to planetfoss.net and says so.
* Your server fetches the data every 30 minutes and stores it. Your readers load nothing from planetfoss.net – no scripts, no fonts, no images, no cookies.
* Everything is rendered on the server. No JavaScript on your pages.
* Links to PlanetFOSS carry campaign tags (`utm_source` = your site's host name, `utm_medium=verbund`, `utm_campaign=topic` or `news`). They name your site, never your reader. PlanetFOSS counts them as daily totals to show how many readers each site sends; it keeps site names for 90 days. Turn the tags off with the filter `planetfoss_link_tags`.

= Licence of the data =

The PlanetFOSS data (topic names, intros, counts) are licensed under CC BY 4.0. The plugin credits PlanetFOSS, links to it and shows the licence in a small note in every box, so you are covered. Details: https://planetfoss.net/wordpress/#terms

= Languages =

PlanetFOSS exists in German and English. The data follows the language of your site (or the setting). The plugin interface is translatable.

== External services ==

This plugin connects to the PlanetFOSS API at planetfoss.net to get the topic data it displays. Without this service the plugin shows nothing.

* **What is sent and when:** every 30 minutes (WP-Cron), and when you press "Fetch now", your server requests `https://planetfoss.net/api/verbund/v1/themen.json`. The request contains the language (`de` or `en`), the host name of your site (`site=`, so PlanetFOSS can return the topics of your own posts if your blog is one of its sources), the address of your site in the User-Agent header and, only if you entered one, your access key.
* **Limits:** without a key PlanetFOSS allows a few requests per hour per server; the plugin needs two. On any error the last good data stays in place.
* **When readers click a link:** the link carries the host name of your site as `utm_source` (see above), nothing else.
* **What is not sent:** nothing about your visitors. Your visitors never connect to planetfoss.net through this plugin; they only follow links if they click them.
* PlanetFOSS terms of use for the data: https://planetfoss.net/wordpress/#terms
* PlanetFOSS privacy policy: https://planetfoss.net/datenschutz/

== Installation ==

1. Install and activate the plugin.
2. Go to Settings → PlanetFOSS and check that the first fetch worked.
3. Add the block "PlanetFOSS Linux news" to your sidebar (Appearance → Editor or Widgets), or use the classic widget of the same name.
4. For the topic card: add the block "PlanetFOSS topic" below the post content in your single post template, or turn on "Card below posts" in the settings.

Shortcodes for classic themes and page builders:

* `[planetfoss_topic]` – card for the current post; `[planetfoss_topic topic="gnome"]` for a fixed topic.
* `[planetfoss_news layout="list" limit="6" title="Linux news"]` – `layout="columns"` for wide areas; `style="plain"` removes the box on both.

== Frequently Asked Questions ==

= Why does a post show no card? =

None of its tags or categories matches a PlanetFOSS topic with reports in the last 30 days. Pick a topic in the block settings, or use the filter `planetfoss_post_topics`.

= Can I change the HTML? =

Use the filters `planetfoss_topic_html` and `planetfoss_news_html`. Other filters: `planetfoss_link_tags`, `planetfoss_post_topics`, `planetfoss_auto_post_types`, `planetfoss_load_styles`, `planetfoss_endpoint`, `planetfoss_site_host`.

= Does it slow down my site? =

No. The data is fetched in the background and kept in one database option that is not autoloaded. Rendering needs no request to another server.

= Does it work with page caching? =

Yes. The numbers are at most 30 minutes old plus the lifetime of your page cache. The news list shows when the data was counted.

= Who runs PlanetFOSS? =

PlanetFOSS is an independent Linux and open source news aggregator from Germany. See https://planetfoss.net/ueber/.

== Screenshots ==

1. Topic card below a post and the Linux news list in the sidebar (Twenty Twenty-Five).
2. A quieter topic: reports per six days instead of a daily chart.
3. The news list in two columns on a wide area.
4. Settings → PlanetFOSS.

== Changelog ==

= 0.2.2 =
* German translation complete: settings page help texts, admin notice and block descriptions.

= 0.2.1 =
* Plugin header name shortened to "PlanetFOSS" (slug and text domain `planetfoss`); no functional changes.

= 0.2.0 =
* Links to PlanetFOSS carry campaign tags naming your site (not your readers), so PlanetFOSS can show how many readers each site sends. Filter `planetfoss_link_tags` turns them off.
* Narrow sidebars: sparkline and count move below the topic name.
* Licence note CC BY 4.0 in every box.

= 0.1.0 =
* First version: topic card and Linux news as blocks, classic widget and shortcodes; automatic topic matching; server-side rendering; theme-friendly stylesheet.
