{"id":27433131,"url":"https://github.com/programming-sai/github-readme-site-preview","last_synced_at":"2026-04-19T14:05:07.729Z","repository":{"id":287826767,"uuid":"965359155","full_name":"Programming-Sai/Github-README-Site-Preview","owner":"Programming-Sai","description":"Automatically generate responsive device mockups of your website and display them in your GitHub README using screenshots.","archived":false,"fork":false,"pushed_at":"2025-04-14T05:55:05.000Z","size":17715,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T17:14:11.121Z","etag":null,"topics":["automation","github","github-actions","mockup","nodejs","pupeteer","readme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Programming-Sai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-04-13T01:35:00.000Z","updated_at":"2025-04-14T05:56:03.000Z","dependencies_parsed_at":"2025-04-14T06:44:22.925Z","dependency_job_id":null,"html_url":"https://github.com/Programming-Sai/Github-README-Site-Preview","commit_stats":null,"previous_names":["programming-sai/github-readme-site-preview"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FGithub-README-Site-Preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FGithub-README-Site-Preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FGithub-README-Site-Preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FGithub-README-Site-Preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Programming-Sai","download_url":"https://codeload.github.com/Programming-Sai/Github-README-Site-Preview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248923768,"owners_count":21183953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automation","github","github-actions","mockup","nodejs","pupeteer","readme"],"created_at":"2025-04-14T17:14:14.921Z","updated_at":"2026-04-19T14:05:07.690Z","avatar_url":"https://github.com/Programming-Sai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub README Site Preview\n\n**Automatically generate responsive device mockups of your website and display them in your GitHub README using screenshots.**\n\n\u003c!-- PLACEHOLDER: Add a demo banner or screenshot here --\u003e\n\n![GitHub README Site Preview](./public/output_laptop_theme1.png)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Sample Output Files](#sample-output-files)\n- [Contributing](#contributing)\n\n## Overview\n\nThe GitHub README Site Preview tool is designed to help you generate dynamic, device-specific screenshots of any website, process them into attractive mockups and output these images for use on your Website README. The tool supports multiple device types (laptop, tablet, mobile), theme toggling (if selectors are provided), and flexible command-line inputs. It can also be integrated into GitHub Actions for automated, scheduled updates.\n\n## Features\n\n- **Screenshot Capture**: Capture screenshots from a specified URL with customizable viewport dimensions.\n- **Multiple Device Support**: Generate previews for different devices (laptop, tablet, mobile) using predefined configurations.\n- **Theme Toggling**: (Optional) If a CSS selector or XPath is provided for a theme toggle, the tool captures two screenshots (e.g., light and dark themes).\n- **Mockup Embedding**: Processes and embeds the captured screenshots into device mockups with rounded corners using Sharp.\n- **Flexible CLI**: Accept parameters via command-line arguments (URL, devices, output, selectors) using `yargs`.\n- **GitHub Actions Integration**: Easily integrate into GitHub Actions for scheduled or on-demand updates.\n- **Error Handling**: Gracefully handles invalid URLs and provides clear logging on skipped devices.\n\n## Installation\n\nClone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/Programming-Sai/Github-README-Site-Preview.git\n\ncd Github-README-Site-Preview\n\nnpm install\n```\n\n## Configuration\n\nThe project is organized into several parts:\n\n```ftt\n\n./Github-README-Site-Preview/*\n        ├─ assets/*\n        |       ├─ Laptop.png\n        |       ├─ Mobile.png\n        |       └─ Tablet.png\n        ├─ public/*\n        |       └─ ... # Ouputs Are Saved Here By Default\n        ├─ src/*\n        |       ├─ config/*\n        |       |       └─ deviceConfigs.js\n        |       ├─ utils/*\n        |       |       ├─ embed.js\n        |       |       ├─ screenshot_capture.js\n        |       |       └─ themeToggle.js\n        |       └─ index.js\n        ├─ .fttignore\n        ├─ .gitignore\n        ├─ m.md\n        ├─ package-lock.json\n        ├─ package.json\n        └─ README.md\n\n```\n\n- **Core Logic**: Contains the core screenshot and embedding functionality located in the `src/` directory.\n\n  - `src/utils/screenshot_capture.js` – Uses Puppeteer to capture screenshots.\n  - `src/utils/embed.js` – Uses Sharp to embed the screenshot buffers into device mockups.\n  - `src/config/deviceConfigs.js` – Contains the configuration for each device type (laptop, tablet, mobile).\n\n- **Command-Line Interface**:  \n  The main entry point is `src/index.js`, which accepts arguments for URL, devices, output path, and selectors. It uses `yargs` (with positional and named options) to allow flexible configuration.\n\n## Usage\n\n### Running Locally\n\nYou can run the tool directly from the command line with either named flags or positional arguments.\n\n#### **Using Named Flags**\n\n```bash\nnpm run capture -- --url \"https://example.com\" --devices \"laptop,tablet\" --output \"public/preview.png\" --selectors \".btn-toggle-selector1,.btn-toggle-selector2\"\n```\n\n#### **Using Positional Arguments**\n\n```bash\nnode src/index.js \"https://example.com\" \"laptop,tablet\" \"public/preview.png\" \".btn-toggle-selector1,.btn-toggle-selector2\"\n```\n\n### Command-Line Options\n\n- **`--url`** or **`-u`**:  \n  **(Required)** The URL of the website to capture.\n\n- **`--devices`** or **`-d`**:  \n  Comma-separated list of device names. Valid values: `laptop`, `tablet`, `mobile`.  \n  _Default_: `laptop,tablet,mobile`\n\n- **`--output`** or **`-o`**:  \n  **(Required if using positional args)** The directory where the result (screenshots and mockup images) will be saved.  \n  **Important:** This must be a directory path (e.g., `public`) and **must not include a filename or file extension.**  \n  _Default_: `public`\n\n- **`--selectors`** or **`-s`**:  \n  Comma-separated list of CSS selectors to target specific elements for theme toggling.  \n  _Default_: _(empty)_\n\n\u003e **Note:** If you omit any named parameters (especially `--output`), the values may shift, so it’s recommended to always specify these flags explicitly.\n\n### Sample Output Files\n\nAfter running the script, you can expect the output images to be saved in the `public/` folder with names like:\n\n- `public/output_laptop_theme1.png`\n- `public/output_laptop_theme2.png`\n- `public/output_tablet_theme1.png`\n- `public/output_tablet_theme2.png`\n- `public/output_mobile_theme1.png`\n- `public/output_mobile_theme2.png`\n\n\u003c!-- PLACEHOLDER: Add images of the final outputs for each device here --\u003e\n\u003cp align='center'\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n| Theme 1                                              | Theme 2                                              |\n| ---------------------------------------------------- | ---------------------------------------------------- |\n| ![Laptop Theme 1](./public/output_laptop_theme1.png) | ![Laptop Theme 2](./public/output_laptop_theme2.png) |\n| ![Tablet Theme 1](./public/output_tablet_theme1.png) | ![Tablet Theme 2](./public/output_tablet_theme2.png) |\n| ![Mobile Theme 1](./public/output_mobile_theme1.png) | ![Mobile Theme 2](./public/output_mobile_theme2.png) |\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003c/p\u003e\n\n\u003c!-- ## GitHub Actions Integration\n\nYou can integrate this tool into GitHub Actions to automatically generate and update previews. Below is an example workflow file (`.github/workflows/screenshot-capture.yml`):\n\n```yaml\nname: Screenshot Capture\n\non:\n  workflow_dispatch:\n    inputs:\n      url:\n        description: 'The URL to capture'\n        required: true\n        default: 'https://example.com'\n      devices:\n        description: 'Comma-separated list of devices (e.g., laptop,tablet,mobile)'\n        required: true\n        default: 'laptop,tablet,mobile'\n      output:\n        description: 'Path to save the screenshot'\n        required: false\n        default: 'public/preview.png'\n      selectors:\n        description: 'Comma-separated list of CSS selectors'\n        required: false\n        default: ''\njobs:\n  generate:\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n\n    steps:\n      - name: Checkout Repository\n        uses: actions/checkout@v3\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v3\n        with:\n          node-version: '16'\n\n      - name: Install Dependencies\n        run: npm install\n\n      - name: Run Screenshot Capture Logic\n        run: |\n          node src/index.js --url \"${{ github.event.inputs.url }}\" --devices \"${{ github.event.inputs.devices }}\" --output \"${{ github.event.inputs.output }}\" --selectors \"${{ github.event.inputs.selectors }}\"\n```\n\nIn this workflow:\n- The user can trigger the workflow manually using `workflow_dispatch` inputs.\n- The specified URL, devices, output path, and selectors are passed to the tool.\n- The tool generates the screenshots and mockup images in the `public/` folder.\n- You can later use another step (or a separate workflow) to publish these images (for example, using [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)). --\u003e\n\n## Contributing\n\nContributions, feature requests, and bug reports are welcome. Please open an issue or submit a pull request.\n\n\u003c!-- ## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. --\u003e\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramming-sai%2Fgithub-readme-site-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogramming-sai%2Fgithub-readme-site-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramming-sai%2Fgithub-readme-site-preview/lists"}