| name | portfolio-site-management |
| description | Maintain rcarmo.github.io thoroughly: content, icons, diagrams, favicon, build, rebuild/tag/push workflow, and client-side sorting/related behavior. |
Portfolio Site Management
Manage the projects/rcarmo.github.io portfolio site thoroughly and safely.
Scope
This skill applies when working on:
- project metadata under
_content/*.md
- generated pages (
index.html, projects/*.html)
- site generator logic in
build.ts
- client-side behavior in
assets/js/repo-island.mjs
- styles in
assets/css/style.css
- icons, logos, favicon, banners, and diagrams under
assets/
- release/tag/publish workflow for the site
Canonical files
Read these before making non-trivial changes:
build.ts
assets/js/repo-island.mjs
assets/css/style.css
.github/workflows/build.yml
- relevant
_content/<project>.md files
Site model
_content/*.md is the source of truth for project metadata and page content.
build.ts generates:
index.html
projects/*.html
- Live GitHub metadata is filled in client-side by
assets/js/repo-island.mjs.
- Do not hand-edit generated HTML unless debugging temporarily; persist real fixes in source files.
Working rules
- Read before editing.
- Prefer fixing generator/content logic over patching generated output.
- Rebuild only when needed.
- Do not say work is done without verifying generated output.
- Keep dark/light mode behavior intact.
Important user preferences
Visual language
- Clean black/white design with blue accent.
- IBM Plex headings, Inter body, JetBrains Mono.
- Avoid heavy gradients and visual clutter.
- Icons should not have framed boxes/borders unless explicitly requested.
- Diagrams must render at natural size, not stretched full width.
Home page
- The home hero stays centered.
- Motto + avatar are the focal point.
- Stats sit below the centered hero group.
Icons and logos
- Never embed icons as base64 data URIs.
- Always reference logo/image files by normal paths/URLs.
- Preserve real project-specific icons whenever they exist.
- Use fallback/default icons only when a real
logo: is absent or missing.
- If a user reports an icon exists, verify both:
_content/<project>.md
- corresponding assets under
assets/logos-opt/ and assets/logos/
- Remove letter-generated/fake icons when the user wants placeholders/default behavior instead.
Favicon
- Favicon should be derived from the avatar.
- Publish from site root when possible:
- Generated pages should reference root favicon paths, not deep asset paths.
Related items
- Hero-area related items must be chosen from the same section/category.
- They must be sorted client-side by descending live GitHub stars.
- Limit to top 5.
- Do not render the header or block until live data is available.
Metadata policy
Use frontmatter consistently:
repo: GitHub full name when not rcarmo/<id>
section: category key
status: stable/active/etc.
created: YYYY-MM-DD when known
logo: only for real curated/project-specific icons
featured: for homepage featured projects
related: only if explicitly needed beyond same-section logic
Creation dates
When assigning age-based fallback icons or maintaining historical metadata:
- Query GitHub for repository creation date.
- Store it as
created: YYYY-MM-DD in frontmatter.
- Prefer maintainable metadata over one-off logic.
Diagram policy
When editing a project diagram:
- Prefer inline SVG.
- Make it light/dark aware using
prefers-color-scheme.
- Reflect actual architecture from docs/repo behavior, not generic boxes.
- Keep sizes reasonable and allow natural scaling in page CSS.
- Mermaid is acceptable only if it clearly improves maintainability and rendering is reliable in this site.
- Read
.pi/skills/graph-design/SKILL.md before non-trivial diagram audits or redraws.
Build and verification
Rebuild
From repo root:
bun run build.ts
Verify after rebuild
Check at least:
index.html was regenerated
- relevant
projects/*.html pages were regenerated
- logo references are file paths, not data URIs
- no broken/missing hero logos
- related items behavior still makes sense
- diagrams render with natural sizing
- favicon references point to root paths
Useful checks:
rg "data:image|card-logo-placeholder|missing-random|default.png" index.html projects/*.html
rg "repo-island\.mjs\?v=" index.html projects/*.html
Publishing workflow
The repo publishes via GitHub Actions.
Important
- Ordinary pushes to
master do not necessarily publish.
- Tag pushes matching
v* trigger the release workflow.
Always read .github/workflows/build.yml before changing publish assumptions.
Standard publish sequence
When the user explicitly asks to publish/rebuild/tag/push:
- Commit source/content changes.
- Rebuild with
bun run build.ts.
- Commit generated output if it changed.
- Push
master.
- Create and push a new
v* tag.
Example pattern:
git add -A
git commit -m "Apply latest content updates"
bun run build.ts
git add index.html projects/*.html
git commit -m "Rebuild site"
git push origin master
git tag -a vYYYY.MM.DD.N -m "Release vYYYY.MM.DD.N"
git push origin vYYYY.MM.DD.N
Common tasks
Add or fix a project icon
- Check
_content/<project>.md for logo:.
- Check
assets/logos-opt/<project>.* and assets/logos/<project>.*.
- If a real icon exists, point
logo: at it.
- If no real icon exists, remove fake/generated icon assets and let fallback logic handle it.
- Rebuild only if requested or needed for verification.
Replace a diagram
- Read the project content file.
- Read the upstream docs/README if the project architecture matters.
- Replace only the
## Diagram section.
- Keep the SVG theme-aware.
- Rebuild and verify rendering.
Fix sorting/hero behavior
- Inspect
assets/js/repo-island.mjs first.
- If behavior depends on live GitHub data, keep ranking client-side.
- Cache-bust the JS import when necessary so browsers pick up changes.
- Rebuild generated pages after changing script references.
Fix favicon issues
- Compare with known-good local web UI behavior if needed.
- Prefer root-level
favicon.ico and favicon.png.
- Update
build.ts head tags.
- Rebuild and republish.
Do not
- Do not reintroduce base64-embedded icons.
- Do not mass-replace real icons with defaults.
- Do not add decorative icon frames the user removed.
- Do not assume cache issues are fixed without cache-busting if JS changed.
- Do not rebuild unless the task needs it or the user asked.
Deliverables
When finished, report briefly:
- what changed
- which source files changed
- whether you rebuilt
- whether you pushed/tagged
- any remaining uncertainty or follow-up needed