diff --git a/README.md b/README.md
index 01d4b656..478f7e18 100644
--- a/README.md
+++ b/README.md
@@ -32,14 +32,14 @@ I pronounce jq /‘dʒei’kju:/ so I usually pronounce fq /‘ef’kju:/.
 
 ### Supported formats
 
-[./formats_list.jq]: sh-start
+[./formats_list.sh]: sh-start
 
 aac_frame,
 adts,
 adts_frame,
 apev2,
 ar,
-asn1_ber,
+[asn1_ber](doc/formats.md#asn1_ber),
 av1_ccr,
 av1_frame,
 av1_obu,
@@ -50,12 +50,12 @@ avc_nalu,
 avc_pps,
 avc_sei,
 avc_sps,
-avro_ocf,
+[avro_ocf](doc/formats.md#avro_ocf),
 bencode,
 bsd_loopback_frame,
-bson,
+[bson](doc/formats.md#bson),
 bzip2,
-cbor,
+[cbor](doc/formats.md#cbor),
 dns,
 dns_tcp,
 elf,
@@ -81,24 +81,24 @@ id3v2,
 ipv4_packet,
 jpeg,
 json,
-matroska,
+[matroska](doc/formats.md#matroska),
 mp3,
 mp3_frame,
-mp4,
+[mp4](doc/formats.md#mp4),
 mpeg_asc,
 mpeg_es,
 mpeg_pes,
 mpeg_pes_packet,
 mpeg_spu,
 mpeg_ts,
-msgpack,
+[msgpack](doc/formats.md#msgpack),
 ogg,
 ogg_page,
 opus_packet,
 pcap,
 pcapng,
 png,
-protobuf,
+[protobuf](doc/formats.md#protobuf),
 protobuf_widevine,
 pssh_playready,
 raw,
diff --git a/doc/formats.md b/doc/formats.md
index de8706b2..c042c004 100644
--- a/doc/formats.md
+++ b/doc/formats.md
@@ -105,7 +105,7 @@ fq -d mp4 -o force=true file.mp4
 fq -d raw 'mp4({force: true})' file.mp4
 ```
 
-## Format functions
+## Format details
 
 [./formats_collect.sh]: sh-start
 
diff --git a/doc/formats_list.jq b/doc/formats_list.jq
index 199cea1d..a0a9ffc3 100755
--- a/doc/formats_list.jq
+++ b/doc/formats_list.jq
@@ -1,2 +1,7 @@
 #!/usr/bin/env fq -rnf
-[formats[] | "\(.name)"] | join(",\n")
+
+[ (formats | keys[]) as $format
+| if ($doc_formats | indices($format)) != [] then "[\($format)](doc/formats.md#\($format))"
+  else $format
+  end
+] | join(",\n")
diff --git a/doc/formats_list.sh b/doc/formats_list.sh
new file mode 100755
index 00000000..34062d38
--- /dev/null
+++ b/doc/formats_list.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+# what formats has a .md file
+DOC_FORMATS=$(echo $(ls -1 $REPODIR/format/*/*.md | sed "s#$REPODIR/format/.*/\(.*\).md#\1#"))
+./formats_list.jq --arg doc_formats "$DOC_FORMATS"