docs: show the GitHub Action and a safe preview first, with links that work on npm

README.md

@@ -1,20 +1,20 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/GeiserX/ghost-github-portfolio/main/docs/images/banner.svg" alt="Ghost GitHub Portfolio banner" width="900"/>
+  <img src="https://raw.githubusercontent.com/GeiserX/ghost-github-portfolio/main/docs/images/banner.svg" alt="Ghost GitHub Portfolio" width="900"/>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/ghost-github-portfolio"><img src="https://img.shields.io/npm/v/ghost-github-portfolio?style=flat-square&logo=npm" alt="npm"></a>
-  <a href="https://hub.docker.com/r/drumsergio/ghost-github-portfolio"><img src="https://img.shields.io/docker/pulls/drumsergio/ghost-github-portfolio?style=flat-square&logo=docker" alt="Docker Pulls"></a>
   <a href="https://github.com/GeiserX/ghost-github-portfolio/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/GeiserX/ghost-github-portfolio/ci.yml?style=flat-square&logo=github&label=CI" alt="CI"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/GeiserX/ghost-github-portfolio?style=flat-square" alt="License"></a>
+  <a href="https://github.com/GeiserX/ghost-github-portfolio/blob/main/LICENSE"><img src="https://img.shields.io/github/license/GeiserX/ghost-github-portfolio?style=flat-square" alt="License"></a>
+  <a href="https://hub.docker.com/r/drumsergio/ghost-github-portfolio"><img src="https://img.shields.io/docker/pulls/drumsergio/ghost-github-portfolio?style=flat-square&logo=docker" alt="Docker Pulls"></a>
   <a href="https://codecov.io/gh/GeiserX/ghost-github-portfolio"><img src="https://codecov.io/gh/GeiserX/ghost-github-portfolio/graph/badge.svg" alt="codecov"></a>
 </p>
 
 <p align="center"><strong>Keep a Ghost portfolio page in step with your GitHub repositories.</strong></p>
 
-`ghost-github-portfolio` reads your public GitHub repositories, keeps the most starred ones, and writes them to a Ghost page as a grid of cards through the Ghost Admin API. Run it on a schedule and the page follows your star counts.
+`ghost-github-portfolio` reads your public GitHub repositories, keeps the most starred ones, and writes them to a Ghost page as a grid of cards through the Ghost Admin API. Run it as a CLI, in Docker, or as a GitHub Action on a schedule, and the page follows your star counts.
 
-<p align="center"><img src="https://raw.githubusercontent.com/GeiserX/ghost-github-portfolio/main/docs/preview-desktop.png" alt="Portfolio page preview" width="900"/></p>
+<p align="center"><img src="https://raw.githubusercontent.com/GeiserX/ghost-github-portfolio/main/docs/images/screenshots/preview-desktop.png" alt="Portfolio page preview" width="900"/></p>
 
 ## Features
 
@@ -32,19 +32,20 @@
 ```bash
 npm install -g ghost-github-portfolio
 ghost-github-portfolio init
-GHOST_ADMIN_API_KEY=KEY_ID:SECRET ghost-github-portfolio sync --config config.yml --verbose
+ghost-github-portfolio sync --config config.yml --html-out preview.html
 ```
 
-Get the Admin API key in Ghost under Settings, Integrations, "Add custom integration". [Usage](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/usage.md) shows how to preview before writing.
+Open `preview.html` in a browser; Ghost is not touched. When the preview looks right, drop `--html-out` and set `GHOST_ADMIN_API_KEY` (Ghost, Settings, Integrations, "Add custom integration") to write the page. [Usage](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/usage.md) has the other install paths.
 
 ## Documentation
 
-- [Usage](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/usage.md): install, init, preview and sync
 - [Configuration](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/configuration.md): `config.yml`, filters, environment variables, descriptions, banners, writing through the Ghost origin
-- [Running on a schedule](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/scheduling.md): Docker loop, cron, GitHub Actions
+- [Usage](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/usage.md): install, init, preview and sync
 - [How it works](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/how-it-works.md): the page layout and the sync steps
-- [Roadmap](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/ROADMAP.md)
+- [Running on a schedule](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/scheduling.md): the GitHub Action, cron and a Docker loop
+
+The roadmap is in [docs/ROADMAP.md](https://github.com/GeiserX/ghost-github-portfolio/blob/main/docs/ROADMAP.md).
 
 ## License
 
-[GPL-3.0](LICENSE)
+[GPL-3.0-or-later](https://github.com/GeiserX/ghost-github-portfolio/blob/main/LICENSE)

docs/how-it-works.md

@@ -11,7 +11,7 @@ The page is one Ghost html card with its own scoped style. It holds a short intr
 
 The grid has three columns on desktop, two on tablets and one on phones. On themes built on Ghost's content grid, such as Alto, Source and Casper, the cards take the wide column and the text stays at reading width. The colours suit a dark theme.
 
-[preview-desktop.png](preview-desktop.png) shows a real run at 1280 px wide, and [preview-mobile.png](preview-mobile.png) the same page on a phone. [preview-config.yml](preview-config.yml) is the config behind them.
+[preview-desktop.png](images/screenshots/preview-desktop.png) shows a real run at 1280 px wide, and [preview-mobile.png](images/screenshots/preview-mobile.png) the same page on a phone. [preview-config.yml](preview-config.yml) is the config behind them.
 
 ## The sync steps
 

docs/scheduling.md

@@ -1,5 +1,32 @@
 # Running on a schedule
 
+## As a GitHub Action
+
+The repository is also a GitHub Action. It installs and builds the tool on the runner and runs `sync --config <config-path> --verbose`, with `GHOST_GITHUB_TOKEN` set to the workflow's `github.token`:
+
+```yaml
+name: Update portfolio
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: GeiserX/ghost-github-portfolio@v0.4.0
+        with:
+          config-path: portfolio/config.yml
+          ghost-admin-api-key: ${{ secrets.GHOST_ADMIN_API_KEY }}
+```
+
+`config-path` defaults to `config.yml`. The other inputs, `ghost-url`, `ghost-page-slug`, `github-username` and `min-stars`, are optional and override the matching values in the config. The runner has to reach your Ghost URL: a GitHub-hosted runner cannot reach an `originUrl` on a private network.
+
+## Docker
+
 The Docker image runs one sync and exits. To keep it running, loop inside the container and let Docker restart it after a reboot:
 
 ```bash
@@ -13,13 +40,17 @@ docker run -d --name ghost-portfolio --restart unless-stopped \
 
 `portfolio.env` holds `GHOST_ADMIN_API_KEY=KEY_ID:SECRET` and, if you want it, `GHOST_GITHUB_TOKEN`.
 
+## Cron
+
 Or run it from the host's cron, once a day at 06:00:
 
 ```
 0 6 * * * docker run --rm -v /path/to/config.yml:/config/config.yml:ro --env-file /path/to/portfolio.env drumsergio/ghost-github-portfolio:0.4.0
 ```
 
-A GitHub Actions schedule works too, as long as the runner can reach your Ghost URL. A GitHub-hosted runner cannot reach an `originUrl` on a private network.
+## npx in a workflow
+
+Without the Action, a workflow can run the npm package directly. The same rule about reaching your Ghost URL applies.
 
 ```yaml
 name: Update portfolio

package.json

@@ -34,7 +34,7 @@
     "self-hosted"
   ],
   "author": "GeiserX",
-  "license": "GPL-3.0",
+  "license": "GPL-3.0-or-later",
   "repository": {
     "type": "git",
     "url": "https://github.com/GeiserX/ghost-github-portfolio.git"