ghost-github-portfolio 0.3.4 → 0.4.0

package/README.md

@@ -8,202 +8,200 @@
   <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/stargazers"><img src="https://img.shields.io/github/stars/GeiserX/ghost-github-portfolio?style=flat-square&logo=github" alt="Stars"></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>Auto-sync your GitHub repositories to a Ghost CMS portfolio page.</strong></p>
-
----
+<p align="center"><strong>Keep a Ghost portfolio page in step with your GitHub repositories.</strong></p>
 
 ## What it does
 
-`ghost-github-portfolio` fetches your public GitHub repositories, sorts them by stars, generates beautiful portfolio cards with banners and badges, and pushes the result to a Ghost page via the Admin API.
+`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.
+
+The page is one Ghost html card with its own scoped style. It holds a short intro, then a card per repository, then one line that points at your GitHub profile. Each card has:
 
-Run it daily via cron, GitHub Actions, or Docker to keep your portfolio always up to date.
+- the repository banner, or a tile with the repository name when there is no usable banner
+- the name, linked to GitHub, and the star count as plain text, such as "215 stars"
+- one line on what the repository does
+- a "Site" link when the repository has a homepage outside github.com
 
-**Features:**
+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.
 
-- Fetches repos sorted by stars, filtered by configurable minimum
-- Auto-detects banner images (`docs/images/banner.svg`, `media/banner.svg`, etc.)
-- Dynamic shields.io badges (stars, forks, license, Docker pulls, website, awesome-list)
-- Per-repo overrides (custom description, badges, Docker image, tech stack)
-- Ghost lexical editor format (the current Ghost editor)
-- Dry-run mode for previewing changes
-- Runs as CLI, Docker container, or GitHub Action
+[docs/preview-desktop.png](docs/preview-desktop.png) shows a real run at 1280 px wide, and [docs/preview-mobile.png](docs/preview-mobile.png) the same page on a phone. [docs/preview-config.yml](docs/preview-config.yml) is the config behind them.
 
 ## Quick start
 
-### 1. Install
+Install it, or run it with `npx`:
 
 ```bash
-# npm (global)
 npm install -g ghost-github-portfolio
-
-# npx (no install)
-npx ghost-github-portfolio
-
-# Docker
-docker pull drumsergio/ghost-github-portfolio:0.3.0
 ```
 
-### 2. Create a config
+Write an example config and edit it:
 
 ```bash
 ghost-github-portfolio init
 ```
 
-This generates a `config.yml` with all available options. Edit it with your GitHub username and Ghost API credentials.
-
-### 3. Get your Ghost Admin API key
+Get an Admin API key in Ghost under Settings, Integrations, "Add custom integration". It looks like `KEY_ID:SECRET`.
 
-1. Go to your Ghost Admin panel > **Settings** > **Integrations**
-2. Create a new **Custom Integration**
-3. Copy the **Admin API Key** (format: `KEY_ID:SECRET`)
-
-### 4. Run
+Preview the page, then sync it:
 
 ```bash
-# Preview (no changes to Ghost)
-ghost-github-portfolio sync --config config.yml --dry-run --verbose
+# Builds the page and writes a standalone preview. Ghost is not touched
+ghost-github-portfolio sync --config config.yml --html-out preview.html
 
-# Sync to Ghost
-ghost-github-portfolio sync --config config.yml --verbose
+# Writes the page to Ghost
+GHOST_ADMIN_API_KEY=KEY_ID:SECRET ghost-github-portfolio sync --config config.yml --verbose
 ```
 
+`--dry-run` builds the page and lists each card without writing anything. `--json` prints the Ghost document instead. Both write the html card to `/tmp/ghost-portfolio-preview.html`. `--html-out <file>` also wraps it in a dark page that approximates Ghost's Alto theme, so you can open it in a browser.
+
 ## Configuration
 
 ```yaml
 github:
   username: YOUR_GITHUB_USERNAME
-  # token: ghp_xxx  # Optional: higher rate limits (env: GHOST_GITHUB_TOKEN)
+  # token: ghp_xxx          # Optional, for higher rate limits (env: GHOST_GITHUB_TOKEN)
+  excludePatterns:          # Regular expressions matched against repo names
+    - "^homebrew-"
 
 ghost:
   url: https://your-ghost-blog.com
-  adminApiKey: "KEY_ID:SECRET_HEX"
-  pageSlug: portfolio   # or pageId: "hex_id"
+  adminApiKey: "KEY_ID:SECRET_HEX"  # env GHOST_ADMIN_API_KEY wins over this
+  pageSlug: portfolio               # Or pageId with the page's hex ID
+  # originUrl: http://ghost:2368    # See "Writing through the Ghost origin"
+  # hostHeader: your-ghost-blog.com
 
 portfolio:
-  minStars: 2
-  maxRepos: 50
+  minStars: 2               # Only repos with at least this many stars
+  maxRepos: 20              # How many cards, counted after every filter
+  columns: 3                # Cards per row on desktop, from 1 to 6
   includeForked: false
-  badgeStyle: for-the-badge  # flat, flat-square, for-the-badge, plastic, social
+  includeArchived: false
+  excludeAwesomeLists: true # Skip repos named "awesome*" or tagged "awesome-list"
   showBanner: true
-  centerContent: true
   defaultBannerPath: docs/images/banner.svg
+  intro: "I build things nobody asked for, one repo at a time. These are the ones that got the most stars on GitHub, with a line on what each one does."
 
-  bannerPaths:
-    awesome-spain: media/banner.svg  # Override per repo
+  bannerPaths:              # Banner path per repo, tried before defaultBannerPath
+    my-project: media/banner.svg
 
   excludeRepos:
     - .github
 
-  repos:
+  repos:                    # Per-repo overrides
     my-project:
-      description: "Custom description"
-      dockerImage: myuser/my-project  # Adds Docker pulls badge
-      techStack: "Python, Docker, Redis"
-      badges:
-        - type: website
-          url: https://my-project.com
-        - type: awesome-list
-        - type: platform
-          label: macOS
-          logo: apple
-        - type: docs
-          url: https://docs.my-project.com
-        - type: custom
-          label: MCP
-          value: Official Registry
-          color: E6522C
-
-  footer:
-    showStats: true
-    showViewAll: true
+      description: "One line that replaces the GitHub description"
+      homepage: https://example.com/guide/  # Replaces the GitHub homepage field
+      siteLabel: Guide                      # Link text, "Site" by default
+      bannerPath: assets/banner.png
+      exclude: false
 ```
 
-### Environment variables
+Filters run in this order: minimum stars, forks, archived, `excludeRepos`, per-repo `exclude`, `excludePatterns`, awesome lists. The tool sorts what is left by stars and only then cuts it to `maxRepos`, so an excluded repository never takes a slot.
 
-| Variable | Description |
-|----------|-------------|
-| `GHOST_GITHUB_TOKEN` | GitHub token for private repos / higher rate limits |
-| `GHOST_ADMIN_API_KEY` | Ghost Admin API key (overrides config file) |
+A repository can also carry its own `.ghost-portfolio.yml` at the root of its default branch with `description`, `homepage`, `siteLabel` and `bannerPath`. Values in your `config.yml` win over it.
 
-## Docker
+| Variable | Meaning |
+|---|---|
+| `GHOST_ADMIN_API_KEY` | Ghost Admin API key. Overrides `ghost.adminApiKey`, which can then be left out. |
+| `GHOST_GITHUB_TOKEN` | GitHub token for higher rate limits. Used when `github.token` is not set. The generic `GITHUB_TOKEN` is ignored on purpose. |
 
-```bash
-docker run --rm \
-  -v /path/to/config.yml:/config/config.yml \
-  drumsergio/ghost-github-portfolio:0.3.0
+## Descriptions and site links
+
+A `description` in `config.yml` is used exactly as written, so that is the place for one-liners you want to keep by hand. Otherwise the tool takes the GitHub description, or the one in `.ghost-portfolio.yml`, and cleans it up:
+
+- it keeps the first sentence only
+- em and en dashes become commas
+- emoji and `:shortcodes:` are removed
+- it is cut to 140 characters at a word boundary
+
+The site link comes from `homepage` in the overrides, else from the repository's homepage field. A homepage on github.com is skipped, since the name already links there.
+
+## Banners
+
+For each repository the tool fetches the per-repo banner path if you set one, then `defaultBannerPath`, from `raw.githubusercontent.com` on the default branch. It uses the first one that passes both checks:
+
+1. It answers HTTP 200.
+2. If it is an SVG, it is self-contained. Every `href`, `xlink:href`, `url(...)` and `@import` must point at a `#id` inside the file or at a `data:` URI. Browsers never load other files referenced by an SVG that is shown through `<img>`, so a banner that pulls in `logo.png` or a web font comes out blank or broken on the page.
+
+When no path passes, the card gets a tile with the repository name, and the run prints a warning that names the reason so you can fix the source:
+
+```
+Warning: my-project gets a name tile: docs/images/banner.svg: not self-contained, it loads logo.png
+Warning: other-project gets a name tile: docs/images/banner.svg: missing (HTTP 404)
 ```
 
-### Docker Compose (daily cron)
+To make an SVG self-contained, inline the images it references as base64 `data:` URIs, or redraw them as SVG shapes. The card shows the banner in a 9:2 box and crops it around the centre, so a 900x200 banner fits exactly.
+
+## Writing through the Ghost origin
+
+Some setups put a web application firewall in front of the public Ghost URL that rejects request bodies containing `<img`, which every portfolio update does. Set `ghost.originUrl` to reach Ghost directly instead, for example on the local network:
 
 ```yaml
-services:
-  ghost-portfolio:
-    image: drumsergio/ghost-github-portfolio:0.3.0
-    volumes:
-      - ./config.yml:/config/config.yml:ro
-    # Run daily at 6 AM via external cron or restart policy
+ghost:
+  url: https://your-ghost-blog.com
+  originUrl: http://ghost-host:2368
+  hostHeader: your-ghost-blog.com   # Defaults to the host of url
+```
+
+Admin API requests then go to `originUrl` with `Host: <hostHeader>` and `X-Forwarded-Proto: https`, so Ghost answers as it does for the public site. The token audience stays `/admin/`. The tool does not follow redirects, because a redirect would lead back through the public URL. Without `originUrl` the requests go to `url` as before.
+
+## Running on a schedule
+
+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
+docker run -d --name ghost-portfolio --restart unless-stopped \
+  -v /path/to/config.yml:/config/config.yml:ro \
+  --env-file /path/to/portfolio.env \
+  --entrypoint sh \
+  drumsergio/ghost-github-portfolio:0.4.0 \
+  -c 'while true; do node dist/index.js sync --config /config/config.yml; sleep 86400; done'
 ```
 
-## GitHub Action
+`portfolio.env` holds `GHOST_ADMIN_API_KEY=KEY_ID:SECRET` and, if you want it, `GHOST_GITHUB_TOKEN`.
+
+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
+```
 
-Create `.github/workflows/portfolio.yml` in any repo:
+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.
 
 ```yaml
-name: Update Portfolio
+name: Update portfolio
 
 on:
   schedule:
-    - cron: "0 6 * * *"  # Daily at 6 AM UTC
-  workflow_dispatch:       # Manual trigger
+    - cron: "0 6 * * *"
+  workflow_dispatch:
 
 jobs:
   sync:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-
-      - run: npx ghost-github-portfolio sync --config config.yml --verbose
+      - run: npx ghost-github-portfolio@0.4.0 sync --config config.yml --verbose
         env:
-          GHOST_GITHUB_TOKEN: ${{ secrets.GHOST_GITHUB_TOKEN }}
+          GHOST_ADMIN_API_KEY: ${{ secrets.GHOST_ADMIN_API_KEY }}
+          GHOST_GITHUB_TOKEN: ${{ github.token }}
 ```
 
-Store `config.yml` in the repo (without secrets) and use environment variables for the API keys.
+Keep `config.yml` in the repository without the key, and store the key as a secret.
 
 ## How it works
 
-1. **Fetches** all public repos for the configured GitHub user via the REST API
-2. **Filters** by minimum stars, excludes forks and blocklisted repos
-3. **Sorts** by star count (descending)
-4. **Detects** banner images by checking common paths (`docs/images/banner.svg`, `media/banner.svg`, etc.)
-5. **Generates** HTML cards with: banner, name, dynamic badges, description, tech stack
-6. **Composes** a Ghost lexical JSON document (the format Ghost's editor uses internally)
-7. **Updates** the target Ghost page via the Admin API with JWT authentication
-
-Badges are dynamic (served by shields.io) — stars, forks, and Docker pulls update automatically on every page view without re-running the tool.
-
-## Badge types
-
-| Type | Auto-detected | Description |
-|------|--------------|-------------|
-| Stars | Yes | Always shown |
-| Forks | Yes | Always shown |
-| License | Yes | From GitHub repo metadata |
-| Docker pulls | Config | Set `dockerImage` in repo overrides |
-| Website | Yes | From GitHub homepage field |
-| Awesome list | Yes | If repo has `awesome-list` topic |
-| Docs | Yes | If homepage is a GitHub Pages URL |
-| Platform | Config | Custom platform badge (macOS, Linux, etc.) |
-| Custom | Config | Any shields.io-compatible badge |
-
-## Roadmap
-
-See [docs/ROADMAP.md](docs/ROADMAP.md) for the full roadmap — themes, multi-CMS support, AI features, analytics, team portfolios, and more.
+1. Fetches every public repository the user owns from the GitHub REST API. The API cannot sort by stars, so it reads all pages and sorts locally.
+2. Applies the filters, sorts by stars and keeps `maxRepos`.
+3. Reads each repository's `.ghost-portfolio.yml`, if any.
+4. Checks each banner as described above.
+5. Builds one html card and wraps it in the Ghost lexical document format.
+6. Fetches the page to get its `updated_at`, then writes the new content through the Admin API with a short-lived JWT.
 
 ## License
 

package/dist/config.d.ts

@@ -1,4 +1,6 @@
 import type { Config } from "./types.js";
+export declare const DEFAULT_INTRO = "I build things nobody asked for, one repo at a time. These are the ones that got the most stars on GitHub, with a line on what each one does.";
+export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
 export declare function loadConfig(path: string): Config;
 export declare function generateExampleConfig(): string;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,YAAY,CAAC;AAiB1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkD/C;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAuD9C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,aAAa,kJACuH,CAAC;AAElJ,eAAO,MAAM,wBAAwB,UAAiB,CAAC;AAqBvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8E/C;AAgBD,wBAAgB,qBAAqB,IAAI,MAAM,CA2C9C"}

package/dist/config.js

@@ -1,118 +1,146 @@
 import { readFileSync } from "node:fs";
 import { parse } from "yaml";
+export const DEFAULT_INTRO = "I build things nobody asked for, one repo at a time. These are the ones that got the most stars on GitHub, with a line on what each one does.";
+export const DEFAULT_EXCLUDE_PATTERNS = ["^homebrew-"];
 const DEFAULT_PORTFOLIO = {
     minStars: 2,
-    maxRepos: 50,
+    maxRepos: 20,
+    columns: 3,
     excludeRepos: [],
     includeForked: false,
-    excludeAwesomeLists: false,
-    badgeStyle: "for-the-badge",
+    includeArchived: false,
+    excludeAwesomeLists: true,
     showBanner: true,
-    centerContent: true,
     defaultBannerPath: "docs/images/banner.svg",
     bannerPaths: {},
+    intro: DEFAULT_INTRO,
     repos: {},
-    footer: { showStats: true, showViewAll: true },
 };
+function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}
 export function loadConfig(path) {
     const raw = readFileSync(path, "utf-8");
-    const parsed = parse(raw);
-    if (!parsed.github || !parsed.github.username) {
+    const parsed = (parse(raw) ?? {});
+    const github = (parsed.github ?? {});
+    const ghost = (parsed.ghost ?? {});
+    if (!github.username) {
         throw new Error("Config: github.username is required");
     }
-    if (!parsed.ghost || !parsed.ghost.url) {
+    if (!ghost.url) {
         throw new Error("Config: ghost.url is required");
     }
-    if (!parsed.ghost.adminApiKey) {
-        throw new Error("Config: ghost.adminApiKey is required");
+    // The environment wins over the config file, so the key can stay out of it.
+    const ghostKey = process.env.GHOST_ADMIN_API_KEY || ghost.adminApiKey;
+    if (!ghostKey) {
+        throw new Error("Config: ghost.adminApiKey is required (or set GHOST_ADMIN_API_KEY)");
     }
-    const ghost = parsed.ghost;
     if (!ghost.pageId && !ghost.pageSlug) {
         throw new Error("Config: ghost.pageId or ghost.pageSlug is required");
     }
-    const github = parsed.github;
-    const portfolio = (parsed.portfolio ?? {});
-    // Env var overrides (GHOST_GITHUB_TOKEN only — GITHUB_TOKEN is not used to
-    // avoid picking up unrelated tokens from gh CLI or CI environments)
+    // GHOST_GITHUB_TOKEN only. GITHUB_TOKEN is not used, to avoid picking up
+    // unrelated tokens from the gh CLI or CI environments.
     const ghToken = github.token ?? process.env.GHOST_GITHUB_TOKEN;
-    const ghostKey = ghost.adminApiKey ?? process.env.GHOST_ADMIN_API_KEY;
+    const excludePatterns = (github.excludePatterns ??
+        DEFAULT_EXCLUDE_PATTERNS);
+    if (!Array.isArray(excludePatterns)) {
+        throw new Error("Config: github.excludePatterns must be a list");
+    }
+    for (const pattern of excludePatterns) {
+        try {
+            new RegExp(String(pattern), "i");
+        }
+        catch {
+            throw new Error(`Config: github.excludePatterns has an invalid pattern: ${pattern}`);
+        }
+    }
+    const portfolio = (parsed.portfolio ?? {});
+    const merged = {
+        ...DEFAULT_PORTFOLIO,
+        ...portfolio,
+        bannerPaths: { ...portfolio.bannerPaths },
+        repos: { ...portfolio.repos },
+        excludeRepos: portfolio.excludeRepos ?? [],
+    };
+    if (!Number.isInteger(merged.columns) || merged.columns < 1 || merged.columns > 6) {
+        throw new Error("Config: portfolio.columns must be a whole number from 1 to 6");
+    }
+    if (!Number.isInteger(merged.maxRepos) || merged.maxRepos < 1) {
+        throw new Error("Config: portfolio.maxRepos must be a whole number above 0");
+    }
     return {
         github: {
             username: github.username,
             token: ghToken,
+            excludePatterns: excludePatterns.map(String),
         },
         ghost: {
-            url: ghost.url.replace(/\/$/, ""),
+            url: trimSlash(ghost.url),
             adminApiKey: ghostKey,
             pageId: ghost.pageId,
             pageSlug: ghost.pageSlug,
+            originUrl: ghost.originUrl ? validateOriginUrl(ghost.originUrl) : undefined,
+            hostHeader: ghost.hostHeader,
         },
-        portfolio: {
-            ...DEFAULT_PORTFOLIO,
-            ...portfolio,
-            footer: { ...DEFAULT_PORTFOLIO.footer, ...portfolio.footer },
-            bannerPaths: {
-                ...DEFAULT_PORTFOLIO.bannerPaths,
-                ...portfolio.bannerPaths,
-            },
-            repos: { ...DEFAULT_PORTFOLIO.repos, ...portfolio.repos },
-        },
+        portfolio: merged,
     };
 }
+/** The origin route carries the Admin key in a JWT, so the scheme must be plain http: or https:. */
+function validateOriginUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("Config: ghost.originUrl must be a full URL such as http://ghost:2368");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Config: ghost.originUrl must start with http:// or https://");
+    }
+    return trimSlash(value);
+}
 export function generateExampleConfig() {
     return `# ghost-github-portfolio configuration
 github:
   username: YOUR_GITHUB_USERNAME
-  # token: ghp_xxx  # Optional: for private repos or higher rate limits (env: GHOST_GITHUB_TOKEN)
+  # token: ghp_xxx          # Optional, for higher rate limits (env: GHOST_GITHUB_TOKEN)
+  excludePatterns:          # Regular expressions matched against repo names
+    - "^homebrew-"
 
 ghost:
   url: https://your-ghost-blog.com
-  adminApiKey: "KEY_ID:SECRET_HEX"  # From Ghost Admin > Integrations (env: GHOST_ADMIN_API_KEY)
-  pageSlug: portfolio               # Update this page (or use pageId for the hex ID)
+  adminApiKey: "KEY_ID:SECRET_HEX"  # Ghost Admin > Integrations (env GHOST_ADMIN_API_KEY wins)
+  pageSlug: portfolio               # Or pageId with the page's hex ID
+  # originUrl: http://ghost:2368    # Send Admin API requests straight to the Ghost origin
+  # hostHeader: your-ghost-blog.com # Host header for originUrl (defaults to the host of url)
 
 portfolio:
-  minStars: 2          # Only show repos with at least this many stars
-  maxRepos: 50         # Maximum number of repos to display
-  includeForked: false # Skip forked repos
-  excludeAwesomeLists: false # Skip repos starting with "awesome" or tagged "awesome-list"
-  badgeStyle: for-the-badge  # shields.io style: flat, flat-square, for-the-badge, plastic, social
-  showBanner: true     # Show repo banner images (SVG/PNG from the repo)
-  centerContent: true  # Center project names and badges
+  minStars: 2               # Only repos with at least this many stars
+  maxRepos: 20              # How many cards to show, counted after every filter
+  columns: 3                # Cards per row on desktop (two on tablets, one on phones)
+  includeForked: false
+  includeArchived: false
+  excludeAwesomeLists: true # Skip repos named "awesome*" or tagged "awesome-list"
+  showBanner: true          # Use the repo banner when it passes the checks, else a name tile
+  defaultBannerPath: docs/images/banner.svg
 
-  defaultBannerPath: docs/images/banner.svg  # Default location to look for banners
+  intro: "${DEFAULT_INTRO}"
 
-  # Override banner path for specific repos
-  bannerPaths:
-    # awesome-spain: media/banner.svg
+  # Banner path for specific repos, tried before defaultBannerPath
+  bannerPaths: {}
+    # my-project: media/banner.svg
 
   excludeRepos:
-    - .github          # Profile config repo
-    # - my-private-project
+    - .github
 
   # Per-repo overrides
   repos: {}
     # my-project:
-    #   description: "Custom description (overrides GitHub)"
-    #   dockerImage: drumsergio/my-project  # Adds Docker pulls badge
-    #   techStack: "Python, Docker, Redis"
+    #   description: "One line that replaces the GitHub description"
+    #   homepage: https://example.com/guide/  # Replaces the GitHub homepage field
+    #   siteLabel: Guide                      # Link text, defaults to "Site"
     #   bannerPath: assets/banner.png
-    #   badges:
-    #     - type: website
-    #       url: https://my-project.com
-    #     - type: awesome-list
-    #     - type: platform
-    #       label: macOS
-    #       logo: apple
-    #     - type: docs
-    #       url: https://docs.my-project.com
-    #     - type: custom
-    #       label: MCP
-    #       value: Official Registry
-    #       color: E6522C
-
-  footer:
-    showStats: true    # Show total stars and repo count
-    showViewAll: true  # Show "View All Repositories" link
+    #   exclude: false
 `;
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAG7B,MAAM,iBAAiB,GAAoB;IACzC,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,EAAE;IACZ,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,KAAK;IACpB,mBAAmB,EAAE,KAAK;IAC1B,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE,IAAI;IAChB,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE,wBAAwB;IAC3C,WAAW,EAAE,EAAE;IACf,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;CAC/C,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAA4B,CAAC;IAErD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAE,MAAM,CAAC,MAAkC,CAAC,QAAQ,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAE,MAAM,CAAC,KAAiC,CAAC,GAAG,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,CAAE,MAAM,CAAC,KAAiC,CAAC,WAAW,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAgC,CAAC;IACtD,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgC,CAAC;IACvD,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAA6B,CAAC;IAEvE,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC/D,MAAM,QAAQ,GACX,KAAK,CAAC,WAAsB,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAEnE,OAAO;QACL,MAAM,EAAE;YACN,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,OAAO;SACf;QACD,KAAK,EAAE;YACL,GAAG,EAAG,KAAK,CAAC,GAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YAC7C,WAAW,EAAE,QAAQ;YACrB,MAAM,EAAE,KAAK,CAAC,MAA4B;YAC1C,QAAQ,EAAE,KAAK,CAAC,QAA8B;SAC/C;QACD,SAAS,EAAE;YACT,GAAG,iBAAiB;YACpB,GAAG,SAAS;YACZ,MAAM,EAAE,EAAE,GAAG,iBAAiB,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE;YAC5D,WAAW,EAAE;gBACX,GAAG,iBAAiB,CAAC,WAAW;gBAChC,GAAG,SAAS,CAAC,WAAW;aACzB;YACD,KAAK,EAAE,EAAE,GAAG,iBAAiB,CAAC,KAAK,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE;SAC1D;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDR,CAAC;AACF,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/generator.d.ts

@@ -1,5 +1,39 @@
 import type { Config, GitHubRepo, LexicalDocument } from "./types.js";
+export declare const MAX_DESCRIPTION_LENGTH = 140;
+/**
+ * Turn a GitHub description into one short line: emoji and :shortcodes:
+ * removed, em and en dashes turned into commas, first sentence only,
+ * at most 140 characters.
+ */
+export declare function cleanDescription(text: string, max?: number): string;
+export declare function formatStars(count: number): string;
+export interface SiteLink {
+    url: string;
+    label: string;
+}
+/** The card's site link: the override, else the GitHub homepage unless it points at github.com. */
+export declare function siteLink(repo: GitHubRepo, config: Config): SiteLink | null;
+export declare function repoDescription(repo: GitHubRepo, config: Config): string;
 export declare function generateCard(repo: GitHubRepo, bannerUrl: string | null, config: Config): string;
-export declare function generateFooter(allRepos: GitHubRepo[], config: Config): string | null;
-export declare function buildLexical(cards: string[], footer: string | null): LexicalDocument;
+export interface PortfolioInput {
+    /** Card HTML from generateCard, in display order. */
+    cards: string[];
+    /** Number of public repositories the user owns, used for the closing line. */
+    totalRepos: number;
+}
+/**
+ * The whole page as the HTML of one Ghost html card. The `kg-width-wide`
+ * class lets themes built on Ghost's content grid (Alto, Source, Casper)
+ * give the cards the wide column; the text stays at reading width.
+ */
+export declare function generatePortfolioHtml(input: PortfolioInput, config: Config): string;
+export declare function buildLexical(html: string): LexicalDocument;
+/** The html card as Ghost renders it, with its begin and end markers. */
+export declare function wrapHtmlCard(html: string): string;
+/**
+ * A standalone dark page that approximates Ghost's Alto theme in dark mode
+ * (content grid, widths, the .gh-content rules that reach into an html
+ * card), for checking the output in a browser before syncing.
+ */
+export declare function buildPreviewPage(html: string, title?: string): string;
 //# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,eAAe,EAEhB,MAAM,YAAY,CAAC;AAyGpB,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,GACb,MAAM,CA+DR;AAuCD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,UAAU,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAsCf;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,eAAe,CA0BjB"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAK1C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,SAAyB,GAC3B,MAAM,CA4BR;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mGAAmG;AACnG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAgB1E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,GACb,MAAM,CA0BR;AAsCD,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAiBR;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAW1D;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAc,GAAG,MAAM,CAwC1E"}