diff --git a/Makefile b/Makefile
index 0de872e..f03d117 100644
--- a/Makefile
+++ b/Makefile
@@ -90,7 +90,7 @@ else
 BIN := passt pasta qrap
 endif
 
-all: $(BIN) $(MANPAGES)
+all: $(BIN) $(MANPAGES) docs
 
 static: CFLAGS += -static -DGLIBC_NO_STATIC_NSS
 static: clean all
@@ -123,12 +123,14 @@ valgrind: all
 clean:
 	$(RM) $(BIN) *.o seccomp.h pasta.1 \
 		passt.tar passt.tar.gz *.deb *.rpm \
-		passt.pid
+		passt.pid README.plain.md
 
-install: $(BIN) $(MANPAGES)
+install: $(BIN) $(MANPAGES) docs
 	mkdir -p $(DESTDIR)$(prefix)/bin $(DESTDIR)$(prefix)/share/man/man1
 	cp -d $(BIN) $(DESTDIR)$(prefix)/bin
 	cp -d $(MANPAGES) $(DESTDIR)$(prefix)/share/man/man1
+	mkdir -p $(DESTDIR)$(prefix)/share/doc/passt
+	cp -d README.plain.md $(DESTDIR)$(prefix)/share/doc/passt/README.md
 
 uninstall:
 	$(RM) $(BIN:%=$(DESTDIR)$(prefix)/bin/%)
@@ -147,6 +149,28 @@ pkgs: static
 		--description="User-mode networking for VMs and namespaces" \
 		-k --version=g$(shell git rev-parse --short HEAD) passt.tar.gz
 
+# TODO: This hack makes a "plain" Markdown version of README.md that can be
+# reasonably shipped as documentation file, while the current README.md is
+# definitely intended for web browser consumption. It should probably work the
+# other way around: the web version should be obtained by adding HTML and
+# JavaScript portions to a plain Markdown, instead. However, cgit needs to use
+# a file in the git tree. Find a better way around this.
+docs: README.md
+	@(								\
+		skip=0;							\
+		while read l; do					\
+			case $$l in					\
+			"## Demo")	exit 0		;;		\
+			"<!"*)				;;		\
+			"</"*)		skip=1		;;		\
+			"<"*)		skip=2		;;		\
+			esac;						\
+									\
+			[ $$skip -eq 0 ]	&& echo "$$l";		\
+			[ $$skip -eq 1 ]	&& skip=0;		\
+		done < README.md;					\
+	) > README.plain.md
+
 # Checkers currently disabled for clang-tidy:
 # - llvmlibc-restrict-system-libc-headers
 #	TODO: this is Linux-only for the moment, nice to fix eventually
diff --git a/test/distro/opensuse b/test/distro/opensuse
index ad2108f..d77821a 100644
--- a/test/distro/opensuse
+++ b/test/distro/opensuse
@@ -39,7 +39,7 @@ hostb	./passt -P __PIDFILE__ &
 sleep	1
 host	echo
 hout	DNS6 sed -n 's/^nameserver \([^:]*:\)\([^%]*\).*/\1\2/p' /etc/resolv.conf | head -1
-hout	GUEST_FILES ls -1 *.c *.h *.sh passt.1 qrap.1 Makefile | tr '\n' ' '; echo
+hout	GUEST_FILES ls -1 *.c *.h *.sh passt.1 qrap.1 Makefile README.md | tr '\n' ' '; echo
 
 
 test	OpenSUSE Leap 15.1
diff --git a/test/distro/ubuntu b/test/distro/ubuntu
index b9a0446..ec6c819 100644
--- a/test/distro/ubuntu
+++ b/test/distro/ubuntu
@@ -38,7 +38,7 @@ endef
 hostb	./passt -P __PIDFILE__ &
 sleep	1
 host	echo
-hout	GUEST_FILES ls -1 *.c *.h *.sh passt.1 qrap.1 Makefile | tr '\n' ' '; echo
+hout	GUEST_FILES ls -1 *.c *.h *.sh passt.1 qrap.1 Makefile README.md | tr '\n' ' '; echo
 
 
 test	Ubuntu 14.04.5 LTS (Trusty Tahr), amd64
diff --git a/test/prepare-distro-img.sh b/test/prepare-distro-img.sh
index aeb97a0..46bc126 100755
--- a/test/prepare-distro-img.sh
+++ b/test/prepare-distro-img.sh
@@ -1,7 +1,7 @@
 #! /bin/sh -e
 
 IMG="$1"
-PASST_FILES="$(echo ../*.c ../*.h ../*.sh ../*.1 ../Makefile)"
+PASST_FILES="$(echo ../*.c ../*.h ../*.sh ../*.1 ../Makefile ../README.md)"
 
 virt-edit -a $IMG /lib/systemd/system/serial-getty@.service -e 's/ExecStart=.*/ExecStart=\/sbin\/agetty --autologin root -8 --keep-baud 115200,38400,9600 %I $TERM/g'