diff --git a/README.md b/README.md index 1b1b5a1..7404e17 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,20 @@

- Ghost GitHub Portfolio banner + Ghost GitHub Portfolio

npm - Docker Pulls CI - License + License + Docker Pulls codecov

Keep a Ghost portfolio page in step with your GitHub repositories.

-`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. -

Portfolio page preview

+

Portfolio page preview

## 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) diff --git a/docs/how-it-works.md b/docs/how-it-works.md index ca7d4a6..89bc3b3 100644 --- a/docs/how-it-works.md +++ b/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 diff --git a/docs/preview-desktop.png b/docs/images/screenshots/preview-desktop.png similarity index 100% rename from docs/preview-desktop.png rename to docs/images/screenshots/preview-desktop.png diff --git a/docs/preview-mobile.png b/docs/images/screenshots/preview-mobile.png similarity index 100% rename from docs/preview-mobile.png rename to docs/images/screenshots/preview-mobile.png diff --git a/docs/scheduling.md b/docs/scheduling.md index 294908a..d155d55 100644 --- a/docs/scheduling.md +++ b/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 --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 diff --git a/package-lock.json b/package-lock.json index 8931aa8..ce6dfb7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7,7 +7,7 @@ "": { "name": "ghost-github-portfolio", "version": "0.4.0", - "license": "GPL-3.0", + "license": "GPL-3.0-or-later", "dependencies": { "commander": "^13.1.0", "yaml": "^2.7.1" diff --git a/package.json b/package.json index bb381e9..f1648c2 100644 --- a/package.json +++ b/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"