From f7bd2ce1a5ef194643b078bd11a90fdf9b389c2b Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat.beresnev@jetbrains.com>
Date: Fri, 4 Aug 2023 18:59:28 +0200
Subject: Update Developer Guides (#3088)

---
 .../architecture/architecture_overview.md          | 123 +++++++++
 .../architecture/data_model/documentable_model.md  | 251 +++++++++++++++++
 .../architecture/data_model/extra.md               |  91 +++++++
 .../architecture/data_model/page_content.md        | 144 ++++++++++
 .../architecture/extension_points/base_plugin.md   |  33 +++
 .../extension_points/core_extension_points.md      | 103 +++++++
 .../extension_points/extension_points.md           | 162 +++++++++++
 .../extension_points/generation_implementations.md |  40 +++
 .../doc/docs/developer_guide/community/slack.md    |   7 +
 .../src/doc/docs/developer_guide/introduction.md   |  22 ++
 .../plugin-development/introduction.md             |  73 +++++
 .../plugin-development/sample-plugin-tutorial.md   | 297 +++++++++++++++++++++
 .../src/doc/docs/developer_guide/workflow.md       | 100 +++++++
 docs-developer/src/doc/docs/dokka_colors.css       |   3 +
 docs-developer/src/doc/docs/favicon.svg            |  10 +
 docs-developer/src/doc/docs/index.md               |   9 +
 docs-developer/src/doc/mkdocs.yml                  |  86 ++++++
 17 files changed, 1554 insertions(+)
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/community/slack.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/introduction.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
 create mode 100644 docs-developer/src/doc/docs/developer_guide/workflow.md
 create mode 100644 docs-developer/src/doc/docs/dokka_colors.css
 create mode 100755 docs-developer/src/doc/docs/favicon.svg
 create mode 100644 docs-developer/src/doc/docs/index.md
 create mode 100644 docs-developer/src/doc/mkdocs.yml

(limited to 'docs-developer/src')

diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md
new file mode 100644
index 00000000..d72dda91
--- /dev/null
+++ b/docs-developer/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
+the most straightforward 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](https://mermaid.js.org/) 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 given level.
+
+## Overview of data model
+
+Generating API documentation begins with input source files (`.kt`, `.java`, etc) and ends with some output files
+(`.html`/`.md`, 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`](data_model/documentable_model.md) - 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`](data_model/page_content.md) - 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 the so-called [Content model](data_model/page_content.md#content-model).
+* `Output` - specific output formats like HTML / Markdown / Javadoc and so on. This is a mapping of the pages/content 
+  model to a human-readable and visual representation. For instance:
+    * `PageNode` is mapped as 
+        * `.html` file for the HTML format
+        * `.md` file for the Markdown format
+    * `ContentList` is mapped as
+        * `<li>` / `<ul>` for the HTML format
+        * `1.` / `*` for the Markdown format
+    * `ContentCodeBlock` is mapped as
+        * `<code>` or `<pre>` with some CSS styles in the HTML format
+        * Text wrapped in triple backticks for the 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 altering everything else. 
+
+For instance, if you wanted to make an annotation / function / class invisible in the final documentation, you would only
+need to modify the `Documentables` level by filtering undesirable declarations 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 `Pages` layer 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/documentable_model.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_extension_points.md) and [Base extensions](extension_points/base_plugin.md).
+
+## Overview of extension points
+
+An _extension point_ usually represents a pluggable interface that performs an action during one of the stages of
+generating documentation. An _extension_ is, therefore, an implementation of the 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
+// declare your own plugin
+class MyPlugin : DokkaPlugin() {
+    // create an extension point for developers to use
+    val signatureProvider by extensionPoint<SignatureProvider>()
+
+    // provide a default implementation
+    val defaultSignatureProvider by extending {
+        signatureProvider with KotlinSignatureProvider()
+    }
+
+    // register our own extension in Dokka's Base plugin by overriding its default implementation
+    val dokkaBasePlugin by lazy { plugin<DokkaBase>() }
+    val multimoduleLocationProvider by extending {
+        (dokkaBasePlugin.locationProviderFactory
+                providing MultimoduleLocationProvider::Factory
+                override dokkaBasePlugin.locationProvider)
+    }
+}
+
+class MyExtension(val context: DokkaContext) {
+
+    // use an existing extension
+    val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider }
+
+    fun doSomething() {
+        signatureProvider.signature(..)
+    }
+}
+
+interface SignatureProvider {
+    fun signature(documentable: Documentable): List<ContentNode>
+}
+
+class KotlinSignatureProvider : SignatureProvider {
+    override fun signature(documentable: Documentable): List<ContentNode> = listOf()
+}
+```
+
+For a deeper dive into extensions and extension points, see [Introduction to Extensions](extension_points/extension_points.md).
+
+For an overview of existing extension points, see [Core extension points](extension_points/core_extension_points.md) and
+[Base extensions](extension_points/base_plugin.md).
+
+## Historical context
+
+This is a second iteration of Dokka that was built from scratch.
+
+If you want to learn more about why Dokka was redesigned 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-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md
new file mode 100644
index 00000000..b30780fc
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md
@@ -0,0 +1,251 @@
+# Documentable Model
+
+The Documentable model represents the data that is parsed from some programming language sources. Think of this data as 
+of something that could be seen or produced by a compiler frontend, it's not far off from the truth.
+
+By default, the documentables are created from:
+
+* Descriptors (Kotlin's K1 compiler)
+* Symbols (Kotlin's K2 compiler)
+* [PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) (Java's model). 
+
+Code-wise, you can have a look at following classes:
+
+* `DefaultDescriptorToDocumentableTranslator` - responsible for Kotlin -> `Documentable` mapping
+* `DefaultPsiToDocumentableTranslator` - responsible for Java -> `Documentable` mapping
+
+Upon creation, the documentable model represents 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](../extension_points/core_extension_points.md#documentablemerger).
+
+## Documentable
+
+The main building block of the documentable model is the `Documentable` class. It is the base class for all more specific 
+types. All implementations represent elements of source code with mostly self-explanatory names: `DFunction`, 
+`DPackage`, `DProperty`, and so on.
+
+`DClasslike` is the base class for all class-like documentables, such as `DClass`, `DEnum`, `DAnnotation` and others.
+
+The contents of each documentable normally represent what you would see in the source code. 
+
+For example, if you open
+`DClass`, you should find that it contains references to functions, properties, companion objects, constructors and so
+on. `DEnum` should have references to its 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<DFunction>,
+    val functions: List<DFunction>,
+    val properties: List<DProperty>,
+    val classlikes: List<DClasslike>,
+    val sources: SourceSetDependent<DocumentableSource>,
+    val visibility: SourceSetDependent<Visibility>,
+    val companion: DObject?,
+    val generics: List<DTypeParameter>,
+    val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>,
+    val documentation: SourceSetDependent<DocumentationNode>,
+    val expectPresentInSet: DokkaSourceSet?,
+    val modifier: SourceSetDependent<Modifier>,
+    val sourceSets: Set<DokkaSourceSet>,
+    val isExpectActual: Boolean,
+    val extra: PropertyContainer<DClass> = PropertyContainer.empty()
+) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors,
+    WithGenerics, WithSupertypes, WithExtraProperties<DClass>
+```
+
+___
+
+There are three non-documentable classes that are 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 the documentables (other than direct ownership) are described using `DRI`.
+
+For example, `DFunction` with a parameter of type `Foo` only has `Foo`'s `DRI`, but 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` modifiers) with particular 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets).
+
+This comes in handy if the `expect` / `actual` declarations differ. For example, 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<T> = Map<DokkaSourceSet, T>
+```
+
+### 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
+
+The Documentation model is used alongside documentables to store data obtained by parsing
+code comments (such as KDocs / Javadocs).
+
+### DocTag
+
+`DocTag` describes a specific documentation syntax element.
+
+It's universal across language sources. For example, the DocTag `B` is the same for `**bold**` in Kotlin and
+`<b>bold</b>` in Java.
+
+However, some DocTag elements are specific to one language. There are many such examples for Java, because it allows 
+HTML tags inside the Javadoc comments, some of which are simply not possible to reproduce with Markdown that KDocs use.
+
+`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` describes the whole comment description or a specific comment tag. For example: `@see` / `@author` / `@return`.
+
+Since each such section may contain formatted text inside 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<DocumentationNode>,
+    ...
+)
+```
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md
new file mode 100644
index 00000000..d7412e36
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md
@@ -0,0 +1,91 @@
+# Extra
+
+## Introduction
+
+`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.
+
+`ExtraProperty` classes are available both in the [Documentable](documentable_model.md) and the [Content](page_content.md#content-model)
+models.
+
+To create a new extra, you need to implement the `ExtraProperty` interface. It is advised to use the following pattern
+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
+    companion object : CustomExtra.Key<Documentable, CustomExtra>
+}
+```
+
+Merge strategy (the `mergeStrategyFor` method) for extras is invoked during the
+[merging](../extension_points/core_extension_points.md#documentablemerger) of the documentables from different 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), when the documentables being
+merged have their own `Extra` of the same type. 
+
+## PropertyContainer
+
+All extras for `ContentNode` and `Documentable` classes are stored in the `PropertyContainer<C : Any>` class instances.
+
+```kotlin
+data class DFunction(
+    ...
+    override val extra: PropertyContainer<DFunction> = PropertyContainer.empty()
+    ...
+) : WithExtraProperties<DFunction>
+```
+
+`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner.
+
+The generic class parameter `C` limits the types of properties that can be stored in the container - it must
+match the generic `C` class parameter from the `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 extra property, store it and then retrieve its value:
+
+```kotlin
+// Extra that is applicable only to DFunction
+data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> {
+    override val key: ExtraProperty.Key<Documentable, *> = CustomExtra
+    companion object: ExtraProperty.Key<Documentable, CustomExtra>
+}
+
+// Storing it inside the documentable
+fun DFunction.withCustomExtraProperty(data: String): DFunction {
+    return this.copy(
+        extra = extra + CustomExtra(data)
+    )
+}
+
+// Retrieveing it from the documentable
+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<Any>, ExtraProperty.Key<Any, MarkerExtra> {
+    override val key: ExtraProperty.Key<Any, *> = this
+}
+
+fun Documentable.markIfFunction(): Documentable {
+    return when(this) {
+        is DFunction -> this.copy(extra = extra + MarkerExtra)
+        else -> this
+    }
+}
+
+fun WithExtraProperties<Documentable>.isMarked(): Boolean {
+    return this.extra[MarkerExtra] != null
+}
+```
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md
new file mode 100644
index 00000000..eb85200f
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md
@@ -0,0 +1,144 @@
+# Page / Content Model
+
+Even though the `Page` and `Content` models reside on the same level (under `Page`), it is easier to view them as two 
+different models altogether, even though `Content` is only used in conjunction with and inside the `Page` model only.
+
+## Page
+
+The 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.
+
+The Page model is independent of the final output format. In other words, it's universal. Which file extension the pages
+should be created as (`.html`, `.md`, etc), and how, is up to the 
+[Renderer](../extension_points/core_extension_points.md#renderer) extension.
+
+Subclasses of the `PageNode` class represent the different kinds of pages, such as `ModulePage`, `PackagePage`,
+`ClasslikePage`, `MemberPage` and so on.
+
+The Page model can be represented as a tree, with `RootPageNode` at the root.
+
+Here's an example of how an arbitrary project's `Page` tree might look like, if the project consists of a module with 
+3 packages, one of which contains a top level function, a 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 a page that has user-visible content on it.
+
+## Content Model
+
+The Content model describes what the pages consist of. It is essentially a set of building blocks that you can put 
+together to represent some content. It is also output-format independent and universal.
+
+For an example, have a look at the subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, 
+`ContentCodeBlock`, `ContentHeader` and so on -- all self-explanatory. You can group chunks of content together with 
+`ContentGroup` - for example, to wrap all children with a style.
+
+```kotlin
+// real example of composing content using the `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 the responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it,
+be it visually (html pages) or otherwise (json).
+
+For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might 
+render it using backticks.
+
+### DCI
+
+Each node is identified by a unique `DCI`, which stands for _Dokka Content Identifier_. 
+
+`DCI` aggregates `DRI`s of all documentables that are used by the given `ContentNode`.
+
+```kotlin
+data class DCI(val dri: Set<DRI>, 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 be rendered as part of a composite
+page, like a single one tab or a block within a class's page.
+
+For example, on the same page that describes a class you can have multiple sections (== `ContentKind`s).
+One to describe functions, one to describe properties, another one to describe the constructors, and so on.
+
+### Styles
+
+Each `ContentNode` has a `styles` property in case you want to indicate to the `Renderer` that this content needs to be
+rendered in a certain way.
+
+```kotlin
+group(styles = setOf(TextStyle.Paragraph)) {
+    text("Text1", styles = setOf(TextStyle.Bold))
+    text("Text2", styles = setOf(TextStyle.Italic))
+}
+```
+
+It is responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it. 
+For instance, `HtmlRenderer` might render `TextStyle.Bold` as `<b>text</b>`, but `CommonmarkRenderer` might render it 
+as `**text**`.
+
+There's a number of existing styles that you can use, most of them are supported by the `HtmlRenderer` extension 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 the `Documentable` model are propagated into the `Content` model, and are available
+in the `Renderer` extensions.
+
+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-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md
new file mode 100644
index 00000000..88579be7
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md
@@ -0,0 +1,33 @@
+# Base plugin
+
+`DokkaBase` represents Dokka's _Base_ plugin, which provides a number of sensible default implementations for 
+`CoreExtensions`, as well as declares its own, more high-level abstractions and extension points to be used from other 
+plugins and output formats.
+
+If you want to develop a simple plugin that only changes a few details, it is very convenient to rely on 
+default implementations and use extension points defined in `DokkaBase`, as it reduces the scope of changes you need to make. 
+
+`DokkaBase` is used extensively in Dokka's own output formats.
+
+You can learn how to add, use, override and configure extensions and extension points in
+[Introduction to Extensions](extension_points.md) - all of that information is applicable to the `DokkaBase` plugin as well.
+
+## Extension points
+
+Some notable extension points defined in Dokka's Base plugin.
+
+### PreMergeDocumentableTransformer
+
+`PreMergeDocumentableTransformer` is very similar to the 
+[DocumentableTransformer](core_extension_points.md#documentabletransformer) core extension point, but it is used during 
+an earlier stage by the [Single module generation](generation_implementations.md#singlemodulegeneration).
+
+This extension point allows you to apply any transformations to the [Documentables model](../data_model/documentable_model.md) 
+before the project's [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged.
+
+It is useful if you want to filter/map existing documentables. For example, 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, whereas the rest is taken care of.
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md
new file mode 100644
index 00000000..fc0088c9
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md
@@ -0,0 +1,103 @@
+# 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 in Dokka. 
+
+For higher-level extension functions that can be used in different output formats, have a look at the 
+[Base plugin](base_plugin.md).
+
+You can find all core extensions in the `CoreExtensions` class:
+
+```kotlin
+object CoreExtensions {
+    val preGenerationCheck by coreExtensionPoint<PreGenerationChecker>()
+    val generation by coreExtensionPoint<Generation>()
+    val sourceToDocumentableTranslator by coreExtensionPoint<SourceToDocumentableTranslator>()
+    val documentableMerger by coreExtensionPoint<DocumentableMerger>()
+    val documentableTransformer by coreExtensionPoint<DocumentableTransformer>()
+    val documentableToPageTranslator by coreExtensionPoint<DocumentableToPageTranslator>()
+    val pageTransformer by coreExtensionPoint<PageTransformer>()
+    val renderer by coreExtensionPoint<Renderer>()
+    val postActions by coreExtensionPoint<PostAction>()
+}
+```
+
+On this page, we'll go over each extension point individually.
+
+## PreGenerationChecker
+
+`PreGenerationChecker` can be used to run some checks and constraints. 
+
+For example, Dokka's 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 higher-level extensions and extension 
+points where applicable.
+
+See [Generation implementations](generation_implementations.md) to learn about the default implementations.
+
+## SourceToDocumentableTranslator
+
+`SourceToDocumentableTranslator` translates any given sources into the Documentable model. 
+
+Kotlin and Java sources are supported by default by the [Base plugin](base_plugin.md), but you can analyze any language 
+as long as you can map it to the [Documentable](../data_model/documentable_model.md) model.
+
+For reference, see
+
+* `DefaultDescriptorToDocumentableTranslator` for Kotlin sources translation
+* `DefaultPsiToDocumentableTranslator` for Java sources translation
+
+## DocumentableMerger
+
+`DocumentableMerger` merges all `DModule` instances into one. Only one extension of this type is expected to be 
+registered.
+
+## DocumentableTransformer
+
+`DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source
+sets.
+
+Notable example is `InheritorsExtractorTransformer`, it extracts inheritance information from 
+[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) page for more information and examples.
+
+Output formats can either use the same page structure or define their own.
+
+Only a single extension of this type is expected to be registered. 
+
+## PageTransformer
+
+`PageTransformer` is useful if you need to add, remove or modify generated pages or their content.
+
+Using this extension point, plugins like `org.jetbrains.dokka:mathjax-pligin` can add `.js` scripts to the HTML pages. 
+
+If you want all overloaded functions to be rendered on the same page instead of separate ones,
+you can use `PageTransformer` to combine the pages into a single one.
+
+## Renderer
+
+`Renderer` - defines the rules on how to render pages and their content: which files to create and how to display
+the content properly. 
+
+Custom output format plugins should use the `Renderer` extension point. Notable examples are `HtmlRenderer`
+and `CommonmarkRenderer`.
+
+## PostAction
+
+`PostAction` can be used for when you want to run some actions after the documentation has been generated - for example,
+if you want to move some files around or log some informational messages.
+
+Dokka's [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) utilizes `PostAction` 
+to move generated documentation to the versioned directories.
+
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md
new file mode 100644
index 00000000..97b02a7d
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md
@@ -0,0 +1,162 @@
+# Extension points
+
+In this section you can learn how to create new extension points, how to configure existing ones, and how to query for 
+registered extensions when generating documentation.
+
+## Declaring extension points
+
+If you are writing a plugin, you can create your own extension points that other developers (or you) can use in other 
+plugins / parts of code.
+
+```kotlin
+class MyPlugin : DokkaPlugin() {
+    val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>()
+}
+
+interface SampleExtensionPointInterface {
+    fun doSomething(input: Input): List<Output>
+}
+
+class Input
+class Output
+```
+
+Usually, you would want to provide some default implementations for your extension points. You can do that
+within the same plugin class by extending an extension point you've just created. See 
+[Extending from extension points](#extending-from-extension-points) for examples.
+
+## Extending from extension points
+
+You can use extension points to provide your own implementations in order to customize a plugin's behaviour.
+
+If you want to provide an implementation for an extension point declared in an external plugin (including `DokkaBase`), 
+you can use plugin querying API to do that. 
+
+The example below shows how to extend `MyPlugin` (that was created above) with an implementation of 
+`SampleExtensionPointInterface`.
+
+```kotlin
+class MyExtendedPlugin : DokkaPlugin() {
+    
+    val mySampleExtensionImplementation by extending {
+        plugin<MyPlugin>().sampleExtensionPoint with SampleExtensionImpl()
+    }
+}
+
+class SampleExtensionImpl : SampleExtensionPointInterface {
+    override fun doSomething(input: Input): List<Output> = listOf()
+}
+```
+
+Alternatively, if it is your own plugin, you can do that within the same class as the extension point itself:
+
+```kotlin
+open class MyPlugin : DokkaPlugin() {
+    val sampleExtensionPoint by extensionPoint<SampleExtensionPointInterface>()
+
+    val defaultSampleExtension by extending {
+        sampleExtensionPoint with DefaultSampleExtension()
+    }
+}
+
+class DefaultSampleExtension : SampleExtensionPointInterface {
+    override fun doSomething(input: Input): List<Output> = listOf()
+}
+```
+
+### Providing
+
+If you need to have access to `DokkaContext` when creating an extension, you can use the `providing` keyword instead. 
+
+```kotlin
+val defaultSampleExtension by extending {
+    sampleExtensionPoint providing { context ->
+        // can use context to query other extensions or get configuration 
+        DefaultSampleExtension() 
+    }
+}
+```
+
+You can read more on what you can do with `context` in [Obtaining extension instance](#obtaining-extension-instance).
+
+### Override
+
+By extending an extension point, you are registering an _additional_ extension. This behaviour is expected by some
+extension points, for example the `Documentable` transformers, because all registered transformer extensions do their own 
+transformations independently and one after the other.
+
+However, a plugin can expect only a single extension to be registered for an extension point. In this case, you can use 
+the `override` keyword to override the existing registered extension:
+
+```kotlin
+class MyExtendedPlugin : DokkaPlugin() {
+    private val myPlugin by lazy { plugin<MyPlugin>() }
+
+    val mySampleExtensionImplementation by extending {
+        (myPlugin.sampleExtensionPoint
+                with SampleExtensionImpl()
+                override myPlugin.defaultSampleExtension)
+    }
+}
+```
+
+This is also useful if you wish to override some extension from `DokkaBase`, to disable or alter it.
+
+### Order
+
+Sometimes, the order in which extensions are invoked matters. This is something you can control as well using the 
+`order` construct:
+
+```kotlin
+class MyExtendedPlugin : DokkaPlugin() {
+    private val myPlugin by lazy { plugin<MyPlugin>() }
+
+    val mySampleExtensionImplementation by extending {
+        myPlugin.sampleExtensionPoint with SampleExtensionImpl() order {
+            before(myPlugin.firstExtension)
+            after(myPlugin.thirdExtension)
+        }
+    }
+}
+```
+
+### Conditional apply
+
+If you want your extension to be registered only if some condition is `true`, you can use the `applyIf` construct:
+
+```kotlin
+class MyExtendedPlugin : DokkaPlugin() {
+    private val myPlugin by lazy { plugin<MyPlugin>() }
+    
+    val mySampleExtensionImplementation by extending {
+        myPlugin.sampleExtensionPoint with SampleExtensionImpl() applyIf {
+            Random.Default.nextBoolean()
+        }
+    }
+}
+```
+
+## Obtaining extension instance
+
+After an extension point has been [created](#declaring-extension-points) and some extensions have been
+[registered](#extending-from-extension-points), you can use `query` and `querySingle` functions to find all or just a 
+single implementation.
+
+```kotlin
+class MyExtension(context: DokkaContext) {
+    // returns all registered extensions for the extension point
+    val allSampleExtensions = context.plugin<MyPlugin>().query { sampleExtensionPoint }
+    
+    // will throw an exception if more than one extension is found.
+    // use if you expect only a single extension to be registered for the extension point
+    val singleSampleExtensions = context.plugin<MyPlugin>().querySingle { sampleExtensionPoint }
+    
+    fun invoke() {
+        allSampleExtensions.forEach { it.doSomething(Input()) }
+        
+        singleSampleExtensions.doSomething(Input())
+    }
+}
+```
+
+In order to have access to `DokkaContext`, you can use the [providing](#providing) keyword when registering an extension.
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md
new file mode 100644
index 00000000..3d857fec
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md
@@ -0,0 +1,40 @@
+# Generation implementations
+
+There are two main implementations of the [Generation](core_extension_points.md#generation) core extension point:
+
+* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked
+* `AllModulesPageGeneration` - generates multi-module documentation, for instance when `dokkaHtmlMultiModule` task is
+  invoked.
+
+## SingleModuleGeneration
+
+`SingleModuleGeneration` is at the heart of generating documentation. It utilizes [core](core_extension_points.md) and 
+[base](base_plugin.md) extensions to build the documentation from start to finish.
+
+Below you can see the flow of how Dokka's [data model](../architecture_overview.md#overview-of-data-model) is transformed
+by various core and base extensions.
+
+```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
+```
+
+You can read about what each stage does in [Core extension points](core_extension_points.md) and 
+[Base plugin](base_plugin.md).
+
+## AllModulesPageGeneration
+
+`AllModulesPageGeneration` utilizes the output generated by `SingleModuleGeneration`. 
+
+Under the hood, it just collects all of the pages generated for individual modules, and assembles it all together, 
+creating navigation links between the modules and so on.
diff --git a/docs-developer/src/doc/docs/developer_guide/community/slack.md b/docs-developer/src/doc/docs/developer_guide/community/slack.md
new file mode 100644
index 00000000..5e57f2ac
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/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-developer/src/doc/docs/developer_guide/introduction.md b/docs-developer/src/doc/docs/developer_guide/introduction.md
new file mode 100644
index 00000000..627afa3a
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/introduction.md
@@ -0,0 +1,22 @@
+# Developer guides
+
+The purpose of the Developer guides documentation is to get you acquainted with Dokka's internals so that you can 
+start developing 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 locally.
+
+[CONTRIBUTING.md](https://github.com/Kotlin/dokka/blob/master/CONTRIBUTING.md) contains information that can be useful 
+if you want to contribute to Dokka.
+
+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 inside `Internals`.
+
+Having read through all the developer guides, you'll have a pretty good understanding of Dokka and how to develop
+for it. 
+
+If you have any questions, feel free to get in touch with maintainers via [Slack](community/slack.md) or 
+[GitHub](https://github.com/kotlin/dokka).
diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md b/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md
new file mode 100644
index 00000000..1008e336
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md
@@ -0,0 +1,73 @@
+# Introduction to plugin development
+
+Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to 
+implement plugins for missing or very specific features that are not provided out of the box.
+
+Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add 
+support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc 
+descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate 
+it with other tools and so much more.
+
+In order to have an easier time developing plugins, it's a good idea to go through
+[Dokka's internals](../architecture/architecture_overview.md) first, to learn more about its
+[data model](../architecture/data_model/documentable_model.md) and 
+[extensions](../architecture/extension_points/extension_points.md).
+
+## Setup
+
+### 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
+
+At a bare minimum, a Dokka plugin requires `dokka-core` as a dependency:
+
+```kotlin
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+
+plugins {
+    kotlin("jvm") version "<kotlin_version>"
+}
+
+dependencies {
+    compileOnly("org.jetbrains.dokka:dokka-core:<dokka_version>")
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions.jvmTarget.set(JvmTarget.JVM_1_8)
+}
+```
+
+In order to load a plugin into Dokka, your class must extend the `DokkaPlugin` class. A fully qualified name of that class
+must be placed in a file named `org.jetbrains.dokka.plugability.DokkaPlugin` under `resources/META-INF/services`. 
+All instances are automatically loaded during Dokka's configuration step using `java.util.ServiceLoader`.
+
+## Extension points 
+
+Dokka provides a set of entry points for which you can create your own implementations. If you are not sure which
+extension points to use, have a look at [core extensions](../architecture/extension_points/core_extension_points.md) and
+[base extensions](../architecture/extension_points/base_plugin.md).
+
+You can learn how to declare extension points and extensions in
+[Introduction to Extension points](../architecture/extension_points/extension_points.md).
+
+In case no suitable extension point exists for your use case, do share the use case with the 
+[maintainers](../community/slack.md) — it might be added in a future version of Dokka.
+
+## Example
+
+You can follow the [sample plugin tutorial](sample-plugin-tutorial.md), which covers the creation of a simple plugin 
+that hides members annotated with your own `@Internal` annotation: that is, it excludes these members from the generated
+documentation.
+
+For more practical examples, have a look at sources of 
+[community plugins](https://kotlinlang.org/docs/dokka-plugins.html#notable-plugins).
+
+## Help
+
+If you have any further questions, feel free to get in touch with Dokka's maintainers via [Slack](../community/slack.md) 
+or [GitHub](https://github.com/kotlin/dokka).
diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
new file mode 100644
index 00000000..55d7001f
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md
@@ -0,0 +1,297 @@
+# 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.
+
+The plugin will be tested with the following code:
+
+```kotlin
+package org.jetbrains.dokka.internal.test
+
+annotation class Internal
+
+fun shouldBeVisible() {}
+
+@Internal
+fun shouldBeExcludedFromDocumentation() {}
+```
+
+Expected behavior: function `shouldBeExcludedFromDocumentation` should not be visible in generated documentation.
+
+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 
+`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/).
+
+First, let's rename the pre-made `template` package and `MyAwesomeDokkaPlugin` class to something of our own.
+
+For instance, package can be renamed to `org.example.dokka.plugin` and the class to `HideInternalApiPlugin`:
+
+```kotlin
+package org.example.dokka.plugin
+
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class HideInternalApiPlugin : DokkaPlugin() {
+
+}
+```
+
+After you do that, make sure to update the path to this class in
+`resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin`:
+```kotlin
+org.example.dokka.plugin.HideInternalApiPlugin
+```
+
+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 begin extending Dokka with our own extension.
+
+Having read through [Core extensions](../architecture/extension_points/core_extension_points.md), it's clear that we need
+a `PreMergeDocumentableTransformer` extension in order to filter out undesired documentables. 
+
+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
+
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.plugability.DokkaContext
+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 `@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 the breakpoint.
+
+Having read through [Introduction to extensions](../architecture/extension_points/extension_points.md), we now know
+how to register our extensions:
+
+```kotlin
+class HideInternalApiPlugin : DokkaPlugin() {
+    val myFilterExtension by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer
+    }
+}
+```
+
+At this point we're ready to debug our plugin locally, it should already work, but do nothing.
+
+## Debugging
+
+Please read through [Debugging Dokka](../workflow.md#debugging-dokka), it goes over the same steps in more detail
+and with examples. Below you will find rough instructions.
+
+First, let's begin by publishing our plugin to `mavenLocal()`. 
+
+```bash
+./gradlew publishToMavenLocal
+```
+
+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 that has Dokka configured, and add our plugin to dependencies:
+
+```kotlin
+dependencies {
+    dokkaPlugin("org.example:hide-internal-api:1.0-SNAPSHOT")
+}
+```
+
+Next, in that project let's run `dokkaHtml` with debug enabled:
+
+```bash
+./gradlew clean dokkaHtml -Dorg.gradle.debug=true --no-daemon
+```
+
+Switch to the plugin project, set a breakpoint inside `shouldBeSuppressed` and run jvm remote debug.
+
+If you've done everything correctly, it should stop in debugger and you should be able to observe the values contained
+inside `d: Documentable`.
+
+## Implementing plugin logic
+
+Now that we've stopped at our breakpoint, let's skip until we see `shouldBeExcludedFromDocumentation` function in the
+place of `d: Documentable` (observe the changing `name` property).
+
+Looking at what's inside the object, you might notice it has 3 values in `extra`, one of which is `Annotations`.
+Sounds like something we need!
+
+Having poked around, we come up with the following monstrosity of a code for determining if a given documentable has
+`@Internal` annotation (it can of course be refactored.. later):
+
+```kotlin
+override fun shouldBeSuppressed(d: Documentable): Boolean {
+   
+    val annotations: List<Annotations.Annotation> =
+        (d as? WithExtraProperties<*>)
+            ?.extra
+            ?.allOfType<Annotations>()
+            ?.flatMap { it.directAnnotations.values.flatten() }
+            ?: emptyList()
+
+    return annotations.any { isInternalAnnotation(it) }
+}
+
+private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean {
+   return annotation.dri.packageName == "org.jetbrains.dokka.internal.test"
+           && annotation.dri.classNames == "Internal"
+}
+```
+
+Seems like we're done with writing our plugin and can begin testing it manually.
+
+## Manual testing
+
+At this point, the implementation of your plugin should look roughly like this:
+
+```kotlin
+package org.example.dokka.plugin
+
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.Annotations
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class HideInternalApiPlugin : DokkaPlugin() {
+    val myFilterExtension by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer
+    }
+}
+
+class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        val annotations: List<Annotations.Annotation> =
+            (d as? WithExtraProperties<*>)
+                ?.extra
+                ?.allOfType<Annotations>()
+                ?.flatMap { it.directAnnotations.values.flatten() }
+                ?: emptyList()
+
+        return annotations.any { isInternalAnnotation(it) }
+    }
+
+    private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean {
+        return annotation.dri.packageName == "org.jetbrains.dokka.internal.test"
+                && annotation.dri.classNames == "Internal"
+    }
+}
+```
+
+Bump plugin version in `gradle.build.kts`, publish it to maven local, open the debug project and run `dokkaHtml` 
+(without debug this time). 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!
+
+## Unit testing
+
+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 - 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 test that passes, and the main takeaways below that.
+
+```kotlin
+package org.example.dokka.plugin
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.junit.Test
+import kotlin.test.assertEquals
+
+class HideInternalApiPluginTest : BaseAbstractTest() {
+   
+    @Test
+    fun `should hide annotated functions`() {
+        val configuration = dokkaConfiguration {
+            sourceSets {
+                sourceSet {
+                    sourceRoots = listOf("src/main/kotlin/basic/Test.kt")
+                }
+            }
+        }
+        val hideInternalPlugin = HideInternalApiPlugin()
+
+        testInline(
+            """
+            |/src/main/kotlin/basic/Test.kt
+            |package org.jetbrains.dokka.internal.test
+            |
+            |annotation class Internal
+            |
+            |fun shouldBeVisible() {}
+            |
+            |@Internal
+            |fun shouldBeExcludedFromDocumentation() {}
+        """.trimMargin(),
+            configuration = configuration,
+            pluginOverrides = listOf(hideInternalPlugin)
+        ) {
+            preMergeDocumentablesTransformationStage = { modules ->
+                val testModule = modules.single { it.name == "root" }
+                val testPackage = testModule.packages.single { it.name == "org.jetbrains.dokka.internal.test" }
+
+                val packageFunctions = testPackage.functions
+                assertEquals(1, packageFunctions.size)
+                assertEquals("shouldBeVisible", packageFunctions[0].name)
+            }
+        }
+    }
+}
+```
+
+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 to your own if you are following along, 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](https://kotlinlang.org/docs/multiplatform-discover-project.html#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 a test, notice `pluginOverrides` parameter
+5. You can write asserts for 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 (that is
+   `preMergeDocumentablesTransformationStage`).
+6. You will need to write asserts using the model of whatever stage you choose. For `Documentable` transformation stage 
+   it's `Documentable`, for `Page` generation stage you would have `Page` model, and for `Output` you can have `.html`
+   files that you will need to parse with `JSoup` (there are also utilities for that).
+
+___
+
+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).
diff --git a/docs-developer/src/doc/docs/developer_guide/workflow.md b/docs-developer/src/doc/docs/developer_guide/workflow.md
new file mode 100644
index 00000000..7db5382d
--- /dev/null
+++ b/docs-developer/src/doc/docs/developer_guide/workflow.md
@@ -0,0 +1,100 @@
+# Workflow
+
+Whether you're contributing a feature/fix to Dokka itself or developing a Dokka plugin, there are 3 essential things
+you need to know how to do:
+
+1. How to build Dokka or a plugin
+2. How to use/test locally built Dokka in a project
+3. How to debug Dokka or a plugin in IntelliJ IDEA
+
+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.
+
+## Build Dokka
+
+Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run
+integration tests as well, which might take some time and will consume a lot of RAM, so you would usually want
+to exclude integration tests when building locally.
+
+```shell
+./gradlew build -x integrationTest
+```
+
+Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`.
+
+### Troubleshooting build
+
+#### API check failed for project ..
+
+If you see a message like `API check failed for project ..` during the `build` phase, it indicates that the
+[binary compatibility check](https://github.com/Kotlin/binary-compatibility-validator) has failed, meaning you've 
+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. These updated files need to be committed as well. Maintainers
+will review API changes thoroughly, so please make sure it's intentional and rational.
+
+## Use / test locally built Dokka
+
+Having built Dokka locally, you can publish it to `mavenLocal()`. This will allow you to test your changes in another
+project as well as debug code remotely.
+
+1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
+   For instance, you can set it to something like `1.8.20-my-fix-SNAPSHOT`. This version will be propagated to plugins
+   that reside inside Dokka's project (such as `mathjax`, `kotlin-as-java`, etc).
+2. Publish it to Maven Local (`./gradlew publishToMavenLocal`). Corresponding artifacts should appear in `~/.m2`
+3. In the project you want to generate documentation for or debug on, add maven local as a plugin/dependency
+   repository:
+```kotlin
+repositories {
+   mavenLocal()
+}
+```
+4. Update your Dokka dependency to the version you've just published:
+```kotlin
+plugins {
+    id("org.jetbrains.dokka") version "1.8.20-my-fix-SNAPSHOT"
+}
+```
+
+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. 
+
+Below you'll find instructions on how to debug Dokka's internal logic, but you can apply the same principles if you
+wish to debug a Dokka plugin.
+
+1. Choose a project to debug on, it needs to have some code for which documentation will be generated.
+   Prefer using smaller projects that reproduce the exact problem or behaviour you want
+   since the less code you have, the easier it will be to understand what's going on. You can use example projects
+   found in [dokka/examples/gradle](https://github.com/Kotlin/dokka/tree/master/examples/gradle), there's both simple 
+   single-module and more complex multi-module / multiplatform examples.
+2. For the debug project, set `org.gradle.debug` to `true` in one of the following ways:
+
+    * In your `gradle.properties` add `org.gradle.debug=true`
+    * When running Dokka tasks:<br/>`./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`
+
+3. Run the desired Dokka task with `--no-daemon`. Gradle should wait until you attach with debugger before proceeding
+   with the task, so no need to hurry here.
+   <br/>Example: `./gradlew dokkaHtml -Dorg.gradle.debug=true --no-daemon`.
+
+4. Open Dokka in IntelliJ IDEA, set a breakpoint and, using remote debug in IntelliJ IDEA,
+   [Attach to process](https://www.jetbrains.com/help/idea/attaching-to-local-process.html#attach-to-remote)
+   running on the default port 5005. You can do that either by creating a `Remote JVM Debug` Run/Debug configuration
+   or by attaching to the process via `Run` -> `Attach to process`
+
+!!! note
+    The reason for `--no-daemon` is that
+    [Gradle daemons](https://docs.gradle.org/current/userguide/gradle_daemon.html) continue to exist even after the task
+    has completed execution, so you might hang in debug or experience issues with `port was already in use` if you try
+    to run it again.
+    
+    If you previously ran Dokka with daemons and you are already encountering problems with it, try killing
+    gradle daemons. For instance, via `pkill -f gradle.*daemon`
+
+In case you need to debug some other part of the build - consult the official Gradle
+tutorials on [Troubleshooting Builds](https://docs.gradle.org/current/userguide/troubleshooting.html).
diff --git a/docs-developer/src/doc/docs/dokka_colors.css b/docs-developer/src/doc/docs/dokka_colors.css
new file mode 100644
index 00000000..69a24359
--- /dev/null
+++ b/docs-developer/src/doc/docs/dokka_colors.css
@@ -0,0 +1,3 @@
+.md-header, .md-tabs {
+    background-color: #27282c
+}
diff --git a/docs-developer/src/doc/docs/favicon.svg b/docs-developer/src/doc/docs/favicon.svg
new file mode 100755
index 00000000..1fea0877
--- /dev/null
+++ b/docs-developer/src/doc/docs/favicon.svg
@@ -0,0 +1,10 @@
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M64 64H0V0H64L31.3373 31.5369L64 64Z" fill="url(#paint0_radial)"/>
+    <defs>
+        <radialGradient id="paint0_radial" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(61.8732 2.63097) scale(73.3111)">
+            <stop offset="0.00343514" stop-color="#EF4857"/>
+            <stop offset="0.4689" stop-color="#D211EC"/>
+            <stop offset="1" stop-color="#7F52FF"/>
+        </radialGradient>
+    </defs>
+</svg>
\ No newline at end of file
diff --git a/docs-developer/src/doc/docs/index.md b/docs-developer/src/doc/docs/index.md
new file mode 100644
index 00000000..2cedfe35
--- /dev/null
+++ b/docs-developer/src/doc/docs/index.md
@@ -0,0 +1,9 @@
+# Dokka 
+
+Dokka is an API documentation engine for Kotlin.
+
+If you want to learn how to use Dokka, see 
+[documentation on kotlinlang.org](https://kotlinlang.org/docs/dokka-introduction.html).
+
+If you want to learn more about Dokka's internals and/or how to write Dokka plugins,
+see [Developer guides](developer_guide/introduction.md).
diff --git a/docs-developer/src/doc/mkdocs.yml b/docs-developer/src/doc/mkdocs.yml
new file mode 100644
index 00000000..533d32b1
--- /dev/null
+++ b/docs-developer/src/doc/mkdocs.yml
@@ -0,0 +1,86 @@
+site_name: Dokka
+
+# Meta tags (placed in header)
+site_description: Dokka is an API 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)
+repo_name: dokka
+repo_url: https://github.com/Kotlin/dokka
+edit_uri: edit/master/docs-developer/src/doc/docs/
+
+# Copyright (shown at the footer)
+copyright: 'Copyright &copy; 2023 JetBrains'
+
+# Material theme
+theme:
+  name: 'material'
+  favicon: favicon.svg
+  social:
+    - type: 'github'
+      link: 'https://github.com/Kotlin/dokka'
+  features:
+    - navigation.expand
+    - navigation.tabs
+    - navigation.instant
+    - navigation.indexes
+    - navigation.top
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - codehilite:
+      guess_lang: false
+  - footnotes
+  - meta
+  - def_list
+  - toc:
+      permalink: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.smartsymbols
+  - attr_list
+  - md_in_html
+  - pymdownx.superfences:
+      custom_fences:
+          - name: mermaid
+            class: mermaid
+            format: !!python/name:pymdownx.superfences.fence_code_format
+
+# Dev server binding for livereload
+dev_addr: 127.0.0.1:3001
+
+nav:
+  - Home:
+      - index.md
+      - User guides: https://kotlinlang.org/docs/dokka-introduction.html
+      - Developer guides: developer_guide/introduction.md
+      - Community: developer_guide/community/slack.md
+  - User guides:
+      - https://kotlinlang.org/docs/dokka-introduction.html
+  - Developer guides:
+      - Developer guides: developer_guide/introduction.md
+      - Workflow: developer_guide/workflow.md
+      - Internals:
+          - Architecture: developer_guide/architecture/architecture_overview.md
+          - Data model:
+              -  Documentables: developer_guide/architecture/data_model/documentable_model.md
+              -  Page & Content: developer_guide/architecture/data_model/page_content.md
+              -  Extra properties: developer_guide/architecture/data_model/extra.md
+          - Extensions:
+              - Extension points: developer_guide/architecture/extension_points/extension_points.md
+              - Core extension points: developer_guide/architecture/extension_points/core_extension_points.md
+              - Base extensions: developer_guide/architecture/extension_points/base_plugin.md
+              - Generation implementations: developer_guide/architecture/extension_points/generation_implementations.md
+      - Plugin development:
+          - Plugin development: developer_guide/plugin-development/introduction.md
+          - Sample plugin tutorial: developer_guide/plugin-development/sample-plugin-tutorial.md
+  - Community:
+      - Slack: developer_guide/community/slack.md
+
+extra_css:
+  - dokka_colors.css
-- 
cgit