https://github.com/programming-sai/github-readme-site-preview
Automatically generate responsive device mockups of your website and display them in your GitHub README using screenshots.
https://github.com/programming-sai/github-readme-site-preview
automation github github-actions mockup nodejs pupeteer readme
Last synced: 6 months ago
JSON representation
Automatically generate responsive device mockups of your website and display them in your GitHub README using screenshots.
- Host: GitHub
- URL: https://github.com/programming-sai/github-readme-site-preview
- Owner: Programming-Sai
- Created: 2025-04-13T01:35:00.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-14T05:55:05.000Z (6 months ago)
- Last Synced: 2025-04-14T17:14:11.121Z (6 months ago)
- Topics: automation, github, github-actions, mockup, nodejs, pupeteer, readme
- Language: JavaScript
- Homepage:
- Size: 16.9 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitHub README Site Preview
**Automatically generate responsive device mockups of your website and display them in your GitHub README using screenshots.**
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Sample Output Files](#sample-output-files)
- [Contributing](#contributing)
## Overview
The 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.
## Features
- **Screenshot Capture**: Capture screenshots from a specified URL with customizable viewport dimensions.
- **Multiple Device Support**: Generate previews for different devices (laptop, tablet, mobile) using predefined configurations.
- **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).
- **Mockup Embedding**: Processes and embeds the captured screenshots into device mockups with rounded corners using Sharp.
- **Flexible CLI**: Accept parameters via command-line arguments (URL, devices, output, selectors) using `yargs`.
- **GitHub Actions Integration**: Easily integrate into GitHub Actions for scheduled or on-demand updates.
- **Error Handling**: Gracefully handles invalid URLs and provides clear logging on skipped devices.
## Installation
Clone the repository and install the dependencies:
```bash
git clone https://github.com/Programming-Sai/Github-README-Site-Preview.git
cd Github-README-Site-Preview
npm install
```
## Configuration
The project is organized into several parts:
```ftt
./Github-README-Site-Preview/*
├─ assets/*
| ├─ Laptop.png
| ├─ Mobile.png
| └─ Tablet.png
├─ public/*
| └─ ... # Ouputs Are Saved Here By Default
├─ src/*
| ├─ config/*
| | └─ deviceConfigs.js
| ├─ utils/*
| | ├─ embed.js
| | ├─ screenshot_capture.js
| | └─ themeToggle.js
| └─ index.js
├─ .fttignore
├─ .gitignore
├─ m.md
├─ package-lock.json
├─ package.json
└─ README.md
```
- **Core Logic**: Contains the core screenshot and embedding functionality located in the `src/` directory.
- `src/utils/screenshot_capture.js` – Uses Puppeteer to capture screenshots.
- `src/utils/embed.js` – Uses Sharp to embed the screenshot buffers into device mockups.
- `src/config/deviceConfigs.js` – Contains the configuration for each device type (laptop, tablet, mobile).
- **Command-Line Interface**:
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.
## Usage
### Running Locally
You can run the tool directly from the command line with either named flags or positional arguments.
#### **Using Named Flags**
```bash
npm run capture -- --url "https://example.com" --devices "laptop,tablet" --output "public/preview.png" --selectors ".btn-toggle-selector1,.btn-toggle-selector2"
```
#### **Using Positional Arguments**
```bash
node src/index.js "https://example.com" "laptop,tablet" "public/preview.png" ".btn-toggle-selector1,.btn-toggle-selector2"
```
### Command-Line Options
- **`--url`** or **`-u`**:
**(Required)** The URL of the website to capture.
- **`--devices`** or **`-d`**:
Comma-separated list of device names. Valid values: `laptop`, `tablet`, `mobile`.
_Default_: `laptop,tablet,mobile`
- **`--output`** or **`-o`**:
**(Required if using positional args)** The directory where the result (screenshots and mockup images) will be saved.
**Important:** This must be a directory path (e.g., `public`) and **must not include a filename or file extension.**
_Default_: `public`
- **`--selectors`** or **`-s`**:
Comma-separated list of CSS selectors to target specific elements for theme toggling.
_Default_: _(empty)_
> **Note:** If you omit any named parameters (especially `--output`), the values may shift, so it’s recommended to always specify these flags explicitly.
### Sample Output Files
After running the script, you can expect the output images to be saved in the `public/` folder with names like:
- `public/output_laptop_theme1.png`
- `public/output_laptop_theme2.png`
- `public/output_tablet_theme1.png`
- `public/output_tablet_theme2.png`
- `public/output_mobile_theme1.png`
- `public/output_mobile_theme2.png`
| Theme 1 | Theme 2 |
| ---------------------------------------------------- | ---------------------------------------------------- |
|  |  |
|  |  |
|  |  |
## Contributing
Contributions, feature requests, and bug reports are welcome. Please open an issue or submit a pull request.
---