Your README Is Already a Website

Announcing readme-to-index — My First GitHub Marketplace Release 🎉

Today I published my first GitHub Action to the Marketplace.

It’s called readme-to-index, and it does something very simple:

It turns your README.md into a clean, styled index.html.

That’s it.

No Jekyll.
No Ruby.
No themes.
No _config.yml.
No implicit behaviour.

Just Markdown → HTML → Done.

---

Why I Built It

I have a lot of small projects.

Many of them already have good READMEs. In fact, for most of them, the README is the documentation.

So the obvious question is:

Why create a separate site when the README already exists?

GitHub Pages + Jekyll is great. But for small libraries and utilities, it can feel like overkill.

I wanted something:

• Minimal
• Deterministic
• Easy to drop into any workflow
• Friendly to CI pipelines
• With zero hidden conventions

So I built a GitHub Action that does exactly one thing:

README.md → index.html

Styled using Simple.css (by default, but you can use any stylesheet you like).

---

What It Does

• Converts README.md to index.html using Pandoc
• Automatically sets the HTML <title> from the first # Heading
• Applies Simple.css for clean, classless styling
• Suppresses Pandoc’s injected syntax-highlighting CSS
• Leaves your original README untouched

Your README remains the canonical source of truth.

---

Usage

Add this to your workflow:

- uses: davorg/readme-to-index@v1
  with:
    output: _site/index.html

Then deploy using the standard GitHub Pages artifact flow.

---

Available Options

The action supports a few optional inputs:

readme

Path to the Markdown source file.

Default: README.md

output

Path to the generated HTML file.

Default: index.html

css_url

CSS stylesheet to include in the generated HTML.

Default: https://cdn.simplecss.org/simple.min.css

install_pandoc

Whether to install Pandoc automatically using apt-get.

Default: true

Set this to false if your workflow already installs Pandoc.

extra_pandoc_args

Additional arguments passed directly to the Pandoc command.

Example:

- uses: davorg/readme-to-index@v1
  with:
    extra_pandoc_args: "--toc"

---

Enabling GitHub Pages

For this to deploy as a website, you’ll need to enable GitHub Pages in your repository settings.

Go to:

Repository → Settings → Pages → Build and deployment

Set:

• Source: GitHub Actions

That’s it. The workflow will handle the rest.

---

Example Complete Workflow

Here’s a minimal working example:

name: Publish README to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

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

jobs:
  pages:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - uses: davorg/readme-to-index@v1
        with:
          output: _site/index.html

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - id: deployment
        uses: actions/deploy-pages@v4

---

Why Not Just Use Jekyll?

You absolutely can.

But this approach has two real advantages:

1. Simplicity

There’s no Ruby toolchain.

There are no implicit layouts.

There are no theme conventions to understand.

It takes one Markdown file and produces one HTML file.

That’s it.

2. Pipeline-Friendly

Because it’s "just a step", you can use it:

• As part of a release build
• In CI pipelines
• Before publishing documentation artifacts
• Outside GitHub entirely

It doesn’t rely on GitHub Pages’ default behaviour.

It works wherever Pandoc runs.

---

A Small Milestone

Shipping something to the GitHub Marketplace feels surprisingly significant.

It’s a tiny tool.
It does one thing.
But it does it cleanly.

That’s the kind of tooling I like building.

If you’re interested:

👉 https://github.com/marketplace/actions/readme-to-index-html

Feedback welcome. Stars appreciated. Minimalism encouraged.