Skip to content

Home

Jump to bottom
AmooReza edited this page Jun 20, 2026 · 1 revision

🦚 readme-peacock Wiki

Welcome to the complete documentation for readme-peacock – a Python CLI that instantly turns your README.md into a stunning landing page.

Table of Contents

Installation

readme-peacock is published on PyPI. You need Python 3.8 or higher.

  1. (Optional but recommended) Create and activate a virtual environment: python -m venv venv On Windows: venv\Scripts\activate On macOS/Linux: source venv/bin/activate

  2. Install the package: pip install readme-peacock

After installation, the command peacock is available in your terminal.

Basic Usage

Navigate to any folder that contains a README.md and run:

peacock

This will create a site/ folder containing an index.html file. Open that file in a browser to see your landing page.

Command-Line Options

Option Description
input Path to the Markdown file (default: README.md)
-o, --output Output HTML file path (default: site/index.html)
--repo GitHub repository in user/repo format – adds quick-link buttons
--template Choose a theme: glass (default) or dark
--all Process all .md files in the current directory (or a given folder)
--help Show the help message
--version Display the tool version

Example:

peacock README.md -o landing.html --repo "ZvanTors/readme-peacock"

Processing Multiple Markdown Files

Use the --all flag to convert every .md file in a directory at once:

peacock --all

  • README.md becomes index.html
  • Other files (e.g. faq.md) keep their base name (faq.html)

All outputs are placed inside the site/ folder (or the directory you specify with -o).

Combine --all with other options:

peacock --all --template dark --repo "ZvanTors/readme-peacock"

Themes & Appearance

Two built-in themes are available through the --template option:

  • glass (default): A glassmorphism design that automatically switches between light and dark mode based on your OS settings.
  • dark: An always-dark theme with a black background and orange accents for buttons and links.

Each theme’s CSS variables are defined inside peacock.py. You can customize them by editing the source.

Output Naming

  • Single-file mode: The output path is exactly what you pass with -o. If the parent directory does not exist, it will be created automatically.
  • Multi-file mode (--all): The value given to -o (default site) is treated as a directory. Inside it:
    • A file whose stem is readme (case-insensitive) becomes index.html.
    • Every other file keeps its original name with a .html extension (e.g. contributing.md → contributing.html).

GitHub Quick-Link Buttons

When you provide --repo "user/repo", five static buttons are added to the hero section:

  • Issues
  • Pull Requests
  • Releases
  • Wiki
  • Star (links to the repository home)

These buttons are pure HTML – they work even if you open the file locally, no JavaScript API calls required.

GitHub Action Integration

You can use readme-peacock as a GitHub Action to automatically build and deploy your landing page on every push.

Setup

  1. In your repository, create a file at .github/workflows/peacock.yml.
  2. Add the following content (note the use of ZvanTors/readme-peacock@v1):

name: Generate Landing Page on: push: branches: [main] workflow_dispatch:

permissions: contents: read pages: write id-token: write

concurrency: group: "pages" cancel-in-progress: false

jobs: build: runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - uses: ZvanTors/readme-peacock@v1 with: repo: ${{ github.repository }}

  1. Go to Settings → Pages, and set the source to GitHub Actions.
  2. After your next push to main, the landing page will be live at https://USERNAME.github.io/REPO.

This Action is also listed on the GitHub Marketplace.

Real-World Examples

  • This project’s own landing page
    The README.md you are reading was converted by readme-peacock and deployed via GitHub Pages:
    https://zvanTors.github.io/readme-peacock

  • Dark theme preview
    Run the following to see the dark theme output locally: peacock --template dark -o dark-demo.html

Contributing & Development

Contributions are welcome! To get started:

  1. Fork the repository.
  2. Create a feature branch: git checkout -b feature/amazing-idea
  3. Make your changes and commit them: git commit -m "Add amazing idea"
  4. Push to your fork and open a Pull Request.

The source code lives in peacock.py (the only dependency is the markdown library).
Please test your changes with a sample README before submitting.

Frequently Asked Questions

1. Why are my images not showing in the output?
If your README references local images (e.g. screenshot.png), you need to copy those files next to the generated HTML file. The tool does not automatically copy assets.

2. Can I use my own custom CSS?
Currently you can manually edit the generated HTML. In future versions we plan to support a --css custom.css option.

3. Can I deploy the output to Vercel or Netlify?
Absolutely. The output is a static HTML file and works on any static hosting service.

We hope you enjoy using readme-peacock! 🦚

Clone this wiki locally