diff --git a/docs/developer/architecture/code-exploration.asciidoc b/docs/developer/architecture/code-exploration.asciidoc
index 4481dea44795c93..7ca206835ec10ca 100644
--- a/docs/developer/architecture/code-exploration.asciidoc
+++ b/docs/developer/architecture/code-exploration.asciidoc
@@ -58,9 +58,9 @@ The Charts plugin is a way to create easier integration of shared colors, themes
 WARNING: Missing README.
 
 
-- {kib-repo}blob/{branch}/src/plugins/dashboard[dashboard]
+- <<kibana-dashboard-plugin>>
 
-WARNING: Missing README.
+Registers the dashboard application.
 
 
 - {kib-repo}blob/{branch}/src/plugins/data/README.md[data]
@@ -360,9 +360,10 @@ WARNING: Missing README.
 WARNING: Missing README.
 
 
-- {kib-repo}blob/{branch}/x-pack/plugins/embeddable_enhanced[embeddableEnhanced]
+- <<enhanced-embeddables-plugin>>
 
-WARNING: Missing README.
+Enhances Embeddables by registering a custom factory provider. The enhanced factory provider
+adds dynamic actions to every embeddables state, in order to support drilldowns.
 
 
 - {kib-repo}blob/{branch}/x-pack/plugins/encrypted_saved_objects/README.md[encryptedSavedObjects]
@@ -582,3 +583,6 @@ in their infrastructure.
 
 This plugins adopts some conventions in addition to or in place of conventions in Kibana (at the time of the plugin's creation):
 
+
+include::{kibana-root}/src/plugins/dashboard/README.asciidoc[leveloffset=+1]
+include::{kibana-root}/x-pack/plugins/embeddable_enhanced/README.asciidoc[leveloffset=+1]
diff --git a/package.json b/package.json
index 51a41cbbab9ffc3..7bdbd325de873d7 100644
--- a/package.json
+++ b/package.json
@@ -404,6 +404,7 @@
     "@typescript-eslint/parser": "^2.34.0",
     "angular-mocks": "^1.7.9",
     "archiver": "^3.1.1",
+    "asciidoctor": "^2.2.0",
     "axe-core": "^3.4.1",
     "babel-eslint": "^10.0.3",
     "babel-jest": "^25.5.1",
diff --git a/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts b/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts
index 733b9f23a5394bb..801c1b9db2e471c 100644
--- a/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts
+++ b/packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts
@@ -20,6 +20,7 @@
 import Path from 'path';
 import Fs from 'fs';
 
+import Asciidoc from 'asciidoctor';
 import MarkdownIt from 'markdown-it';
 import cheerio from 'cheerio';
 
@@ -31,6 +32,7 @@ export interface Plugin {
   relativeDir?: string;
   relativeReadmePath?: string;
   readmeSnippet?: string;
+  readmeAsciidocAnchor?: string;
 }
 
 export type Plugins = Plugin[];
@@ -38,14 +40,35 @@ export type Plugins = Plugin[];
 const getReadmeName = (directory: string) =>
   Fs.readdirSync(directory).find((name) => name.toLowerCase() === 'readme.md');
 
+const getReadmeAsciidocName = (directory: string) =>
+  Fs.readdirSync(directory).find((name) => name.toLowerCase() === 'readme.asciidoc');
+
 export const discoverPlugins = (pluginsRootDir: string): Plugins =>
   simpleKibanaPlatformPluginDiscovery([pluginsRootDir], []).map(
     ({ directory, manifest: { id } }): Plugin => {
       const readmeName = getReadmeName(directory);
+      const readmeAsciidocName = getReadmeAsciidocName(directory);
 
       let relativeReadmePath: string | undefined;
       let readmeSnippet: string | undefined;
-      if (readmeName) {
+      let readmeAsciidocAnchor: string | undefined;
+
+      if (readmeAsciidocName) {
+        const readmePath = Path.resolve(directory, readmeAsciidocName);
+        relativeReadmePath = Path.relative(REPO_ROOT, readmePath);
+
+        const asciidoc = Asciidoc().loadFile(relativeReadmePath);
+
+        const parsed = asciidoc.getContent();
+        const $ = cheerio.load(parsed);
+
+        const firstParagraph = $('p')[0];
+        if (firstParagraph) {
+          readmeSnippet = $(firstParagraph).text();
+        }
+
+        readmeAsciidocAnchor = $('h2')[0].attribs.id;
+      } else if (readmeName) {
         const readmePath = Path.resolve(directory, readmeName);
         relativeReadmePath = Path.relative(REPO_ROOT, readmePath);
 
@@ -64,6 +87,7 @@ export const discoverPlugins = (pluginsRootDir: string): Plugins =>
         relativeReadmePath,
         relativeDir: relativeReadmePath || Path.relative(REPO_ROOT, directory),
         readmeSnippet,
+        readmeAsciidocAnchor,
       };
     }
   );
diff --git a/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts b/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts
index f0f799862e24e72..1bd568a4df80768 100644
--- a/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts
+++ b/packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts
@@ -24,11 +24,18 @@ import normalizePath from 'normalize-path';
 import { REPO_ROOT } from '../repo_root';
 import { Plugins } from './discover_plugins';
 
-function* printPlugins(plugins: Plugins) {
+function* printPlugins(plugins: Plugins, includes: string[]) {
   for (const plugin of plugins) {
     const path = plugin.relativeReadmePath || plugin.relativeDir;
     yield '';
-    yield `- {kib-repo}blob/{branch}/${path}[${plugin.id}]`;
+
+    if (plugin.readmeAsciidocAnchor) {
+      yield `- <<${plugin.readmeAsciidocAnchor}>>`;
+
+      includes.push(`include::{kibana-root}/${path}[leveloffset=+1]`);
+    } else {
+      yield `- {kib-repo}blob/{branch}/${path}[${plugin.id}]`;
+    }
 
     if (!plugin.relativeReadmePath || plugin.readmeSnippet) {
       yield '';
@@ -39,6 +46,8 @@ function* printPlugins(plugins: Plugins) {
 }
 
 export function generatePluginList(ossPlugins: Plugins, xpackPlugins: Plugins) {
+  const includes: string[] = [];
+
   return `////
 
 NOTE:
@@ -75,10 +84,12 @@ To that aim, we strive to:
 
 [discrete]
 ==== src/plugins
-${Array.from(printPlugins(ossPlugins)).join('\n')}
+${Array.from(printPlugins(ossPlugins, includes)).join('\n')}
 
 [discrete]
 ==== x-pack/plugins
-${Array.from(printPlugins(xpackPlugins)).join('\n')}
+${Array.from(printPlugins(xpackPlugins, includes)).join('\n')}
+
+${Array.from(includes).join('\n')}
 `;
 }
diff --git a/yarn.lock b/yarn.lock
index 60d073330b35d7f..e4dd8bb90a431b4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2,6 +2,21 @@
 # yarn lockfile v1
 
 
+"@asciidoctor/cli@3.4.0":
+  version "3.4.0"
+  resolved "https://registry.yarnpkg.com/@asciidoctor/cli/-/cli-3.4.0.tgz#586e9133f3367c7b3236631197f4b621890d9227"
+  integrity sha512-jOtxA0I6zB+6z+GGwm9+xhlmGTqCTkFPE902L6fauFlE6v7LxjhLYNxvjDVyn0zMrFLybvoSRcAnM3DcticNoQ==
+  dependencies:
+    yargs "15.3.1"
+
+"@asciidoctor/core@2.2.0":
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/@asciidoctor/core/-/core-2.2.0.tgz#cae722e32666bf3c38365afe7d05f2f433b165fd"
+  integrity sha512-WN/mFuU4SeWaDqpGvRwAf+Tq2T8NQkVVpZ3Ne1/ZRxDKElzFkqq8bGbmxSMWmMVzC+H9ZO1YxxbOjhWEiNvpOA==
+  dependencies:
+    asciidoctor-opal-runtime "0.3.0"
+    unxhr "1.0.1"
+
 "@babel/cli@^7.10.1":
   version "7.10.1"
   resolved "https://registry.yarnpkg.com/@babel/cli/-/cli-7.10.1.tgz#b6e5cd43a17b8f639442ab027976408ebe6d79a0"
@@ -7218,6 +7233,22 @@ asap@^2.0.0, asap@~2.0.3:
   resolved "https://registry.yarnpkg.com/asap/-/asap-2.0.6.tgz#e50347611d7e690943208bbdafebcbc2fb866d46"
   integrity sha1-5QNHYR1+aQlDIIu9r+vLwvuGbUY=
 
+asciidoctor-opal-runtime@0.3.0:
+  version "0.3.0"
+  resolved "https://registry.yarnpkg.com/asciidoctor-opal-runtime/-/asciidoctor-opal-runtime-0.3.0.tgz#df327a870ddd3cd5eb0e162d64ed4dcdd3fe3fee"
+  integrity sha512-YapVwl2qbbs6sIe1dvAlMpBzQksFVTSa2HOduOKFNhZlE9bNmn+moDgGVvjWPbzMPo/g8gItyTHfWB2u7bQxag==
+  dependencies:
+    glob "7.1.3"
+    unxhr "1.0.1"
+
+asciidoctor@^2.2.0:
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/asciidoctor/-/asciidoctor-2.2.0.tgz#880f0dfe349d7dcc8b819ebc691bf1fd36d47bbe"
+  integrity sha512-w5oBMYPaA5RP/Qlv6XQzWE7kSf8d9sLMRBItcU+nn7E/FF9yGLUd1p/dzqWiu600KyNHBpp8Ml/VTaGjUm6LrQ==
+  dependencies:
+    "@asciidoctor/cli" "3.4.0"
+    "@asciidoctor/core" "2.2.0"
+
 asn1.js@^4.0.0:
   version "4.10.1"
   resolved "https://registry.yarnpkg.com/asn1.js/-/asn1.js-4.10.1.tgz#b9c2bf5805f1e64aadeed6df3a2bfafb5a73f5a0"
@@ -31000,6 +31031,11 @@ untildify@^3.0.3:
   resolved "https://registry.yarnpkg.com/untildify/-/untildify-3.0.3.tgz#1e7b42b140bcfd922b22e70ca1265bfe3634c7c9"
   integrity sha512-iSk/J8efr8uPT/Z4eSUywnqyrQU7DSdMfdqK4iWEaUVVmcP5JcnpRqmVMwcwcnmI1ATFNgC5V90u09tBynNFKA==
 
+unxhr@1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/unxhr/-/unxhr-1.0.1.tgz#92200322d66c728993de771f9e01eeb21f41bc7b"
+  integrity sha512-MAhukhVHyaLGDjyDYhy8gVjWJyhTECCdNsLwlMoGFoNJ3o79fpQhtQuzmAE4IxCMDwraF4cW8ZjpAV0m9CRQbg==
+
 unzip-response@^1.0.0:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/unzip-response/-/unzip-response-1.0.2.tgz#b984f0877fc0a89c2c773cc1ef7b5b232b5b06fe"
@@ -32962,6 +32998,23 @@ yargs@13.3.2, yargs@^13.2.2, yargs@^13.3.0:
     y18n "^4.0.0"
     yargs-parser "^13.1.2"
 
+yargs@15.3.1, yargs@^15.0.2, yargs@^15.1.0, yargs@^15.3.1, yargs@~15.3.1:
+  version "15.3.1"
+  resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.3.1.tgz#9505b472763963e54afe60148ad27a330818e98b"
+  integrity sha512-92O1HWEjw27sBfgmXiixJWT5hRBp2eobqXicLtPBIDBhYB+1HpwZlXmbW2luivBJHBzki+7VyCLRtAkScbTBQA==
+  dependencies:
+    cliui "^6.0.0"
+    decamelize "^1.2.0"
+    find-up "^4.1.0"
+    get-caller-file "^2.0.1"
+    require-directory "^2.1.1"
+    require-main-filename "^2.0.0"
+    set-blocking "^2.0.0"
+    string-width "^4.2.0"
+    which-module "^2.0.0"
+    y18n "^4.0.0"
+    yargs-parser "^18.1.1"
+
 yargs@4.8.1:
   version "4.8.1"
   resolved "https://registry.yarnpkg.com/yargs/-/yargs-4.8.1.tgz#c0c42924ca4aaa6b0e6da1739dfb216439f9ddc0"
@@ -32982,23 +33035,6 @@ yargs@4.8.1:
     y18n "^3.2.1"
     yargs-parser "^2.4.1"
 
-yargs@^15.0.2, yargs@^15.1.0, yargs@^15.3.1, yargs@~15.3.1:
-  version "15.3.1"
-  resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.3.1.tgz#9505b472763963e54afe60148ad27a330818e98b"
-  integrity sha512-92O1HWEjw27sBfgmXiixJWT5hRBp2eobqXicLtPBIDBhYB+1HpwZlXmbW2luivBJHBzki+7VyCLRtAkScbTBQA==
-  dependencies:
-    cliui "^6.0.0"
-    decamelize "^1.2.0"
-    find-up "^4.1.0"
-    get-caller-file "^2.0.1"
-    require-directory "^2.1.1"
-    require-main-filename "^2.0.0"
-    set-blocking "^2.0.0"
-    string-width "^4.2.0"
-    which-module "^2.0.0"
-    y18n "^4.0.0"
-    yargs-parser "^18.1.1"
-
 yargs@^15.4.0:
   version "15.4.1"
   resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.4.1.tgz#0d87a16de01aee9d8bec2bfbf74f67851730f4f8"