{"id":50866356,"url":"https://github.com/dukebarman/hugo-theme-from-design","last_synced_at":"2026-06-15T01:38:18.394Z","repository":{"id":359958131,"uuid":"1244975833","full_name":"dukebarman/hugo-theme-from-design","owner":"dukebarman","description":"Codex skill for creating, updating and validating Hugo themes from Figma frames, screenshots and existing theme references.","archived":false,"fork":false,"pushed_at":"2026-06-08T19:49:30.000Z","size":265,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T21:23:16.826Z","etag":null,"topics":["codex-skill","design-to-code","figma","hugo","hugo-theme"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dukebarman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T19:35:56.000Z","updated_at":"2026-06-08T19:49:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dukebarman/hugo-theme-from-design","commit_stats":null,"previous_names":["dukebarman/hugo-theme-from-design"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dukebarman/hugo-theme-from-design","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dukebarman%2Fhugo-theme-from-design","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dukebarman%2Fhugo-theme-from-design/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dukebarman%2Fhugo-theme-from-design/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dukebarman%2Fhugo-theme-from-design/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dukebarman","download_url":"https://codeload.github.com/dukebarman/hugo-theme-from-design/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dukebarman%2Fhugo-theme-from-design/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34344440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex-skill","design-to-code","figma","hugo","hugo-theme"],"created_at":"2026-06-15T01:38:17.701Z","updated_at":"2026-06-15T01:38:18.389Z","avatar_url":"https://github.com/dukebarman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hugo Theme From Design\n\nSkill for creating, updating, and repairing Hugo themes from design references such as Figma frames, exported assets, screenshots, or existing Hugo theme repositories. It is designed for Codex and other agent runners that load `SKILL.md`.\n\nThe skill is aimed at turning a visual design into a reusable Hugo theme package, not just a static screenshot match. It guides the agent through theme scaffolding, `exampleSite` generation, Hugo build validation, preview image capture, and package-readiness checks for public theme repositories, including configurable footer attribution.\n\nFor publishable themes, the skill also guides neutral demo favicon/webmanifest assets when the theme owns `\u003chead\u003e` metadata. Favicons should use a simplified high-contrast mark that remains readable at 16x16 and 32x32, not a tiny crop of a detailed hero image.\n\nPublication guidance also covers subpath-safe internal links and asset URLs, neutral demo social links, compressed demo imagery, CDN-free theme head output, and safe code render hooks.\n\nFor publishable blog, magazine, documentation, and long-form article themes, the skill can also prepare renderer-friendly article markup for Telegram Instant View and similar extractors. This is optional: the generated theme can expose stable selectors and a sample IV template, but Telegram Instant View must still be configured and validated per live domain in Telegram's editor.\n\n## When to use it\n\nUse `$hugo-theme-from-design` when you want an agent to:\n\n- create a new Hugo theme variant from a Figma frame, PNG, or JPG reference;\n- match an existing Hugo theme to a visual design;\n- repair Hugo layout, asset, metadata, or build issues;\n- migrate or modernize an older Hugo theme while preserving its public surface;\n- prepare a theme for GitHub or `themes.gohugo.io` publication.\n\n## What it includes\n\n- `SKILL.md` - the main workflow and implementation rules for agents.\n- `assets/telegram-instant-view.tpl` - reusable starting template for optional Telegram Instant View support in article-focused themes.\n- `references/` - Hugo packaging notes, UI review guidance, theme tutorial findings, Telegram IV details, and existing-site repair guidance.\n- `scripts/hugo_theme_check.py` - structural checks, metadata checks, and optional Hugo smoke builds.\n- `scripts/render_theme_preview.py` - headless browser capture for `images/screenshot.png` and `images/tn.png`.\n- `tests/` - unit tests for the helper scripts.\n- `agents/openai.yaml` - display metadata for OpenAI/Codex skill interfaces.\n\n## Requirements\n\n- Codex with local skills support, or another agent runner that loads `SKILL.md`.\n- Hugo available on `PATH` for build validation.\n  Tested with Hugo `v0.162.1+extended+withdeploy`.\n- Python 3.10 or newer for the helper scripts.\n- Firefox, Chrome, or Chromium for automated preview image capture.\n\nThe skill can still guide implementation without every optional tool installed, but final validation is strongest when Hugo and a headless browser are available.\n\n## Installation\n\nClone or copy this directory into your Codex skills directory. If `CODEX_HOME`\nis not set, use `~/.codex`. Do not run `mkdir -p \"$CODEX_HOME/skills\"` with an\nempty `CODEX_HOME`: it expands to `/skills`, which is read-only on many macOS\nsystems.\n\n```bash\nSKILLS_DIR=\"${CODEX_HOME:-$HOME/.codex}/skills\"\nmkdir -p \"$SKILLS_DIR\"\ngit clone https://github.com/dukebarman/hugo-theme-from-design.git \"$SKILLS_DIR/hugo-theme-from-design\"\n```\n\nIf your agent runner loads skills from Agents-style directories, install it\nthere instead:\n\n```bash\nmkdir -p \"$HOME/.agents/skills\"\ngit clone https://github.com/dukebarman/hugo-theme-from-design.git \"$HOME/.agents/skills/hugo-theme-from-design\"\n```\n\nFor a project-local install, clone it under the project:\n\n```bash\ncd /path/to/your-hugo-project\nmkdir -p .agents/skills\ngit clone https://github.com/dukebarman/hugo-theme-from-design.git .agents/skills/hugo-theme-from-design\n```\n\nThen invoke it in Codex, or in another compatible runner, with:\n\n```text\nUse $hugo-theme-from-design to create a Hugo theme from this screenshot.\n```\n\n## Typical workflow\n\n1. Provide the agent with a design reference, such as a screenshot, Figma export, or existing theme repository.\n2. Ask for a new variant, a compatible port, an update, or a repair.\n3. The agent inspects the Hugo project, scaffolds or updates the theme, and creates an `exampleSite` when appropriate.\n4. The agent validates the result with Hugo and the bundled checker.\n5. For publishable themes, the agent can capture preview images and run additional package-readiness checks.\n\n## Helper commands\n\nRun the structural checker against a theme:\n\n```bash\npython3 scripts/hugo_theme_check.py --theme-dir /path/to/theme\n```\n\nRun publication-oriented checks:\n\n```bash\npython3 scripts/hugo_theme_check.py --theme-dir /path/to/theme --publication\n```\n\nPublication checks include warning-level favicon/webmanifest checks: missing\nmanifest companion icons, missing files referenced from favicon links in head\npartials, missing README override documentation, and basic sanity checks for\n`favicon-16x16.png` and `favicon-32x32.png`.\n\nPublication checks also run a subpath `baseURL` smoke build when builds are not\nskipped. They warn when generated HTML still contains root-relative asset URLs\nsuch as `src=\"/js/app.js\"` or root-relative internal links such as\n`href=\"/posts/\"`, when README/config/front matter recommend root-relative URL\nparams such as `/images/...` or `/tags/...`, when templates pass root-relative\ninputs to `relURL`, `relLangURL`, `absURL`, or `absLangURL`, when theme-owned\nhead output depends on external CDN assets, when `exampleSite` does not use\n`https://example.com/` as `baseURL`, when neutral demos contain fake or\nunrelated social profiles, when demo PNG/JPG assets under `static/images` are\noversized, and when code block render hooks pass `.Inner` to `safeHTML` without\n`htmlEscape`.\n\nWhen a theme includes `docs/telegram-instant-view.tpl`, or positively documents\nTelegram Instant View support in its README, publication checks emit\nwarning-level guidance for stable article selectors, article metadata, image\nmetadata, README documentation, and per-domain Telegram template wording. These\nchecks are not errors and are not applied to themes that do not declare IV\nsupport.\n\nValidate a known-theme port:\n\n```bash\npython3 scripts/hugo_theme_check.py --theme-dir /path/to/theme --mode port --publication\n```\n\nCapture preview images from a running local Hugo server:\n\n```bash\npython3 scripts/render_theme_preview.py \\\n  --url http://127.0.0.1:1313/ \\\n  --theme-dir /path/to/theme\n```\n\nChrome or Chromium is preferred for JavaScript-heavy themes because the helper\ncan give Chromium a virtual time budget before capture. Firefox capture uses a\ntemporary profile for reliability, but it has no equivalent built-in wait flag.\n\nRun the unit tests:\n\n```bash\npython3 -m unittest discover -s tests\n```\n\n## Development notes\n\nKeep `SKILL.md` focused on instructions the agent should follow during task execution. Put longer background material, checklists, and research notes in `references/` so the skill can load them only when relevant.\n\nWhen updating helper scripts, add or update focused tests under `tests/` and run the full unittest suite before publishing changes.\n\n## Favicons And Webmanifest\n\nFor publishable themes that own `\u003chead\u003e` metadata, the recommended neutral demo\nfavicon set is:\n\n- `static/favicon.ico`\n- `static/favicon-16x16.png`\n- `static/favicon-32x32.png`\n- `static/apple-touch-icon.png`\n- `static/android-chrome-192x192.png`\n- `static/android-chrome-512x512.png`\n- `static/site.webmanifest`\n\nThe head partial should link these files with `relURL`, including `rel=\"icon\"`,\n`rel=\"apple-touch-icon\"`, and `rel=\"manifest\"` entries. Treat them as demo\nassets: site owners should be able to replace them by placing files with the\nsame names in their site `static/` directory.\n\nUse a simplified mark from the theme's demo visual language. Avoid real people,\npersonal identifiers, readable text, logos, trademarks, and watermarks. Inspect\nthe rendered 16x16 and 32x32 files directly and simplify or regenerate if the\nicon becomes a dark blob, loses its silhouette, or depends on fine detail.\n\n## Telegram Instant View\n\nThe skill treats Telegram Instant View as an optional publication pattern for\narticle-focused Hugo themes. When requested, the agent should add stable selectors\nsuch as `article[data-iv-article]`, `.iv-title`, `[data-iv-published]`,\n`[data-iv-content]`, optional `[data-iv-cover]`, and `[data-iv-remove]` for UI\nchrome that should not appear in the rendered article.\n\nThe theme should also provide article metadata such as canonical URL,\ndescription, Open Graph article fields, `og:image`,\n`article:published_time`, `article:modified_time`, and `article:author`, plus\nfront matter conventions for cover images and authors. Markdown image and code\nrender hooks should preserve figure captions and code language metadata when\nthe theme needs publication-grade article rendering.\n\n`assets/telegram-instant-view.tpl` is a reusable starting point for a theme-level\n`docs/telegram-instant-view.tpl`. Adapt its `?path` rule to the live site URL\nstructure, such as `/posts/`, `/blog/`, `/articles/`, or `/docs/`. The theme\ndoes not enable Telegram Instant View automatically; site owners must configure\nand validate the template for their live domain in Telegram's editor. Official\ndocumentation: https://instantview.telegram.org/docs/\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) for the standard license text and\n[NOTICE](NOTICE) for copyright and attribution notices.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdukebarman%2Fhugo-theme-from-design","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdukebarman%2Fhugo-theme-from-design","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdukebarman%2Fhugo-theme-from-design/lists"}