diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..d97771288f
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,4 @@
+## Code of Conduct
+
+This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct).
+Please make sure you read it.
diff --git a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
index 10353b97e5..eb45e255f2 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
@@ -100,7 +100,7 @@ fun Project.configureSonatypePublicationIfNecessary(vararg publications: String)
fun MavenPublication.configurePom(projectName: String) {
pom {
name.set(projectName)
- description.set("Dokka is a documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
+ description.set("Dokka is an API documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
url.set("https://github.com/Kotlin/dokka")
licenses {
diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt
index 0e89b3f6b2..59364af93e 100644
--- a/core/src/main/kotlin/pages/ContentNodes.kt
+++ b/core/src/main/kotlin/pages/ContentNodes.kt
@@ -317,9 +317,8 @@ interface Style
interface Kind
/**
- * [ContentKind] represents a grouping of content of one kind. This can be rendered
- * as either a part of a composite page (one tab/block within a class's page, for instance)
- * or as a separate page altogether.
+ * [ContentKind] represents a grouping of content of one kind that can can be rendered
+ * as part of a composite page (one tab/block within a class's page, for instance).
*/
enum class ContentKind : Kind {
diff --git a/docs/src/doc/docs/about/FAQ.md b/docs/src/doc/docs/about/FAQ.md
deleted file mode 100644
index ba4a7acf15..0000000000
--- a/docs/src/doc/docs/about/FAQ.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# FAQ
-If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
diff --git a/docs/src/doc/docs/about/slack_channel.md b/docs/src/doc/docs/about/slack_channel.md
deleted file mode 100644
index 6879dc7de0..0000000000
--- a/docs/src/doc/docs/about/slack_channel.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Slack channel
-
-For more information or help, feel free to ask questions in the [official Kotlin Slack Channel](https://kotlinlang.slack.com)
-
diff --git a/docs/src/doc/docs/community/plugins-list.md b/docs/src/doc/docs/community/plugins-list.md
index 4a65965ed7..ed8993fc5b 100644
--- a/docs/src/doc/docs/community/plugins-list.md
+++ b/docs/src/doc/docs/community/plugins-list.md
@@ -1,18 +1,160 @@
# Dokka community plugins
-Here is a list of plugins created by dokka team or community.
+On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members.
-In order to add your plugin to this list it needs to be:
+If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md)
+or `GitHub`.
- * an open source project - sharing is caring so let others learn and improve your plugin
- * present in any public artefacts repository like bintray
+If you want to learn how to develop plugins for `Dokka`, see
+[Plugin development](../developer_guide/plugin-development/introduction.md) section.
-| Plugin name | Description | Source |
-| :--------- | :--------- | :------------ |
-| [Kotlin as Java](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Display Kotlin code as seen from Java | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)
-| [GFM](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a GFM format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/gfm)
-| [Javadoc](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Javadoc format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc)
-| [Jekyll](https://kotlin.github.io/dokka/1.7.0/user_guide/introduction/#plugins) | Renders documentation in a Jekyll format | [Github](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll)
-| [Mermaid-HTML](https://mermaid-js.github.io/mermaid/#/) | Renders Mermaid graphs for HTML renderer. | [Github](https://github.com/glureau/dokka-mermaid)
+## Output Formats
+### Javadoc (Alpha)
+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
+`Javadoc` documentation generated by `Java`.
+
+`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task.
+
+`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks:
+
+* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module.
+* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together.
+
+`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones.
+
+**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to
+[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see.
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc)
+
+### GFM (Alpha)
+
+`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:
+
+* `dokkaGfm` - generate documentation for a non multi-module project or one specific module.
+* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and
+ generate navigation page/menu for all the modules.
+
+Example:
+
+___
+
+//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm)
+
+#### MyClass
+
+[jvm]
+class [MyClass](#gfm)
+
+KDoc that describes this class
+
+##### Constructors
+
+| | |
+|---|---|
+| [MyClass](#gfm) | [jvm] fun [MyClass](#gfm)() |
+
+##### Functions
+
+| Name | Summary |
+|------------------|---|
+| [function](#gfm) | [jvm] fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html) KDoc comment on top of this function |
+
+##### Properties
+
+| Name | Summary |
+|---|------------------------------------------------------------------------------------------------------------------------------------------------|
+| [property](#gfm) | [jvm] val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html) KDoc comment for a property |
+
+___
+
+**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to
+[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see.
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm)
+
+### Jekyll (Alpha)
+
+`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:
+
+* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module.
+* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and
+ generate navigation page/menu for all the modules.
+
+**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to
+[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see.
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll)
+
+## Extensions
+
+### Mathjax
+
+[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` (ver. 2) with `config=TeX-AMS_SVG`
+to generated `HTML` pages.
+
+Usage example:
+```kotlin
+/**
+ * Some math \(\sqrt{3x-1}+(1+x)^2\)
+ *
+ * @usesMathJax
+ */
+class Foo {}
+```
+
+Which results in:
+
+{ width="400" }
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax)
+
+### Mermaid
+
+[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:
+
+{ width="700" }
+
+For more information and examples, see
+[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub.
+
+### Kotlin as Java
+
+With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures.
+
+For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`.
+
+`Kotlin as Java` plugin is published to maven central as a
+[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin):
+`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.0`.
+
+[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)
diff --git a/docs/src/doc/docs/community/slack.md b/docs/src/doc/docs/community/slack.md
new file mode 100644
index 0000000000..290d4a180e
--- /dev/null
+++ b/docs/src/doc/docs/community/slack.md
@@ -0,0 +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`.
+
+[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
new file mode 100644
index 0000000000..fb11f32a99
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md
@@ -0,0 +1,123 @@
+# Architecture overview
+
+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 an API documentation engine.
+
+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.
+
+For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers
+of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce
+selective changes on a single level.
+
+## Overview of data model
+
+Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files
+(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent
+abstractions have been added to the data model.
+
+Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage.
+
+```mermaid
+flowchart TD
+ Input --> Documentables --> Pages --> Output
+```
+
+* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything
+* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source
+ language. Examples of a `Documentable`: class, function, package, property, etc
+* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of
+ (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
+ * `
` / `
` for `HTML` format
+ * `1.` / `*` for `Markdown` format
+ * `ContentCodeBlock` is mapped as
+ * `` or `
` with some CSS styles in `HTML` format
+ * Text wrapped in triple backticks for `Markdown` format
+
+
+You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the
+model on one particular level without touching everything else.
+
+For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only
+need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded
+methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple
+pages into one, and so on.
+
+For a deeper dive into Dokka's model with more examples and details,
+see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md)
+
+For an overview of existing extension points that let you transform Dokka's models, see
+[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md).
+
+## Overview of extension points
+
+An extension point usually represents some pluggable interface that performs an action during one of the stages of
+generating documentation. An extension is therefore an implementation of that interface which is extending the
+extension point.
+
+You can create extension points, provide your own implementations (extensions) and configure them. All of
+this is possible with Dokka's plugin/extension point API.
+
+Here's a sneak peek of the DSL:
+
+```kotlin
+class MyPlugin : DokkaPlugin() {
+ // create an extension point for other developers
+ val signatureProvider by extensionPoint()
+
+ // provide a default implementation
+ val defaultSignatureProvider by extending {
+ signatureProvider with KotlinSignatureProvider()
+ }
+
+ // register our own extension in base plugin and override its default
+ val dokkaBasePlugin by lazy { plugin() }
+ val multimoduleLocationProvider by extending {
+ (dokkaBasePlugin.locationProviderFactory
+ providing MultimoduleLocationProvider::Factory
+ override dokkaBasePlugin.locationProvider)
+ }
+}
+
+// use a registered extention, pretty much dependency injection
+class MyExtension(val context: DokkaContext) {
+
+ val signatureProvider: SignatureProvider = context.plugin().querySingle { signatureProvider }
+
+ fun doSomething() {
+ signatureProvider.signature(..)
+ }
+}
+
+interface SignatureProvider {
+ fun signature(documentable: Documentable): List
+}
+
+class KotlinSignatureProvider : SignatureProvider {
+ override fun signature(documentable: Documentable): List = listOf()
+}
+```
+
+For a deeper dive into extensions and extension points with more examples and details, see
+[Introduction to Extensions](extension_points/introduction.md).
+
+For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and
+[Base extensions](extension_points/base_extensions.md).
+
+## Historical context
+
+This is a second iteration of Dokka that was built from scratch.
+
+If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks:
+[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles
+and general architecture are the same, although it may be outdated in some areas, so please double-check.
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
new file mode 100644
index 0000000000..5264553d98
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
@@ -0,0 +1,245 @@
+# Documentables Model
+
+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)
+(for `Java`) models. Code-wise, you can have a look at following classes:
+
+* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping
+* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping
+
+Upon creation, it's a collection of trees, each with `DModule` as root.
+
+Take some arbitrary `Kotlin` source code that is located within the same module:
+
+```kotlin
+// Package 1
+class Clazz(val property: String) {
+ fun function(parameter: String) {}
+}
+
+fun topLevelFunction() {}
+
+// Package 2
+enum class Enum { }
+
+val topLevelProperty: String
+```
+
+This would be represented roughly as the following `Documentable` tree:
+
+```mermaid
+flowchart TD
+ DModule --> firstPackage[DPackage]
+ firstPackage --> DClass
+ firstPackage --> toplevelfunction[DFunction]
+ DClass --> DProperty
+ DClass --> DFunction
+ DFunction --> DParameter
+ DModule --> secondPackage[DPackage]
+ secondPackage --> DEnum
+ secondPackage --> secondPackageProperty[DProperty]
+```
+
+At later stages of transformation, all trees are folded into one (by `DocumentableMerger`).
+
+## Documentable
+
+The main building block of documentables model is `Documentable` class. It's the base class for all more specific types
+that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc)
+.
+`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc.
+
+The contents of each documentable normally represent what you would see in source code. For instance, if you open
+`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so
+on.
+`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level
+functions and properties (`Kotlin`-specific).
+
+Here's an example of a documentable:
+
+```kotlin
+data class DClass(
+ val dri: DRI,
+ val name: String,
+ val constructors: List,
+ val functions: List,
+ val properties: List,
+ val classlikes: List,
+ val sources: SourceSetDependent,
+ val visibility: SourceSetDependent,
+ val companion: DObject?,
+ val generics: List,
+ val supertypes: SourceSetDependent>,
+ val documentation: SourceSetDependent,
+ val expectPresentInSet: DokkaSourceSet?,
+ val modifier: SourceSetDependent,
+ val sourceSets: Set,
+ val isExpectActual: Boolean,
+ val extra: PropertyContainer = PropertyContainer.empty()
+) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors,
+ WithGenerics, WithSupertypes, WithExtraProperties
+```
+
+___
+
+There are three non-documentable classes that important for this model:
+
+* `DRI`
+* `SourceSetDependent`
+* `ExtraProperty`.
+
+### DRI
+
+`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
+to `Foo`'s `Documentable` object.
+
+#### Example
+
+For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`:
+
+```kotlin
+package kotlinx.coroutines
+
+import ...
+
+public abstract class MainCoroutineDispatcher : CoroutineDispatcher() {
+
+ override fun limitedParallelism(parallelism: Int): CoroutineDispatcher {
+ ...
+ }
+}
+```
+
+If we were to re-create the DRI of this function in code, it would look something like this:
+
+```kotlin
+DRI(
+ packageName = "kotlinx.coroutines",
+ classNames = "MainCoroutineDispatcher",
+ callable = Callable(
+ name = "limitedParallelism",
+ receiver = null,
+ params = listOf(
+ TypeConstructor(
+ fullyQualifiedName = "kotlin.Int",
+ params = emptyList()
+ )
+ )
+ ),
+ target = PointingToDeclaration,
+ extra = null
+)
+```
+
+If you format it as `String`, it would look like this:
+
+```
+kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/
+```
+
+### SourceSetDependent
+
+`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either
+`expect` or `actual` modifier) with particular
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets).
+
+This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ
+from that declared in `expect`, or code comments written for `expect` might be different from what's written
+for `actual`.
+
+Under the hood, it's a `typealias` to a `Map`:
+
+```kotlin
+typealias SourceSetDependent = Map
+```
+
+### ExtraProperty
+
+`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly
+recommended to use extras to provide any additional information when creating custom Dokka plugins.
+
+This element is a bit more complex, so you can read more about how to use it
+[in a separate section](extra.md).
+
+___
+
+## Documentation model
+
+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.
+
+It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and
+`bold` 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 = emptyList(),
+ override val params: Map = emptyMap()
+) : DocTag()
+
+data class H2(
+ override val children: List = emptyList(),
+ override val params: Map = emptyMap()
+) : DocTag()
+
+data class Strikethrough(
+ override val children: List = emptyList(),
+ override val params: Map = emptyMap()
+) : DocTag()
+
+data class Strong(
+ override val children: List = emptyList(),
+ override val params: Map = emptyMap()
+) : DocTag()
+
+data class CodeBlock(
+ override val children: List = emptyList(),
+ override val params: Map = emptyMap()
+) : Code()
+
+```
+
+### TagWrapper
+
+`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.
+
+```kotlin
+/**
+ * @author **Ben Affleck*
+ * @return nothing, except _sometimes_ it may throw an [Error]
+ */
+fun foo() {}
+```
+
+### DocumentationNode
+
+`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually
+used like this:
+
+```kotlin
+data class DFunction(
+ ...
+ val documentation: SourceSetDependent,
+ ...
+)
+```
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
new file mode 100644
index 0000000000..0abbc70e0d
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
@@ -0,0 +1,99 @@
+# Extra
+
+## Introduction
+
+`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model)
+models.
+
+Source code for `ExtraProperty`:
+
+```kotlin
+interface ExtraProperty {
+ interface Key {
+ fun mergeStrategyFor(left: T, right: T): MergeStrategy = MergeStrategy.Fail {
+ throw NotImplementedError("Property merging for $this is not implemented")
+ }
+ }
+
+ val key: Key
+}
+```
+
+To declare a new extra, you need to implement `ExtraProperty` interface. It is advised to use following pattern
+when declaring new extras:
+
+```kotlin
+data class CustomExtra(
+ [any data relevant to your extra],
+ [any data relevant to your extra]
+): ExtraProperty {
+ override val key: CustomExtra.Key = CustomExtra
+ companion object : CustomExtra.Key
+}
+```
+
+Merge strategy (`mergeStrategyFor` method) for extras is invoked during
+[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each
+have their own `Extra` of the same type.
+
+## PropertyContainer
+
+All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer` class instances.
+
+```kotlin
+data class DFunction(
+ ...
+ override val extra: PropertyContainer = PropertyContainer.empty()
+ ...
+) : WithExtraProperties
+```
+
+`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner.
+
+The `C` generic class parameter limits the type of properties that can be stored in the container - it must
+match generic `C` class parameter from `ExtraProperty` interface. This allows creating extra properties
+which can only be stored in a specific `Documentable`.
+
+## Usage example
+
+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 {
+ override val key: ExtraProperty.Key = CustomExtra
+ companion object: ExtraProperty.Key
+}
+
+fun DFunction.withCustomExtraProperty(data: String): DFunction {
+ return this.copy(
+ extra = extra + CustomExtra(data)
+ )
+}
+
+fun DFunction.getCustomExtraPropertyValue(): String? {
+ return this.extra[CustomExtra]?.customExtraValue
+}
+```
+
+___
+
+You can also use extras as markers, without storing any data in them:
+
+```kotlin
+
+object MarkerExtra : ExtraProperty, ExtraProperty.Key {
+ override val key: ExtraProperty.Key = this
+}
+
+fun Documentable.markIfFunction(): Documentable {
+ return when(this) {
+ is DFunction -> this.copy(extra = extra + MarkerExtra)
+ else -> this
+ }
+}
+
+fun WithExtraProperties.isMarked(): Boolean {
+ return this.extra[MarkerExtra] != null
+}
+```
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
new file mode 100644
index 0000000000..54ded235cb
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
@@ -0,0 +1,140 @@
+# Page / Content Model
+
+Even though `Page` and `Content` models reside on the same level (under `Page`), it's easier to view it as two different
+models altogether, even though `Content` is only used in conjunction with and inside `Page` model.
+
+## Page
+
+Page model represents the structure of documentation pages to be generated. During rendering, each page
+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`.
+
+Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`,
+`ClasslikePage`, `MemberPage` (properties, functions), etc.
+
+The Page Model is a tree structure, with `RootPageNode` at the root.
+
+Here's an example of how an arbitrary `Page` tree might look like for a module with 3 packages, one of which contains
+a top level function, top level property and a class, inside which there's a function and a property:
+
+```mermaid
+flowchart TD
+ RootPageNode --> firstPackage[PackagePageNode]
+ RootPageNode --> secondPackage[PackagePageNode]
+ RootPageNode --> thirdPackage[PackagePageNode]
+ firstPackage --> firstPackageFirstMember[MemberPageNode - Function]
+ firstPackage --> firstPackageSecondMember[MemberPageNode - Property]
+ firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class]
+ firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function]
+ firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property]
+ secondPackage --> etcOne[...]
+ thirdPackage --> etcTwo[...]
+```
+
+Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it.
+
+## Content Model
+
+Content model describes how the actual `Page` content is presented. The important thing to understand is that it's
+also output-format independent and is universal.
+
+Content model is essentially a set of building blocks that you can put together to represent some content.
+Have a look at subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, `ContentCodeBlock`,
+`ContentHeader` and so on. You can group content together with `ContentGroup` - for instance,
+to wrap all children with some style.
+
+```kotlin
+// real example of composing content using `DocumentableContentBuilder` DSL
+orderedList {
+ item {
+ text("This list contains a nested table:")
+ table {
+ header {
+ text("Col1")
+ text("Col2")
+ }
+ row {
+ text("Text1")
+ text("Text2")
+ }
+ }
+ }
+ item {
+ group(styles = setOf(TextStyle.Bold)) {
+ text("This is bald")
+ text("This is also bald")
+ }
+ }
+}
+```
+
+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 `text`, 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 a specific `ContentNode`.
+
+```kotlin
+data class DCI(val dri: Set, val kind: Kind)
+```
+
+All references to other nodes (other than direct ownership) are described using `DCI`.
+
+### ContentKind
+
+`ContentKind` represents a grouping of content of one kind that can can be rendered as part of a composite
+page (one tab/block within a class's page, for instance).
+
+For instance, on the same page that describes a class you can have multiple sections (== `ContentKind`).
+One to describe functions, one to describe properties, another one to describe constructors and so on.
+
+### Styles
+
+Each `ContentNode` has `styles` property in case you want to incidate to `Renderer` that this content needs to be
+displayed in a certain way.
+
+```kotlin
+group(styles = setOf(TextStyle.Paragraph)) {
+ text("Text1", styles = setOf(TextStyle.Bold))
+ text("Text2", styles = setOf(TextStyle.Italic))
+}
+```
+
+It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance,
+`HtmlRenderer` might render `TextStyle.Bold` as `text`, but `CommonmarkRenderer` might render it as `**text**`.
+
+There's a number of existing styles that you can use, most of them are supported by `HtmlRenderer` out of the box:
+
+```kotlin
+// for code highlighting
+enum class TokenStyle : Style {
+ Keyword, Punctuation, Function, Operator, Annotation,
+ Number, String, Boolean, Constant, Builtin, ...
+}
+
+enum class TextStyle : Style {
+ Bold, Italic, Strong, Strikethrough, Paragraph, ...
+}
+
+enum class ContentStyle : Style {
+ TabbedContent, RunnableSample, Wrapped, Indented, ...
+}
+```
+
+### Extra
+
+`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly
+recommended to use extras to provide any additional information when creating custom Dokka plugins.
+
+All `ExtraProperty` elements from `Documentable` model are propagated into `Content` model and are available
+for `Renderer`.
+
+This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md).
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
new file mode 100644
index 0000000000..16a52fab42
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
@@ -0,0 +1,13 @@
+# Base extensions
+
+`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 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.
+
+You can learn how to add/use/override/configure extensions and extension points in
+[Introduction to Extensions](introduction.md), all the information is applicable to `DokkaBase` plugin as well.
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
new file mode 100644
index 0000000000..381a95962f
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
@@ -0,0 +1,151 @@
+# Core extension points
+
+Core extension points represent the main stages of generating documentation.
+
+These extension points are plugin and output format independent, meaning it's the very core functionality and as
+low-level as can get. For higher-level extension functions that can be used in different output formats, have a look at
+[Base extensions](base_extensions.md) defined in `DokkaBase`.
+
+You can find all core extensions in `CoreExtensions` class:
+```kotlin
+object CoreExtensions {
+ val preGenerationCheck by coreExtensionPoint()
+ val generation by coreExtensionPoint()
+ val sourceToDocumentableTranslator by coreExtensionPoint()
+ val documentableMerger by coreExtensionPoint()
+ val documentableTransformer by coreExtensionPoint()
+ val documentableToPageTranslator by coreExtensionPoint()
+ val pageTransformer by coreExtensionPoint()
+ val renderer by coreExtensionPoint()
+ val postActions by coreExtensionPoint()
+}
+```
+
+On this page we'll go over each extension point individually.
+
+## PreGenerationChecker
+
+`PreGenerationChecker` can be used to run some checks and constraints.
+
+For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses
+`PreGenerationChecker` to check for multi-platform
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and fails if it finds any.
+
+## Generation
+
+`Generation` is responsible for generating documentation as a whole, utilizing other extension points where applicable.
+
+There are two implementations at the moment:
+
+* `AllModulesPageGeneration` - generates multimodule documentation, for instance when `dokkaHtmlMultiModule` task is
+ invoked.
+* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked
+
+### AllModulesPageGeneration
+
+`AllModulesPageGeneration` utilizes output generated by `SingleModuleGeneration`. Under the hood it just collects all
+pages generated for individual modules and assembles everything together, creating navigation pages between the
+modules and so on.
+
+### SingleModuleGeneration stages
+
+When developing a feature or a plugin, it's more convenient to think that you are generating documentation for single
+module projects, believing that Dokka will somehow take care of the rest in multimodule environment.
+
+`SingleModuleGeneration` is at heart of generating documentation and utilizes other core extension points, so
+it's worth going over its stages.
+
+Below you can see the transformations of [Dokka's models](../architecture_overview.md#overview-of-data-model) and
+extension interfaces responsible for each one. Notice how `Documentables` and `Pages` are transformed multiple times.
+
+```mermaid
+flowchart TD
+ Input -- SourceToDocumentableTranslator --> doc1[Documentables]
+ subgraph documentables [ ]
+ doc1 -- PreMergeDocumentableTransformer --> doc2[Documentables]
+ doc2 -- DocumentableMerger --> doc3[Documentables]
+ doc3 -- DocumentableTransformer --> doc4[Documentables]
+ end
+ doc4 -- DocumentableToPageTranslator --> page1[Pages]
+ subgraph ide2 [ ]
+ page1 -- PageTransformer --> page2[Pages]
+ end
+ page2 -- Renderer --> Output
+```
+
+#### SourceToDocumentableTranslator
+
+`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 the [Documentable](../data_model/documentables.md) model.
+
+For reference, see
+
+* `DefaultDescriptorToDocumentableTranslator` for `Kotlin` sources translation
+* `DefaultPsiToDocumentableTranslator` for `Java` sources translation
+
+#### PreMergeDocumentableTransformer
+
+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 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](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged.
+
+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 overridden. The rest is taken care of.
+
+#### DocumentableMerger
+
+`DocumentableMerger` merges all `DModule` instances into one. Only one extension is expected of this type.
+
+#### DocumentableTransformer
+
+`DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source
+sets.
+
+Notable example is `InheritorsExtractorTransformer`, it extracts inherited classes data across
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and creates an inheritance
+map.
+
+#### DocumentableToPageTranslator
+
+`DocumentableToPageTranslator` is responsible for creating pages and their content. See
+[Page/Content model](../data_model/page_content.md) section for more information and examples.
+
+Different output formats can either use the same page structure or define their own in case it needs to be different.
+
+Only a single extension of this type is expected to be registered.
+
+#### PageTransformer
+
+`PageTransformer` is useful if you need to add/remove/modify generated pages or their content.
+
+Plugins like `mathjax` can add `.js` scripts to pages using this extension point.
+
+If you want all overloaded functions to be rendered on the same page (instead of separate ones),
+you can also use `PageTransformer` to delete excessive pages and combine them into a new single one.
+
+#### Renderer
+
+`Renderer` - defines rules on what to do with pages and their content, which files to create and how to display
+it properly.
+
+Output format implementations should use `Renderer` extension point. Notable examples are `HtmlRenderer`
+and `CommonmarkRenderer`.
+
+## PostAction
+
+`PostAction` is useful for when you want to run some actions after the documentation has been generated - for instance
+if you want to move some files around.
+
+[Versioning plugin](../../../user_guide/plugins/versioning-plugin.md) utilizes `PostAction` in order to move
+generated documentation to versioned folders.
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
new file mode 100644
index 0000000000..877d14e967
--- /dev/null
+++ b/docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md
@@ -0,0 +1,163 @@
+# 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.
+
+## Declaring extension points
+
+If you are writing a plugin, you can create your own extension point that other developers (or you) can use later on
+in some other part of code.
+
+```kotlin
+class MyPlugin : DokkaPlugin() {
+ val sampleExtensionPoint by extensionPoint()
+}
+
+interface SampleExtensionPointInterface {
+ fun doSomething(input: Input): List