diff --git a/docs/src/doc/docs/community/plugins-list.md b/docs/src/doc/docs/community/plugins-list.md
index dc88ade3cb..8a01a6845d 100644
--- a/docs/src/doc/docs/community/plugins-list.md
+++ b/docs/src/doc/docs/community/plugins-list.md
@@ -1,6 +1,12 @@
 # Dokka community plugins
 
-TODO add a link on how to apply plugins
+On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members.
+
+If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md)
+or `GitHub`.
+
+If you want to learn how to develop plugins for `Dokka`, see 
+[Plugin development](../developer_guide/plugin-development/introduction.md) section.
 
 ## Output Formats
 
@@ -8,7 +14,7 @@ TODO add a link on how to apply plugins
 
 Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part
 a lookalike, so you may experience problems if you try to use it with a tool that expects native
-`Javadocs` generated by `Java`.
+`Javadoc` documentation generated by `Java`.
 
 `Javadoc` plugin does not support multiplatform projects and does not have a multi-module task.
 
@@ -26,7 +32,7 @@ a lookalike, so you may experience problems if you try to use it with a tool tha
 
 ### GFM (Alpha)
 
-`GFM` plugins adds an ability to generate documentation in `GitHub flavoured Markdown` format. Supports both
+`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both
 multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it
 right away with one of the following tasks:
 
@@ -40,26 +46,26 @@ ___
 
 //[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm)
 
-# MyClass
+#### MyClass
 
 [jvm]
 class [MyClass](#gfm)
 
 KDoc that describes this class
 
-## Constructors
+##### Constructors
 
 | | |
 |---|---|
 | [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() |
 
-## Functions
+##### Functions
 
 | Name             | Summary |
 |------------------|---|
 | [function](#gfm) | [jvm]<br>fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment on top of this function |
 
-## Properties
+##### Properties
 
 | Name | Summary                                                                                                                                        |
 |---|------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -74,7 +80,7 @@ ___
 
 ### Jekyll (Alpha)
 
-`Jekyll` plugins adds an ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both
+`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both
 multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it
 right away with one of the following tasks:
 
@@ -91,18 +97,18 @@ right away with one of the following tasks:
 
 ### Mathjax
 
-[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `Dokka` `MathJax` plugin
-adds an ability to render mathematics from source code comments.
+[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin
+adds the ability to render mathematics from source code comments.
 
-If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` 2.7.6 with `config=TeX-AMS_SVG`
+If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG`
 to generated `HTML` pages.
 
 Usage example:
 ```kotlin
 /**
- * @usesMathJax
- *
  * Some math \(\sqrt{3x-1}+(1+x)^2\)
+ * 
+ * @usesMathJax
  */
 class Foo {}
 ```
@@ -118,6 +124,26 @@ Which results in:
 [Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. 
 `Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation.
 
+Usage example:
+```kotlin
+/**
+ * See the graph for more details:
+ * \```mermaid
+ * graph LR
+ *   A[Christmas] -->|Get money| B(Go shopping)
+ *   B --> C{Let me think}
+ *   C -->|One| D[Laptop]
+ *   C -->|Two| E[iPhone]
+ *   C -->|Three| F[fa:fa-car Car]
+ * \```
+ */
+class CompositeSubscription
+```
+
+Which results in:
+
+![Mermaid demo](../images/mermaid_demo.png){ width="700" }
+
 For more information and examples, see 
 [Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub.
 
diff --git a/docs/src/doc/docs/community/slack.md b/docs/src/doc/docs/community/slack.md
index 98716523f9..290d4a180e 100644
--- a/docs/src/doc/docs/community/slack.md
+++ b/docs/src/doc/docs/community/slack.md
@@ -1,7 +1,7 @@
 # Slack channel
 
-Dokka has a dedicated `#dokka` channel in the Kotlin Community Slack, where you can ask questions and chat 
-about using, customizing or contributing to Dokka. 
+`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat 
+about using, customizing or contributing to `Dokka`. 
 
 [Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
 to get an invite or [connect directly](https://kotlinlang.slack.com). 
diff --git a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md
index 17bd7568b8..54ca9d331d 100644
--- a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md
+++ b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md
@@ -1,21 +1,23 @@
 # Architecture overview
 
-Normally, you would think that a tool like Dokka simply parses some programming language sources and generates
+Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates
 `HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and
 shortest way to implement a documentation engine.
 
-However, it was clear that Dokka may need to generate documentation from various sources (not only `Kotlin`), that users
+However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users
 might request additional output formats (like `Markdown`), that users might need additional features like supporting
-custom KDoc tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside
-Dokka itself if all solutions were hardcoded.
+custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside
+`Dokka` itself if all solutions were hardcoded.
 
-For this reason, Dokka was built from the ground up to be extensible and customizable. You can think of the general
-flow of generating documentation with Dokka as mapping one intermediate representation / abstraction into another.
-You, as a Dokka developer or a plugin writer, can use extension points and introduce selective changes to the
-model on any level without touching everything else.
+For this reason, `Dokka` was built from the ground up to be extensible and customizable. You can think of the general
+flow of generating documentation with `Dokka` as mapping one intermediate representation / abstraction into another.
+You, as a `Dokka` developer or a plugin writer, can use extension points and introduce selective changes to the
+model on one particular level without touching the rest.
 
 ## Overview of data model
 
+Below you can find the general flow and transformation of Dokka's models.
+
 ```mermaid
 flowchart TD
     Input --> Documentables --> Documentables --> Pages --> Pages --> Output
@@ -25,9 +27,13 @@ flowchart TD
 * `Documentables` - unified data model that represents any parsed sources as a tree. 
   Examples: class/function/package/property
 * `Pages` - universal model that represents pages (e.g a function/property page) and its content
-  (lists, text, code blocks) that the users needs to see
-* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of content to
+  (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand
+  with so-called Content Model.
+* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to
   some human-readable and visual representation. For instance:
+    * `PageNode` is mapped as 
+        * `.html` file for `HTML` format
+        * `.md` file for `Markdown` format
     * `ContentList` is mapped as
         * `<li>` / `<ul>` for `HTML` format
         * `1.` / `*` for `Markdown` format
@@ -63,7 +69,7 @@ class MyPlugin : DokkaPlugin() {
         signatureProvider with KotlinSignatureProvider()
     }
 
-    // register our own extension in another plugin and override its default
+    // register our own extension in base plugin and override its default
     val dokkaBasePlugin by lazy { plugin<DokkaBase>() }
     val multimoduleLocationProvider by extending {
         (dokkaBasePlugin.locationProviderFactory
@@ -74,6 +80,7 @@ class MyPlugin : DokkaPlugin() {
 
 // use a registered extention, pretty much dependency injection
 class MyExtension(val context: DokkaContext) {
+    
     val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider }
 
     fun doSomething() {
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
index 5fd8db5be5..6c66f9be98 100644
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
@@ -1,7 +1,7 @@
-# Documentables
+# Documentables Model
 
-Documentables represent data that is parsed from some sources. Think of this data model as of something that could be
-seen or produced by a compiler frontend, and it's not far off from the truth.
+Documentables represent data that is parsed from sources. Think of this data model as of something that could be
+seen or produced by a compiler frontend, it's not far off from the truth.
 
 By default, documentables are parsed from `Descriptor` (for `Kotlin`)
 and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html)
@@ -67,7 +67,7 @@ data class DClass(
 
 ___
 
-There are three non-documentable classes important for this model:
+There are three non-documentable classes that important for this model:
 
 * `DRI`
 * `SourceSetDependent`
@@ -75,7 +75,7 @@ There are three non-documentable classes important for this model:
 
 ### DRI
 
-`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies specific `Documentable`.
+`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`.
 All references and relations between documentables (other than direct ownership) are described using `DRI`.
 
 For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference
@@ -83,7 +83,7 @@ to `Foo`'s `Documentable` object.
 
 #### Example
 
-For an example of how a `DRI` can look like, let's look at `limitedParallelism` function from `kotlinx.coroutines`:
+For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`:
 
 ```kotlin
 package kotlinx.coroutines
@@ -152,22 +152,54 @@ ___
 
 ## Documentation model
 
-Documentation model is used along `Documentable` model to store data obtained by parsing
+Documentation model is used alongside Documentables to store data obtained by parsing
 code comments (such as `KDoc`/`Javadoc`).
 
 ### DocTag
 
-`DocTag` describes a specific documentation syntax element, universal across source languages. For instance,
-DocTag `B` is the same for `**bold**` in `Kotlin` and `<b>bold</b>` in `Java`.
+`DocTag` describes a specific documentation syntax element.
 
-However, some `DocTag` elements are specific to a certain language, there are many such example for `Java`
-because it allows HTML tags inside `Javadoc` comments, some of which are not possible with `Markdown`.
+It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and
+`<b>bold</b>` in `Java`.
+
+However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java`
+because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`.
 
 `DocTag` elements can be deeply nested with other `DocTag` children elements.
 
+Examples:
+
+```kotlin
+data class H1(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class H2(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class Strikethrough(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class Strong(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class CodeBlock(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : Code()
+
+```
+
 ### TagWrapper
 
-`TagWrapper` described a whole comment description or a specific comment tag.
+`TagWrapper` describes the whole comment description or a specific comment tag.
 For example: `@see` / `@author` / `@return`.
 
 Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children.
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
index 69025d7957..5dda7ef394 100644
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
@@ -2,7 +2,10 @@
 
 ## Introduction
 
-`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md) models.
+`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model)
+models.
+
+Source code for `ExtraProperty`:
 
 ```kotlin
 interface ExtraProperty<in C : Any> {
@@ -21,6 +24,7 @@ when declaring new extras:
 
 ```kotlin
 data class CustomExtra(
+    [any data relevant to your extra], 
     [any data relevant to your extra] 
 ): ExtraProperty<Documentable> {
     override val key: CustomExtra.Key<Documentable, *> = CustomExtra
@@ -51,7 +55,7 @@ which can only be stored in a specific `Documentable`.
 
 ## Usage example
 
-In following example we will create `DFunction`-only property, store it and then retrieve its value:
+In following example we will create a `DFunction`-only property, store it and then retrieve its value:
 
 ```kotlin
 data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> {
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
index a07e90658e..86fe49acab 100644
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
@@ -9,7 +9,7 @@ Page model represents the structure of documentation pages to be generated. Duri
 is processed separately, so one page corresponds to exactly one output file.
 
 Page model is independent of the final output format, in other words it's universal. Which extension the pages
-should be created as (`.html`, `.md`, etc) and how is up to the `Renderer` part.
+should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`.
 
 Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`,
 `ClasslikePage`, `MemberPage` (properties, functions), etc.
@@ -28,7 +28,7 @@ flowchart TD
     firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property]
 ```
 
-Almost all pages are `ContentPage` - it's the type of `Page` that has `Content` on it.
+Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it.
 
 ## Content Model
 
@@ -44,7 +44,7 @@ to wrap all children with some style.
 // real example of composing content using `DocumentableContentBuilder` DSL
 orderedList {
     item {
-        text("The following table is nested in a list:")
+        text("This list contains a nested table:")
         table {
             header {
                 text("Col1")
@@ -61,16 +61,17 @@ orderedList {
 }
 ```
 
-It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance,
-`HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might render it using
-backticks.
+It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. 
+
+For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might 
+render it using backticks.
 
 ___
 
 ### DCI
 
 Each node is identified by unique `DCI`, which stands for _Dokka Content Identifier_. `DCI` aggregates `DRI`s of all
-`Documentables` that make up specific `ContentNode`.
+`Documentables` that make up a specific `ContentNode`.
 
 ```kotlin
 data class DCI(val dri: Set<DRI>, val kind: Kind)
diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
index 32bb578a1f..16a52fab42 100644
--- a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
@@ -1,10 +1,11 @@
 # Base extensions
 
-`DokkaBase` is a base plugin which defines a number of default implementations for `CoreExtensions` as well as declares
-its own, more high-level, extension points to be used from other plugins and output formats.
+`DokkaBase` class is a base plugin which defines a number of default implementations for `CoreExtensions` as well as
+declares its own, more high-level extension points to be used from other plugins and output formats.
 
 It's very convenient to use extension points and defaults defined in `DokkaBase` if you have an idea for a simple
-plugin that only needs to provide a few extensions or change a single place and have everything else be the default.
+plugin that only needs to provide a few extensions or change a single extension point and have everything else be the
+default.
 
 `DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others.
 
diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
index 28f1564d6d..e540c79662 100644
--- a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
@@ -21,11 +21,13 @@ object CoreExtensions {
 }
 ```
 
+On this page we'll go over each extension point individually.
+
 ## PreGenerationChecker
 
-`PreGenerationChecker` can be used to run some check to check for constraints. 
+`PreGenerationChecker` can be used to run some checks and constraints. 
 
-For instance, `Javadoc` plugin does not support generating documentation for multi-platform project, so it uses
+For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses
 `PreGenerationChecker` to check for multi-platform source sets and fails if it finds any.
 
 ## Generation
@@ -70,7 +72,7 @@ flowchart TD
 `SourceToDocumentableTranslator` translates sources into documentable model. 
 
 `Kotlin` and `Java` sources are supported by default, but you can analyze any language as long as you can map
-it to `Documentables` model.
+it to the [Documentable](../data_model/documentables.md) model.
 
 For reference, see
 
@@ -81,17 +83,18 @@ For reference, see
 
 This extension point actually comes from `DokkaBase` and is not a core extension point, but it's used in
 `SingleModuleGeneration` nonetheless. If you are implementing your own plugin without relying on `DokkaBase`,
-you can either have something similar or rely on [DocumentableTransformer](#documentabletransformer).
+you can either introduce a similar extension point or rely on [DocumentableTransformer](#documentabletransformer) which
+will be discussed below.
 
 `PreMergeDocumentableTransformer` allows applying any transformation to 
 [Documentables model](../data_model/documentables.md) before different source sets are merged. 
 
-Useful if you want to filter/map existing documentables. For instance, if you want to only include members annotated
-as `@PublicAPI`, you most likely need an implementation of `PreMergeDocumentableTransformer`.
+Useful if you want to filter/map existing documentables. For instance, if you want to exclude members annotated with
+`@Internal`, you most likely need an implementation of `PreMergeDocumentableTransformer`.
 
 For simple condition-based filtering of documentables consider extending 
 `SuppressedByConditionDocumentableFilterTransformer` - it implements `PreMergeDocumentableTransformer` and only
-requires one function to be overriden and takes care of the rest.
+requires one function to be overridden. The rest is taken care of.
 
 #### DocumentableMerger
 
diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md
index 1751ecefce..28fd0019cf 100644
--- a/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md
@@ -1,4 +1,4 @@
-# Overview
+# Introduction to extension points
 
 In this section you can learn how to create new extension points, how to use and configure existing ones and
 how to query for extensions when generating documentation.
@@ -29,7 +29,7 @@ See [Extending from extension points](#extending-from-extension-points) for exam
 
 You can use extension points to provide your own implementation(s) in order to customize plugin's behaviour.
 
-If you want to provide a default implementation of your plugin's extension point, you can do that within the same class:
+You can do that within the same class as the extension point itself:
 
 ```kotlin
 open class MyPlugin : DokkaPlugin() {
@@ -47,6 +47,8 @@ class DefaultSampleExtension : SampleExtensionPointInterface {
 }
 ```
 
+___
+
 If you want to extend someone else's plugin (including `DokkaBase`), you can use plugin querying API to do that.
 In the example below we will extend `MyPlugin` that was created above with our own implementation of
 `SampleExtensionPointInterface`.
@@ -81,7 +83,7 @@ You can read more on what you can do with `context` in [Obtaining extension inst
 
 ### Override
 
-By extending an extension point, you are registering an additional extension. This behaviour is expected for some
+By extending an extension point, you are registering an _additional_ extension. This behaviour is expected for some
 extension points, for instance documentable transformers, since all transformers do their own transformations and all
 of them will be invoked before proceeding.
 
diff --git a/docs/src/doc/docs/developer_guide/introduction.md b/docs/src/doc/docs/developer_guide/introduction.md
index a15a0f2540..feb601fe90 100644
--- a/docs/src/doc/docs/developer_guide/introduction.md
+++ b/docs/src/doc/docs/developer_guide/introduction.md
@@ -4,13 +4,13 @@ The purpose of `Developer guides` section is to get you acquainted with Dokka's
 your own plugins or contributing features and fixes to Dokka itself.
 
 If you want to start hacking on Dokka right away, the only thing you need to be aware of is the
-[general workflow](workflow.md), it will teach you how to build, debug and test Dokka.
+[general workflow](workflow.md), it will teach you how to build, debug and test Dokka locally.
 
 If you want to get into plugin development quick, see
 [Introduction to plugin development](plugin-development/introduction.md).
 
 If you have time to spare and want to know more about Dokka's internals, its architecture and capabilities, follow
-[Architecture overview](architecture/architecture_overview.md) and subsequent sections.
+[Architecture overview](architecture/architecture_overview.md) and subsequent sections inside `Internals`.
 
 Having read through all the developer guides, you'll have a pretty good unrestanding of Dokka and how to develop
 for it. 
diff --git a/docs/src/doc/docs/developer_guide/plugin-development/introduction.md b/docs/src/doc/docs/developer_guide/plugin-development/introduction.md
index d1314fcfad..fbfb32ac7a 100644
--- a/docs/src/doc/docs/developer_guide/plugin-development/introduction.md
+++ b/docs/src/doc/docs/developer_guide/plugin-development/introduction.md
@@ -1,15 +1,15 @@
-# Plugin Development
+# Introduction to plugin development
 
 In order to have an easier time developing plugins, it's a good idea to go through
-[Dokka's internals](../architecture/architecture_overview.md) to learn more about
-[extensions](../architecture/extension_points/introduction.md) and
-[data model](../architecture/data_model/documentables.md).
+[Dokka's internals](../architecture/architecture_overview.md) first to learn more about its
+[data model](../architecture/data_model/documentables.md) and 
+[extensions](../architecture/extension_points/introduction.md).
 
 ## Setup
 
 ### Template 
 
-The easiest way to start is to use a convenient [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template).
+The easiest way to start is to use the convenient [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template).
 It has pre-configured dependencies, publishing and signing of your artifacts.
 
 ### Manual
@@ -38,7 +38,7 @@ All instances are automatically loaded during Dokka setup using `java.util.Servi
 
 Dokka provides a set of entry points for which you can create your own implementations. If you are not sure which
 extension point to use, have a look at [core extensions](../architecture/extension_points/core_extensions.md) and
-[base extensions](../architecture/extension_points/base_extensions.md) - it might give you a general direction.
+[base extensions](../architecture/extension_points/base_extensions.md).
 
 You can learn how to declare extension points and use extensions in
 [Introduction to Extension points](../architecture/extension_points/introduction.md).
@@ -48,8 +48,8 @@ versions of Dokka.
 
 ## Example
 
-You can follow [a simple plugin guide](simple-plugin-guide.md) which covers creation of a simple plugin: hide members
-annotated with `@Internal` annotation, i.e exclude them from generated documentation.
+You can follow the [sample plugin tutorial](sample-plugin-tutorial.md) which covers creation of a simple plugin: hide members
+annotated with your own `@Internal` annotation, that is exclude these members from generated documentation.
 
 Fore more practical examples, have a look at sources of [community plugins](../../community/plugins-list.md).
 
diff --git a/docs/src/doc/docs/developer_guide/plugin-development/simple-plugin-guide.md b/docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
similarity index 77%
rename from docs/src/doc/docs/developer_guide/plugin-development/simple-plugin-guide.md
rename to docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
index 098b11c861..f99344017c 100644
--- a/docs/src/doc/docs/developer_guide/plugin-development/simple-plugin-guide.md
+++ b/docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
@@ -1,9 +1,9 @@
-# Simple plugin guide
+# Sample plugin tutorial
 
 We'll go over creating a simple plugin that covers a very common use case: generate documentation for everything except 
 for members annotated with a custom `@Internal` annotation - they should be hidden.
 
-Plugin functionality will be tested on a simple project with the following code:
+The plugin will be tested with the following code:
 
 ```kotlin
 package org.jetbrains.dokka.internal.test
@@ -18,18 +18,18 @@ fun shouldBeExcludedFromDocumentation() {}
 
 Expected behavior: function `shouldBeExcludedFromDocumentation` should not be visible in generated documentation.
 
-Full plugin code can be found in Dokka's examples under 
+Full source code of this tutorial can be found in Dokka's examples under 
 [hide-internal-api](https://github.com/Kotlin/dokka/examples/plugin/hide-internal-api).
 
 ## Preparing the project
 
-We'll begin by using [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). Press the
-green `Use this template` button and open this project in an IDE of your choice (IntelliJ IDEA is recommended).
+We'll begin by using [Dokka plugin template](https://github.com/Kotlin/dokka-plugin-template). Press the 
+`Use this template` button and 
+[open this project in IntelliJ IDEA](https://www.jetbrains.com/idea/guide/tutorials/working-with-gradle/opening-a-gradle-project/).
 
-We can start by changing `template` package and renaming the pre-made `MyAwesomeDokkaPlugin` class to something 
-of our own.
+First, let's rename the pre-made `template` package and `MyAwesomeDokkaPlugin` class to something of our own.
 
-For instance, `org.example.dokka.plugin.ExposePublicApiPlugin`:
+For instance, package can be renamed to `org.example.dokka.plugin` and the class to `HideInternalApiPlugin`:
 
 ```kotlin
 package org.example.dokka.plugin
@@ -47,17 +47,20 @@ After you do that, make sure to update the path to this class in
 org.example.dokka.plugin.HideInternalApiPlugin
 ```
 
-At this point you can also change project name in `settings.gradle.kts` and `groupId` in `build.gradle.kts`. 
+At this point you can also change project name in `settings.gradle.kts` (to `hide-internal-api` in our case)
+and `groupId` in `build.gradle.kts`. 
 
 ## Extending Dokka
 
-After preparing the project we can start extending Dokka with our own extension.
+After preparing the project we can begin extending Dokka with our own extension.
 
-Having read through [Core extensions](../architecture/extension_points/core_extensions.md) it's clear that we need
-a `PreMergeDocumentableTransformer` in order to filter out undesired documentables. Moreover, it mentioned a convenient
-abstract transformer `SuppressedByConditionDocumentableFilterTransformer`, so we can begin by implementing it.
+Having read through [Core extensions](../architecture/extension_points/core_extensions.md), it's clear that we need
+a `PreMergeDocumentableTransformer` extension in order to filter out undesired documentables. 
 
-Create a new class, place it next to your plugin and implement the abstract class method. You should end up with this:
+Moreover, the article mentioned a convenient abstract transformer `SuppressedByConditionDocumentableFilterTransformer`
+which is perfect for our use case, so we can try to implement it.
+
+Create a new class, place it next to your plugin and implement the abstract method. You should end up with this:
 
 ```kotlin
 package org.example.dokka.plugin
@@ -70,17 +73,18 @@ import org.jetbrains.dokka.plugability.DokkaPlugin
 class HideInternalApiPlugin : DokkaPlugin() {}
 
 class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+   
     override fun shouldBeSuppressed(d: Documentable): Boolean {
         return false
     }
 }
 ```
 
-Now we somehow need to find all annotations applied to `d: Documentable` and see if our annotation is present. However,
-it's not very clear how to do that. What usually helps is stopping in debugger and having a look at what fields
+Now we somehow need to find all annotations applied to `d: Documentable` and see if our `@Internal` annotation is present.
+However, it's not very clear how to do that. What usually helps is stopping in debugger and having a look at what fields
 and values a given `Documentable` has.
 
-To do that, we'll need to register our extension point first, then we can publish our plugin and set a breakpoint.
+To do that, we'll need to register our extension point first, then we can publish our plugin and set the breakpoint.
 
 Having read through [Introduction to extensions](../architecture/extension_points/introduction.md), we now know
 how to register our extensions:
@@ -93,7 +97,7 @@ class HideInternalApiPlugin : DokkaPlugin() {
 }
 ```
 
-At this point we're ready to debug our plugin locally.
+At this point we're ready to debug our plugin locally, it should already work, but do nothing.
 
 ## Debugging
 
@@ -106,7 +110,7 @@ First, let's begin by publishing our plugin to `mavenLocal()`.
 ./gradlew publishToMavenLocal
 ```
 
-This will publish your plugin under the package, project name and version that you've specified in your
+This will publish your plugin under the groupId, artifactId and version that you've specified in your
 `build.gradle.kts`. In our case it's `org.example:hide-internal-api:1.0-SNAPSHOT`.
 
 Open a debug project of your choosing and add our plugin to dependencies:
@@ -117,7 +121,7 @@ dependencies {
 }
 ```
 
-Next, in that project let's run `dokkaHtml` with debug enabled
+Next, in that project let's run `dokkaHtml` with debug enabled:
 
 ```bash
 ./gradlew clean dokkaHtml -Dorg.gradle.debug=true --no-daemon
@@ -157,11 +161,11 @@ private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean {
 }
 ```
 
-Seems like we're done with writing our plugin and can begin testing it.
+Seems like we're done with writing our plugin and can begin testing it manually.
 
 ## Manual testing
 
-At this point you should be looking a plugin that looks roughly like this:
+At this point, the implementation of your plugin should look roughly like this:
 
 ```kotlin
 package org.example.dokka.plugin
@@ -200,8 +204,8 @@ class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionD
 }
 ```
 
-Bump plugin version in `gradle.build.kts`, publish it to maven local, run `dokkaHtml` and see if it works! It should.
-You should **NOT** be able to see `shouldBeExcludedFromDocumentation` function in generated documentation.
+Bump plugin version in `gradle.build.kts`, publish it to maven local, open the debug project and run `dokkaHtml`. 
+It should work, you should **not** be able to see `shouldBeExcludedFromDocumentation` function in generated documentation.
 
 Manual testing is cool and all, but wouldn't it be better if we could somehow write unit tests for it? Indeed!
 
@@ -210,13 +214,13 @@ Manual testing is cool and all, but wouldn't it be better if we could somehow wr
 You might've noticed that plugin template comes with a pre-made test class. Feel free to move it to another package
 and rename it.
 
-We are mostly interested in a single test case - non-annotated functions should be visible, and annotated ones should
-be hidden.
+We are mostly interested in a single test case - functions annotated with `@Internal` should be hidden, while all other
+public functions should be visible.
 
 Plugin API comes with a set of convenient test utilities that are used to test Dokka itself, so it covers a wide range
 of use cases. When in doubt, see Dokka's tests for reference.
 
-Below you will find a complete unit tests that passes, and the main takeaways below that.
+Below you will find a complete unit test that passes, and the main takeaways below that.
 
 ```kotlin
 package org.example.dokka.plugin
@@ -265,18 +269,21 @@ class HideInternalApiPluginTest : BaseAbstractTest() {
 }
 ```
 
-Note that the package of the test code (inside `testInline` function) is the same as the package that we have
-hardcoded in our plugin. Make sure to change that if you are following along, otherwise it will fail.
+Note that the package of the tested code (inside `testInline` function) is the same as the package that we have
+hardcoded in our plugin. Make sure to change that if you are following along but for your own annotation and package,
+otherwise it will fail.
 
 Things to note and remember:
 
 1. Your test class should extend `BaseAbstractTest`, which contains base utility methods for testing.
-2. You can configure Dokka to your liking, enable some specific settings, configure source sets, etc
+2. You can configure Dokka to your liking, enable some specific settings, configure source sets, etc. All done via
+   `dokkaConfiguration` DSL.
 3. `testInline` function is the main entry point for unit tests
-4. You can pass plugins to be used in tests, notice `pluginOverrides` parameter
+4. You can pass plugins to be used in a test, notice `pluginOverrides` parameter
 5. You can test Dokka on different stages of generating documentation, the main ones being documentables model
    generation, pages generation and output generation. Since we implemented our plugin to work during
-   `PreMergeDocumentableTransformer` stage, we can test it on the same level.
+   `PreMergeDocumentableTransformer` stage, we can test it on the same level (that is
+   `preMergeDocumentablesTransformationStage`).
 6. You will need to write asserts using the model of whatever stage you choose. For documentables transformation stage 
-   it's documentables, for page generation stage you would have pages, and for output you can have `.html` pages
+   it's documentables, for page generation stage you would have pages, and for output you can have `.html` files
    that you will need to parse with JSoup (there are also utilities for that).
diff --git a/docs/src/doc/docs/developer_guide/workflow.md b/docs/src/doc/docs/developer_guide/workflow.md
index ef13ddaaaf..d5c92f8201 100644
--- a/docs/src/doc/docs/developer_guide/workflow.md
+++ b/docs/src/doc/docs/developer_guide/workflow.md
@@ -1,3 +1,5 @@
+# Workflow
+
 Whether you're contributing a feature/fix to Dokka itself or developing a separate plugin, there's 3 things
 you'll be doing:
 
@@ -10,9 +12,6 @@ We'll go over each step individually in this section.
 Examples below will be specific to Gradle and [Gradle’s Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html),
 but you can apply the same principles and run/test/debug with CLI/Maven runners and build configurations if you wish.
 
-If you have any specific questions which are not covered in this section, feel free to reach out to devs out through
-[Slack](../community/slack.md).
-
 ## Building Dokka
 
 Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run
@@ -34,8 +33,8 @@ If you see messages like `API check failed for project ..` during `build` phase,
 changed/added/removed some public API.
 
 If the change was intentional, run `./gradlew apiDump` - it will re-generate `.api` files with signatures,
-and you should be able to `build` Dokka with no errors. Maintainers will review API changes, so please make sure
-it's intentional and rational.
+and you should be able to `build` Dokka with no errors. These updated files need to be committed as well. Maintainers
+will review API changes thoroughly, so please make sure it's intentional and rational.
 
 ## Using/testing locally built Dokka
 
@@ -60,6 +59,8 @@ plugins {
 }
 ```
 
+After completing these steps, you should be able to build documentation using your own version of Dokka.
+
 ## Debugging Dokka
 
 Dokka is essentially a gradle plugin, so you can debug it the same way you would any other gradle plugin. 
diff --git a/docs/src/doc/docs/dokka_colors.css b/docs/src/doc/docs/dokka_colors.css
index 7816457f72..69a2435914 100644
--- a/docs/src/doc/docs/dokka_colors.css
+++ b/docs/src/doc/docs/dokka_colors.css
@@ -1,3 +1,3 @@
 .md-header, .md-tabs {
-    background-color: #bc0fd4;
+    background-color: #27282c
 }
diff --git a/docs/src/doc/docs/images/mermaid_demo.png b/docs/src/doc/docs/images/mermaid_demo.png
new file mode 100644
index 0000000000..0d0e27b605
Binary files /dev/null and b/docs/src/doc/docs/images/mermaid_demo.png differ
diff --git a/docs/src/doc/docs/index.md b/docs/src/doc/docs/index.md
index fe91c62032..15cf534875 100644
--- a/docs/src/doc/docs/index.md
+++ b/docs/src/doc/docs/index.md
@@ -1,24 +1,37 @@
 # Dokka 
 
 `Dokka` is an API documentation engine for `Kotlin` that performs the same function as the `Javadoc` tool for `Java`,
-but more modern and highly pluggable.
+but it's modern and highly pluggable.
 
-Just like `Kotlin` itself, `Dokka` supports mixed-language `Kotlin`/`Java` projects. It understands
+Just like `Kotlin` itself, `Dokka` supports mixed-language projects (`Kotlin`/`Java`). It understands
 [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in `Kotlin` source files as well
 as `Javadoc` comments in `Java` files, and can generate documentation in multiple formats including its
-own `HTML` format, Java's `Javadoc` lookalike and Markdown.
+own `HTML` format, Java's `Javadoc` lookalike and `Markdown`.
 
 Some libraries that use `Dokka` for API reference docs:
 
-* [kotlinx.coroutines](https://kotlin.github.io/kotlinx.coroutines/)
-* [kotlinx.serialization](https://kotlin.github.io/kotlinx.serialization/)
+* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/)
+* [kotlinx.serialization](https://kotlinlang.org/api/kotlinx.serialization/)
 * [Ktor](https://api.ktor.io/)
 * [Spring Framework](https://docs.spring.io/spring-framework/docs/current/kdoc-api/)
 
+___
+
 `Dokka` provides support for the following build systems:
 
 * [Gradle](user_guide/applying/gradle.md) (preffered)
 * [Maven](user_guide/applying/maven.md)
 * [Command line](user_guide/applying/cli.md)
 
-// TODO write about plugins and pluggability
+___
+
+`Dokka` is also very pluggable and comes with convenient plugin and extension point API. 
+
+You can write a plugin to support [mermaid.js](https://mermaid-js.github.io/mermaid/#/) diagrams,
+[mathjax](https://www.mathjax.org/) formulas or even write custom processing of your own tags and annotations.
+
+For more info, see:
+
+* [Sample plugin tutorial](developer_guide/plugin-development/sample-plugin-tutorial.md)
+* [Community plugins](community/plugins-list.md)
+* [Developer guides](developer_guide/introduction.md)
diff --git a/docs/src/doc/mkdocs.yml b/docs/src/doc/mkdocs.yml
index 63943c9544..9d04c2b269 100644
--- a/docs/src/doc/mkdocs.yml
+++ b/docs/src/doc/mkdocs.yml
@@ -1,8 +1,8 @@
 site_name: Dokka documentation
 
 # Meta tags (placed in header)
-site_description: Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java
-site_author: Jetbrains
+site_description: Dokka is a documentation engine for Kotlin, performing the same function as the Javadoc tool for Java
+site_author: JetBrains
 site_url: https://github.com/Kotlin/dokka
 
 # Repository (add link to repository on each page)
@@ -11,7 +11,7 @@ repo_url: https://github.com/Kotlin/dokka
 edit_uri: edit/master/docs/src/doc/docs/
 
 # Copyright (shown at the footer)
-copyright: 'Copyright &copy; 2020 Jetbrains'
+copyright: 'Copyright &copy; 2022 JetBrains'
 
 # Material theme
 theme:
@@ -62,7 +62,7 @@ nav:
       - Community: community/slack.md
       - FAQ: faq.md
   - User guides:
-      - user_guide/introduction.md
+      - User guides: user_guide/introduction.md
       - Applying Dokka:
           - Gradle: user_guide/applying/gradle.md
           - Maven: user_guide/applying/maven.md
@@ -73,7 +73,7 @@ nav:
           - Versioning plugin: user_guide/plugins/versioning-plugin.md
           - Android plugin: user_guide/plugins/android-plugin.md
   - Developer guides:
-      - developer_guide/introduction.md
+      - Developer guides: developer_guide/introduction.md
       - Workflow: developer_guide/workflow.md
       - Internals:
           - Architecture: developer_guide/architecture/architecture_overview.md
@@ -82,12 +82,12 @@ nav:
               -  Page & Content: developer_guide/architecture/data_model/page_content.md
               -  Extra properties: developer_guide/architecture/data_model/extra.md
           - Extension points:
-              - developer_guide/architecture/extension_points/introduction.md
+              - Extension points: developer_guide/architecture/extension_points/introduction.md
               - Core extension points: developer_guide/architecture/extension_points/core_extensions.md
               - Base extensions: developer_guide/architecture/extension_points/base_extensions.md
       - Plugin development:
           - Plugin development: developer_guide/plugin-development/introduction.md
-          - Simple plugin tutorial: developer_guide/plugin-development/simple-plugin-guide.md
+          - Sample plugin tutorial: developer_guide/plugin-development/sample-plugin-tutorial.md
   - Community:
       - Slack: community/slack.md
       - Community plugins: community/plugins-list.md
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
index a7ba81ba99..2ec4fd7c85 100644
--- a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
+++ b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
@@ -12,7 +12,7 @@
         </@template_cmd>
     </div>
     <div>
-        <#-- This can be handled by a versioning plugin -->
+        <#-- This can be handled by the versioning plugin -->
         <@version/>
     </div>
     <div class="pull-right d-flex">
@@ -21,4 +21,4 @@
         <div id="searchBar"></div>
     </div>
 </div>
-</#macro>
\ No newline at end of file
+</#macro>
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
index f897c104dc..7cab45828b 100644
--- a/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
+++ b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
@@ -3,4 +3,4 @@
     <@template_cmd name="pathToRoot">
     <link href="${pathToRoot}images/logo-icon.svg" rel="icon" type="image/svg">
     </@template_cmd>
-</#macro>
\ No newline at end of file
+</#macro>