{"id":48618232,"url":"https://github.com/hideack/storyboards-cli","last_synced_at":"2026-04-09T02:30:54.623Z","repository":{"id":347512624,"uuid":"1194265024","full_name":"hideack/storyboards-cli","owner":"hideack","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-28T12:12:00.000Z","size":48,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T12:30:52.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hideack.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":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T05:42:01.000Z","updated_at":"2026-03-28T07:33:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hideack/storyboards-cli","commit_stats":null,"previous_names":["hideack/storyboards-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hideack/storyboards-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideack%2Fstoryboards-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideack%2Fstoryboards-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideack%2Fstoryboards-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideack%2Fstoryboards-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hideack","download_url":"https://codeload.github.com/hideack/storyboards-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideack%2Fstoryboards-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31582533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"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":[],"created_at":"2026-04-09T02:30:51.861Z","updated_at":"2026-04-09T02:30:54.613Z","avatar_url":"https://github.com/hideack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# storyboards-cli\n\nA CLI tool that generates HTML presentations from Markdown files.\n\n---\n\n## Features\n\n- Write Markdown files to generate slides automatically\n- Switch appearances with themes\n- Import custom themes from SVG files (recommended)\n- Import themes from PDF files (experimental)\n- Use `visual` syntax to specify diagram insertion points\n- Auto-generate diagrams via Claude Code with the `--ai visual` option\n- Generated HTML has no external dependencies — open directly in a browser\n- Watch mode (`--watch`) for live reloading during editing\n\n---\n\n## Installation\n\n### Install from repository\n\n```bash\ngit clone https://github.com/hideack/storyboards-cli.git\ncd storyboards-cli\nnpm install\nnpm run build\nnpm link\n```\n\nAfter installation, the `storyboards` command becomes available.\n\n### Requirements\n\n- Node.js 18 or later\n\n---\n\n## Initial Setup\n\nWhen you run the `storyboards` command for the first time, the following setup is performed automatically:\n\n1. Create config file: `~/.config/storyboards-cli/config.json`\n2. Create theme directory: `~/.config/storyboards-cli/themes/`\n3. Install the built-in theme `simple`\n\nNo manual setup is required. Just run any command to trigger initialization.\n\n```bash\nstoryboards --help\n```\n\n---\n\n## build command\n\nGenerates an HTML presentation from a Markdown file.\n\n### Basic usage\n\n```bash\nstoryboards build slides.md\n```\n\nBy default, the following files are generated in the `storyboards-dist/` directory:\n\n```\nstoryboards-dist/\n  index.html\n  styles.css\n  app.js\n  assets/\n```\n\nOpen `index.html` in a browser to view the presentation.\n\n### Options\n\n| Option | Description | Default |\n|---|---|---|\n| `--theme \u003cname\u003e` | Theme name to use | `defaultTheme` in config |\n| `--out \u003cdir\u003e` | Output directory | `storyboards-dist` |\n| `--open` | Open in browser after build | false |\n| `--strict` | Treat warnings as errors and exit non-zero | false |\n| `--ai visual` | Auto-generate visual diagrams via Claude Code | disabled |\n| `--watch` | Watch for file changes and rebuild automatically | false |\n\n### Examples\n\n```bash\n# Build with a specific theme\nstoryboards build slides.md --theme my-corp\n\n# Specify output directory\nstoryboards build slides.md --out ./output\n\n# Build and open in browser immediately\nstoryboards build slides.md --open\n\n# Generate AI visual diagrams\nstoryboards build slides.md --ai visual\n\n# Watch mode with live reload\nstoryboards build slides.md --open --watch\n\n# Strict build for CI\nstoryboards build slides.md --strict\n```\n\n### Theme resolution order\n\n1. `--theme` option\n2. `theme` key in Markdown frontmatter\n3. `defaultTheme` in config\n\n---\n\n## Writing Markdown\n\n### Frontmatter\n\nYou can write YAML frontmatter at the top of the file.\n\n```markdown\n---\ntitle: My Presentation\ntheme: my-corp\n---\n```\n\n### Slide splitting rules\n\n| Markdown syntax | Slide type |\n|---|---|\n| First `# ` | title slide |\n| Second and later `# ` | section slide |\n| `## ` | content slide |\n\n### Example\n\n```markdown\n---\ntitle: Q4 2024 Strategy\ntheme: simple\n---\n\n# Q4 2024 Strategy\n\nExample Corp.\n\n# Introduction\n\n## Background\n\n\u003e Category: Market Analysis\n\nThe market environment has changed significantly this quarter.\n\n- New competitors entering the market\n- Diversifying user needs\n- Accelerating technology trends\n\n## Challenges and Responses\n\nWe will implement the following measures:\n\n1. Review product lineup\n2. Refresh marketing strategy\n3. Improve development process\n```\n\n### Eyebrow label\n\nWriting `\u003e text` at the beginning of a content slide displays a small label at the top of the slide.\n\n```markdown\n## Slide Title\n\n\u003e Category Name\n```\n\n### Text alignment and font size\n\nYou can add `{...}` attributes to the heading line to control per-slide text behavior.\n\n```markdown\n## Centered Slide {center}\nThis text will be center-aligned.\n\n## Fill Slide {fill}\nShort text is displayed as large as possible.\n\n## Both {center fill}\nCenter-aligned and maximized font size.\n```\n\n| Attribute | Description |\n|---|---|\n| `center` | Center-align body text |\n| `fill` | Expand font size to fill available space |\n\n---\n\n## visual syntax\n\nYou can specify diagram placement and instructions within a slide.\n\n### Inline form\n\n```markdown\n## Three Loop Structure\n\nThe business model consists of three loops.\n\n!visual: Show the three loop structure as a relationship diagram\n```\n\n### Block form\n\nUse block form for more detailed instructions.\n\n```markdown\n## Growth Strategy\n\n:::visual type=diagram\nThree loops — sales, operations, and cash —\nconnected through a central sales/payment hub.\nPlace \"Sales/Payment\" at the center.\n:::\n```\n\n### Supported visual types\n\n| type | Use case |\n|---|---|\n| `auto` | Auto-detect (default) |\n| `diagram` | Relationship / concept diagrams |\n| `flow` | Flow / step diagrams |\n| `compare` | Comparison / contrast |\n| `chart` | Graphs / proportions / trends |\n\n### Without `--ai visual`\n\nIf `--ai visual` is not specified, a fallback placeholder is inserted at the visual position.\n\n### Using `--ai visual`\n\nRequires Claude Code to be installed and the `claude` command to be available.\n\n```bash\nstoryboards build slides.md --ai visual\n```\n\nGenerated visuals are saved as `assets/slide-XX-visual.svg` and embedded in the HTML. Results are cached at `~/.cache/storyboards-cli/visuals/`.\n\n---\n\n## theme command\n\n### List themes\n\n```bash\nstoryboards theme list\n```\n\nThe default theme is marked with `*`.\n\n### Set default theme\n\n```bash\nstoryboards theme use my-corp\n```\n\n### Show theme details\n\n```bash\nstoryboards theme show simple\n```\n\n### Validate a theme\n\n```bash\nstoryboards theme validate my-corp\n```\n\n### theme import (SVG)\n\nImport a custom theme from SVG files. **SVG import is the recommended method.**\n\n```bash\nstoryboards theme import \\\n  --name my-corp \\\n  --title title.svg \\\n  --section section.svg \\\n  --content content.svg\n```\n\nThe following are automatically generated from the SVG:\n\n- `theme.json` (layout information is auto-detected)\n- Background images under `assets/`\n\nAfter importing, activate with:\n\n```bash\nstoryboards theme use my-corp\n```\n\n#### Recommended SVG specification\n\nSpecify text placement areas using `\u003cpath\u003e` elements with `fill-opacity=\"0\"`. storyboards-cli uses the coordinates of these transparent paths to estimate text slot layouts.\n\n| Order (top to bottom) | Slot |\n|---|---|\n| title slide: 1st transparent path | title |\n| title slide: 2nd transparent path | subtitle |\n| content slide: 1st | eyebrow |\n| content slide: 2nd | title |\n| content slide: 3rd | body |\n| content slide: 4th | visual region |\n\n### theme import (PDF) [experimental]\n\nYou can import a theme from a PDF template. Note that **PDF import is an experimental feature**.\n\n```bash\nstoryboards theme import \\\n  --name my-corp-pdf \\\n  --pdf template.pdf\n```\n\n- Layout information cannot be accurately extracted from PDF; default layout is applied\n- Complex designs are not supported\n- Manually adjust `theme.json` as needed\n- The `kind` field in `theme.json` will be `\"imported-pdf-theme\"`\n\n---\n\n## config command\n\n### Show config\n\n```bash\nstoryboards config show\n```\n\n### Set config values\n\n```bash\n# Change theme directory\nstoryboards config set themeDirectory /path/to/my-themes\n\n# Change default theme\nstoryboards config set defaultTheme my-corp\n```\n\nConfigurable keys:\n\n| Key | Description |\n|---|---|\n| `themeDirectory` | Path to the directory containing themes |\n| `defaultTheme` | Default theme name |\n\n---\n\n## Slide navigation\n\nOpen the generated `index.html` in a browser and use the following controls:\n\n| Input | Action |\n|---|---|\n| `→` / `↓` / Space | Next slide |\n| `←` / `↑` | Previous slide |\n| `Home` | First slide |\n| `End` | Last slide |\n| Swipe (touch) | Navigate slides |\n\n---\n\n## Directory structure (for developers)\n\n```\nstoryboards-cli/\n├── src/\n│   ├── commands/        # CLI command definitions\n│   │   ├── build.ts\n│   │   ├── theme.ts\n│   │   └── config.ts\n│   ├── core/            # Core logic\n│   │   ├── config.ts    # Config management\n│   │   ├── theme.ts     # Theme management \u0026 import\n│   │   ├── build.ts     # Build orchestrator\n│   │   ├── markdown.ts  # Markdown parser\n│   │   ├── visual.ts    # AI visual generation\n│   │   ├── renderer.ts  # HTML/CSS/JS generation\n│   │   └── types.ts     # Type definitions\n│   ├── utils/           # Utilities\n│   │   ├── fs.ts\n│   │   ├── log.ts\n│   │   ├── hash.ts\n│   │   └── path.ts\n│   ├── builtin-themes/\n│   │   └── simple/\n│   │       └── theme.json\n│   └── index.ts         # CLI entry point\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhideack%2Fstoryboards-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhideack%2Fstoryboards-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhideack%2Fstoryboards-cli/lists"}