diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..24a8e87
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
index 77f0382..42935bf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,5 @@ coverage.txt
 coverage.html
 coverage.xml
 dist
+
+third_party
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c4effa2..58a9996 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -40,3 +40,10 @@ repos:
             args: [run, fmt]
             language: system
             pass_filenames: false
+          - id: autotoc
+            name: generate toc
+            entry: mise
+            args: [run, autotoc]
+            language: system
+            files: ^README\.md$
+            pass_filenames: false
diff --git a/README.md b/README.md
index 86b4a3f..8464c55 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,42 @@
-# Teastraw
+<img src="./assets/teastraw.png" width="90" style="margin-right:10px" align=left alt="teastraw logo">
+<H1>Teastraw</H1><br>
+
+
+![License](https://img.shields.io/github/license/fiffeek/teastraw.svg?style=flat)
+![Code Size](https://img.shields.io/github/languages/code-size/fiffeek/teastraw.svg?style=flat)
+![Go Version](https://img.shields.io/github/go-mod/go-version/fiffeek/teastraw?style=flat)
+![Go Report Card](https://goreportcard.com/badge/github.com/fiffeek/teastraw)
+![Build](https://img.shields.io/github/actions/workflow/status/fiffeek/teastraw/test.yaml?branch=main&style=flat)
+
 
 A Go package for end-to-end testing of Terminal User Interface (TUI) applications.
 
+## Table of Contents
+
+<!--ts-->
+* [Teastraw](#teastraw)
+   * [Table of Contents](#table-of-contents)
+   * [Overview](#overview)
+   * [Installation](#installation)
+   * [Quick Start](#quick-start)
+   * [Key Features](#key-features)
+      * [Screen Validation](#screen-validation)
+      * [Waiting for Conditions](#waiting-for-conditions)
+      * [Input Simulation](#input-simulation)
+      * [Graceful Shutdown](#graceful-shutdown)
+   * [Configuration Options](#configuration-options)
+      * [Terminal Size](#terminal-size)
+      * [Exit Sequences](#exit-sequences)
+   * [Testing Patterns](#testing-patterns)
+      * [Golden File Testing](#golden-file-testing)
+      * [Time-based Testing](#time-based-testing)
+   * [Examples](#examples)
+   * [Comparison to Teatest](#comparison-to-teatest)
+   * [Contributing](#contributing)
+   * [License](#license)
+   * [Credits](#credits)
+<!--te-->
+
 ## Overview
 
 `Teastraw` provides a test runner that can interact with TUI applications by:
@@ -171,8 +206,8 @@ runner, err := exp.NewTestRunner(
     exp.WithCommand(cmd),
 )
 
-[A few common ones](https://github.com/fiffeek/teastraw/blob/main/pkg/exp/const.go#L3) are passed by default, you can also refer to them in your code.
 ```
+[A few common ones](https://github.com/fiffeek/teastraw/blob/main/pkg/exp/const.go#L3) are passed by default, you can also refer to them in your code.
 
 ## Testing Patterns
 
diff --git a/assets/teastraw.png b/assets/teastraw.png
new file mode 100644
index 0000000..3a916f6
--- /dev/null
+++ b/assets/teastraw.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:174f234b153b639141a829018e7162164b0b55e0a63122b9e7839e040667057e
+size 1463844
diff --git a/mise.toml b/mise.toml
index 9ba5b99..ceec5c4 100644
--- a/mise.toml
+++ b/mise.toml
@@ -38,6 +38,21 @@ description = "Install golang dependencies"
 run = "go mod download all"
 sources = ["go.mod", "go.sum"]
 
+[tasks."install:autotoc"]
+description = "Install auto toc script"
+run = [
+  "mkdir -p ./third_party",
+  "wget -q https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc",
+  "chmod 755 gh-md-toc",
+  "mv gh-md-toc ./third_party/",
+  "./third_party/gh-md-toc --help >/dev/null 2>&1",
+]
+
+[tasks."autotoc"]
+description = "Generate TOC for README.md"
+run = ["./scripts/autotoc"]
+sources = ["README.md"]
+
 [tasks."install"]
 depends = ["install:*"]
 run = ["python -m pre_commit install --install-hooks"]
diff --git a/scripts/autotoc b/scripts/autotoc
new file mode 100755
index 0000000..304200d
--- /dev/null
+++ b/scripts/autotoc
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+README="README.md"
+
+"${SCRIPT_DIR}/../third_party/gh-md-toc" --no-backup --hide-footer "$README"