Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions .github/workflows/repo-banners.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Renders the README banner for every public AsBuiltReport.* repo into assets/repo-banners/,
# and the organisation profile tiles into profile/images/tiles/, then commits any that changed.
# the organisation profile tiles into profile/images/tiles/, and the README section icon pack
# into assets/section-icons/, then commits any that changed.
# On a pull request it renders without committing, and uploads the images for review.
# The generator lives in generator/. Run it by hand after creating a new repo, or wait for the daily run.
name: Repo banners
Expand Down Expand Up @@ -48,6 +49,14 @@ jobs:
npm ci
npx playwright install --with-deps chromium

- name: Test the README changes
working-directory: generator
run: node --test

- name: Render section icons
working-directory: generator
run: node section-icons.mjs

- name: Render banners and tiles
working-directory: generator
env:
Expand All @@ -67,17 +76,18 @@ jobs:
name: repo-banners
path: |
assets/repo-banners
assets/section-icons
profile/images/tiles

- name: Commit changes
if: github.event_name != 'pull_request'
run: |
git add assets/repo-banners profile/images/tiles
git add assets/repo-banners assets/section-icons profile/images/tiles
if git diff --cached --quiet; then
echo "No banner changes"
exit 0
fi
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git commit -m 'Update repo banners and profile tiles'
git commit -m 'Update repo banners, profile tiles and section icons'
git push
31 changes: 24 additions & 7 deletions generator/README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# Repo banner generator
# Brand asset generator

Renders the README banner for every public `AsBuiltReport.*` repo, and the module tiles on the organisation profile, from one HTML template.
Renders the brand images for AsBuiltReport repos: a README banner for every public `AsBuiltReport.*` repo and the module tiles on the organisation profile, from one HTML template, and the section icon pack used on README headings.

| Output | Size | Path |
|---|---|---|
| README banner | 1760 x 480 | `assets/repo-banners/<repo>.png` |
| Profile tile | 840 x 240 | `profile/images/tiles/<repo>.png` |
| README section icon | 32 x 32 SVG, 96 x 96 PNG | `assets/section-icons/<name>.svg`, `.png` |

The [Repo banners](../.github/workflows/repo-banners.yml) workflow runs daily, on pushes to `generator/`, and by hand. It commits only the images that changed. After creating a new repo, run the workflow by hand so its banner exists straight away.

Expand All @@ -15,6 +16,10 @@ The [Repo banners](../.github/workflows/repo-banners.yml) workflow runs daily, o
- Line 3 is `PS> Install-Module <repo>` when the module is on the PowerShell Gallery, and the GitHub URL when it is not, so a banner never shows a command that fails.
- `repos.json` sets the exceptions: repos to skip, repos without a tile, and fixed line 3 text (the website shows `www.asbuiltreport.com`).

## Section icons

Section headings in module READMEs use icons in place of emoji, in the style of the feature icons on [www.asbuiltreport.com](https://www.asbuiltreport.com): an [Octicons](https://primer.style/octicons/) glyph in console blue on a highlighter yellow tile. `section-icons.json` lists each icon, its Octicon and the heading texts it is used for. `section-icons.mjs` renders them, with a catalogue at [`assets/section-icons`](../assets/section-icons). To add an icon, add an entry to `section-icons.json`.

## Using a banner in a README

```html
Expand All @@ -27,13 +32,23 @@ The [Repo banners](../.github/workflows/repo-banners.yml) workflow runs daily, o

New modules get this from the [Plaster template](https://github.com/AsBuiltReport/AsBuiltReport.Plaster.Template).

For existing repos, `readme-banners.mjs` opens a pull request in each one that replaces the old logo at the top of the README with the banner (or adds the banner at the top when there is no logo). It skips repos that already use the banner or already have the pull request open. It is a dry run unless you pass `--apply`:
## Applying the brand to existing READMEs

`readme-prs.mjs` opens a pull request in each repo that applies the brand to its README, using the functions in `readme-brand.mjs`:

- the banner in place of the old logo at the top (or at the top when there is no logo)
- section icons in place of the emoji on known section headings, sized to the heading level (headings inside code blocks are left alone)
- badges in the brand palette: link blue `#1F5FD0` for versions, console blue `#012456` for counts (downloads, contributors), highlighter `#FFD02B` for compatibility (platform)

Where the pull request is already open, it commits to that branch instead. It skips READMEs that already have every change. It is a dry run unless you pass `--apply`:

```sh
GITHUB_TOKEN=$(gh auth token) node readme-banners.mjs --out ./preview # dry run, writes the new READMEs to ./preview
GITHUB_TOKEN=$(gh auth token) node readme-banners.mjs --apply # opens the pull requests
GITHUB_TOKEN=$(gh auth token) node readme-prs.mjs --out ./preview # dry run, writes the new READMEs to ./preview
GITHUB_TOKEN=$(gh auth token) node readme-prs.mjs --apply # opens or updates the pull requests
```

`readme-brand.test.mjs` tests these changes (`node --test`). Set `README_DIR` to a folder of downloaded READMEs to also check that nothing else in them changes.

## Running it locally

Needs Node.js 22 or later.
Expand All @@ -44,10 +59,12 @@ npm ci
npx playwright install chromium
node render.mjs # every repo
node render.mjs --repo AsBuiltReport.Microsoft.Azure # one repo
node section-icons.mjs # the section icon pack
node --test # tests
```

To preview a layout change, open `template.html` in a browser with a query string, for example `template.html?kind=banner&name=Microsoft.Azure`. Local renders on Windows or macOS differ slightly from the Linux runner, so let the workflow produce the committed images.

## Fonts
## Fonts and icons

Archivo and Cascadia Code are copied from the project website and used under the SIL Open Font License (see `fonts/`).
Archivo and Cascadia Code are copied from the project website and used under the SIL Open Font License (see `fonts/`). Octicons are by GitHub, used under the MIT License.
19 changes: 19 additions & 0 deletions generator/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions generator/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"node": ">=22"
},
"dependencies": {
"@primer/octicons": "19.42.0",
"playwright": "1.64.1"
}
}
120 changes: 0 additions & 120 deletions generator/readme-banners.mjs

This file was deleted.

108 changes: 108 additions & 0 deletions generator/readme-brand.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
// Pure functions that apply the AsBuiltReport brand to a module README:
// addBanner the repo banner in place of the old organisation logo
// addSectionIcons section icons in place of the emoji on known section headings
// recolourBadges shields.io badges in the brand palette
// readme-banners.mjs uses these to open pull requests. readme-brand.test.mjs tests them.

import { readFileSync } from "node:fs";
import { join } from "node:path";
import { config, here } from "./repos.mjs";

const { icons } = JSON.parse(readFileSync(join(here, "section-icons.json"), "utf8"));
const assetBase = `https://raw.githubusercontent.com/${config.org}/.github/main/assets`;

const eolOf = (text) => (text.includes("\r\n") ? "\r\n" : "\n");

// ---------- Banner ----------

export function bannerBlock(repo, eol = "\n") {
return [
'<p align="center">',
' <a href="https://www.asbuiltreport.com/">',
` <img src="${assetBase}/repo-banners/${repo}.png" alt="${repo}" width="880"></a>`,
"</p>",
].join(eol);
}

// The old logo is a centred paragraph holding the organisation avatar or AsBuiltReport.png.
const logoBlock = /<p align="center">\s*<a href="https:\/\/www\.asbuiltreport\.com\/?"[^>]*>(?:\s*<\/a>)?\s*<img src=['"](?:https:\/\/github\.com\/AsBuiltReport\.png|https:\/\/avatars\.githubusercontent\.com\/u\/42958564[^'"]*|[^'"]*\/AsBuiltReport\.png)['"][^>]*>\s*(?:<\/a>)?\s*<\/p>/;

export function addBanner(readme, repo) {
if (readme.includes("/assets/repo-banners/")) return readme;
const block = bannerBlock(repo, eolOf(readme));
if (logoBlock.test(readme)) return readme.replace(logoBlock, block);

// No logo: put the banner first, after the "DO NOT EDIT" comment if the README has one.
const comment = readme.match(/^<!--[^\n]*DO NOT EDIT[^\n]*-->\r?\n/);
const head = comment ? comment[0] : "";
return head + block + eolOf(readme) + readme.slice(head.length);
}

// ---------- Section icons ----------

// A GitHub :shortcode: or a run of Unicode emoji (with variation selectors and joiners).
const emoji = String.raw`(?::[a-z0-9_+-]+:|(?:\p{Extended_Pictographic}|\p{Regional_Indicator})(?:️|‍|\p{Extended_Pictographic})*)`;
const leadingEmoji = new RegExp(String.raw`^(?:${emoji}\s*)+`, "u");
const trailingEmoji = new RegExp(String.raw`(?:\s*${emoji})+$`, "u");
const iconSizes = { 1: 28, 2: 24, 3: 20, 4: 16 };

const normalise = (text) => text.replace(/\*\*/g, "").replace(/\s+/g, " ").trim().toLowerCase();
const iconByHeading = new Map(icons.flatMap((icon) => icon.headings.map((h) => [normalise(h), icon])));

export function sectionIcon(icon, level) {
const size = iconSizes[level];
return `<img src="${assetBase}/section-icons/${icon.name}.svg" alt="" width="${size}" height="${size}" align="top">`;
}

export function addSectionIcons(readme) {
const eol = eolOf(readme);
let fence = null;
return readme.split(/\r?\n/).map((line) => {
// Skip fenced code blocks, where "# ..." lines are comments, not headings.
const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
if (fenceMatch) {
if (!fence) fence = fenceMatch[1][0];
else if (fenceMatch[1][0] === fence) fence = null;
return line;
}
if (fence) return line;

const heading = line.match(/^(#{1,4})\s+(.*?)\s*$/);
if (!heading || heading[2].includes("/assets/section-icons/")) return line;
const hadEmoji = leadingEmoji.test(heading[2]);
const text = heading[2].replace(leadingEmoji, "").replace(trailingEmoji, "").trim();
const icon = iconByHeading.get(normalise(text));
// Headings without an emoji only get an icon down to level 3, so deep sub-headings stay plain.
if (!icon || (!hadEmoji && heading[1].length > 3)) return line;
return `${heading[1]} ${sectionIcon(icon, heading[1].length)} ${text}`;
}).join(eol);
}

// ---------- Badges ----------

// Brand palette for shields.io badges: link blue for versions, console blue for counts,
// highlighter for compatibility. Shields picks dark text on the highlighter automatically.
const badgeColours = [
{ pattern: /img\.shields\.io\/powershellgallery\/v\//, colour: "1F5FD0" },
{ pattern: /img\.shields\.io\/github\/v\/release\//, colour: "1F5FD0" },
{ pattern: /img\.shields\.io\/powershellgallery\/dt\//, colour: "012456" },
{ pattern: /img\.shields\.io\/github\/contributors\//, colour: "012456" },
{ pattern: /img\.shields\.io\/github\/stars\//, colour: "012456" },
{ pattern: /img\.shields\.io\/powershellgallery\/p\//, colour: "FFD02B" },
];

export function recolourBadge(url) {
const rule = badgeColours.find((r) => r.pattern.test(url));
if (!rule) return url;
const [path, query = ""] = url.split("?");
const params = query.split("&").filter((p) => p && !/^colou?r=/i.test(p));
return `${path}?${[`color=${rule.colour}`, ...params].join("&")}`;
}

export function recolourBadges(readme) {
return readme.replace(/https:\/\/img\.shields\.io\/[^\s"'()<>]+/g, recolourBadge);
}

export function applyBrand(readme, repo) {
return recolourBadges(addSectionIcons(addBanner(readme, repo)));
}
Loading
Loading