diff --git a/gst-libs/gst/vaapi/gstvaapitypes.h b/gst-libs/gst/vaapi/gstvaapitypes.h
index cf486a4153..b958e75a15 100644
--- a/gst-libs/gst/vaapi/gstvaapitypes.h
+++ b/gst-libs/gst/vaapi/gstvaapitypes.h
@@ -57,11 +57,10 @@ typedef gsize GstVaapiID;
  *
  * Can be used together with #GST_VAAPI_ID_ARGS to properly output an
  * integer value in a printf()-style text message.
- * <informalexample>
- * <programlisting>
+ *
+ * ``` C
  * printf("id: %" GST_VAAPI_ID_FORMAT "\n", GST_VAAPI_ID_ARGS(id));
- * </programlisting>
- * </informalexample>
+ * ```
  */
 #define GST_VAAPI_ID_FORMAT "p"
 
diff --git a/gst/vaapi/gstvaapidecodebin.c b/gst/vaapi/gstvaapidecodebin.c
index f807223b90..4f0dd52fa5 100644
--- a/gst/vaapi/gstvaapidecodebin.c
+++ b/gst/vaapi/gstvaapidecodebin.c
@@ -33,12 +33,11 @@
  * It offers the functionality of GstVaapiDecoder and the many options
  * of #GstVaapiPostproc.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/big_buck_bunny.mov ! qtdemux ! h264parse ! vaapidecodebin ! vaapisink
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapidecodedoc.c b/gst/vaapi/gstvaapidecodedoc.c
index aafe9fa66d..f8dd837f62 100644
--- a/gst/vaapi/gstvaapidecodedoc.c
+++ b/gst/vaapi/gstvaapidecodedoc.c
@@ -37,12 +37,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/image.jpeg ! jpegparse ! vaapijpegdec ! imagefreeze ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -63,12 +62,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/sample.mpg ! mpegpsdemux ! vaapimpeg2dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -89,12 +87,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/sample.mpeg4 ! mpeg4videoparse ! vaapimpeg4dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -115,12 +112,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/sample.h263 ! h263parse ! vaapih263dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -141,12 +137,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/big_buck_bunny.mov ! qtdemux ! h264parse ! vaapih264dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -167,12 +162,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=./sample.bin ! h265parse ! vaapih265dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -193,12 +187,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=~/elephants_dream.wmv  ! asfdemux ! vaapivc1dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -219,12 +212,11 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 filesrc location=./sample.webm ! matroskademux ! vaapivp8dec ! vaapisink
  * ]|
- * </refsect2>
  */
 
 /**
@@ -245,10 +237,8 @@
  * processed by other elements, but the performance would be rather
  * bad.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
  * |[
  * gst-launch-1.0 filesrc location=./sample.vp9.webm ! ivfparse ! vaapivp9dec ! vaapisink
  * ]|
- * </refsect2>
  */
diff --git a/gst/vaapi/gstvaapiencode_h264.c b/gst/vaapi/gstvaapiencode_h264.c
index ed19c409a3..e861255c8c 100644
--- a/gst/vaapi/gstvaapiencode_h264.c
+++ b/gst/vaapi/gstvaapiencode_h264.c
@@ -52,12 +52,11 @@
  * you can set #GstVaapiEncodeH264:tune, if your backend supports it,
  * for low-power mode or high compression.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapih264enc ! h264parse ! mp4mux ! filesink location=test.mp4
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_h264_fei.c b/gst/vaapi/gstvaapiencode_h264_fei.c
index caf68b3899..6e4d51a88a 100644
--- a/gst/vaapi/gstvaapiencode_h264_fei.c
+++ b/gst/vaapi/gstvaapiencode_h264_fei.c
@@ -27,12 +27,11 @@
  *
  * Encodes raw video streams into H.264 bitstreams.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 !  vaapih264feienc fei-mode=ENC_PAK ! filesink location=test.264
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_h265.c b/gst/vaapi/gstvaapiencode_h265.c
index 268f404d64..fa03fdcefc 100644
--- a/gst/vaapi/gstvaapiencode_h265.c
+++ b/gst/vaapi/gstvaapiencode_h265.c
@@ -26,12 +26,11 @@
  *
  * Encodes raw video streams into HEVC bitstreams.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapih265enc ! h265parse ! matroskamux ! filesink location=test.mkv
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_jpeg.c b/gst/vaapi/gstvaapiencode_jpeg.c
index 81da4c738b..4d644fa9d2 100644
--- a/gst/vaapi/gstvaapiencode_jpeg.c
+++ b/gst/vaapi/gstvaapiencode_jpeg.c
@@ -26,12 +26,11 @@
  *
  * Encodes raw images into JPEG images.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=1 ! timeoverlay ! vaapijpegenc ! filesink location=test.jpg
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_mpeg2.c b/gst/vaapi/gstvaapiencode_mpeg2.c
index 3622bbea59..f43ac3f9fe 100644
--- a/gst/vaapi/gstvaapiencode_mpeg2.c
+++ b/gst/vaapi/gstvaapiencode_mpeg2.c
@@ -27,12 +27,11 @@
  *
  * Encodes raw video streams into MPEG2 bitstreams.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapimpeg2enc ! matroskamux ! filesink location=test.mkv
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_vp8.c b/gst/vaapi/gstvaapiencode_vp8.c
index fcaffbb812..5fee607b0a 100644
--- a/gst/vaapi/gstvaapiencode_vp8.c
+++ b/gst/vaapi/gstvaapiencode_vp8.c
@@ -26,12 +26,11 @@
  *
  * Encodes raw video streams into VP8 bitstreams.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapivp8enc ! matroskamux ! filesink location=test.mkv
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapiencode_vp9.c b/gst/vaapi/gstvaapiencode_vp9.c
index 7a69384ec4..22c40a6443 100644
--- a/gst/vaapi/gstvaapiencode_vp9.c
+++ b/gst/vaapi/gstvaapiencode_vp9.c
@@ -26,12 +26,11 @@
  *
  * Encodes raw video streams into VP9 bitstreams.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapivp9enc ! matroskamux ! filesink location=test.mkv
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapipostproc.c b/gst/vaapi/gstvaapipostproc.c
index d89804abb4..d6dc762a02 100644
--- a/gst/vaapi/gstvaapipostproc.c
+++ b/gst/vaapi/gstvaapipostproc.c
@@ -27,12 +27,11 @@
  * vaapipostproc consists in various postprocessing algorithms to be
  * applied to VA surfaces.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 videotestsrc ! vaapipostproc ! video/x-raw width=1920, height=1080 ! vaapisink
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapisink.c b/gst/vaapi/gstvaapisink.c
index e820f2c5b2..92f953475c 100644
--- a/gst/vaapi/gstvaapisink.c
+++ b/gst/vaapi/gstvaapisink.c
@@ -30,12 +30,11 @@
  * display using the Video Acceleration (VA) API. The element will
  * create its own internal window and render into it.
  *
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
+ *
  * |[
  * gst-launch-1.0 videotestsrc ! vaapisink
  * ]|
- * </refsect2>
  */
 
 #include "gstcompat.h"