docs: Add navigation structure and remove redundant topics (#2203)

* replace broken links

documentation-website/Writerside/hi.tree

@@ -6,21 +6,26 @@
                   name="Exposed"
                   start-page="Home.topic">
 
-    <toc-element topic="Home.topic"/>
+    <toc-element topic="Home.topic" toc-title="Home"/>
     <toc-element topic="Getting-Started-with-Exposed.topic" toc-title="Get started with Exposed"/>
     <toc-element topic="Exposed-Modules.md"/>
-    <toc-element topic="Database-and-DataSource.md"/>
-    <toc-element toc-title="Working with Tables">
+    <toc-element toc-title="Databases">
+        <toc-element topic="Working-with-Database.md"/>
+        <toc-element topic="Working-with-DataSource.md"/>
+        <toc-element topic="Transactions.md"/>
+    </toc-element>
+    <toc-element toc-title="Schemas">
         <toc-element topic="Table-Definition.md"/>
         <toc-element topic="Data-Types.md"/>
         <toc-element topic="SQL-Functions.md"/>
     </toc-element>
-    <toc-element topic="Transactions.md"/>
     <toc-element topic="Deep-Dive-into-DSL.md"/>
     <toc-element topic="Deep-Dive-into-DAO.md"/>
+    <toc-element toc-title="Releases">
+        <toc-element topic="Breaking-Changes.md"/>
+        <toc-element topic="Migration-Guide.md"/>
+    </toc-element>
     <toc-element topic="Frequently-Asked-Questions.md"/>
-    <toc-element topic="Samples.md"/>
-    <toc-element topic="Migration-Guide.md"/>
-    <toc-element topic="Breaking-Changes.md"/>
+    <toc-element toc-title="Samples" href="https://github.com/JetBrains/Exposed/tree/main/samples"/>
     <toc-element topic="Contributing.md"/>
 </instance-profile>

documentation-website/Writerside/topics/Contributing.md

@@ -1,3 +1,5 @@
+<show-structure for="chapter,procedure" depth="3"/>
+
 # Contributing to Exposed
 
 We're delighted that you're considering contributing to Exposed!
@@ -37,9 +39,9 @@ Make sure that default is used as default docker context:
 docker context list
 ```
 
-### Code
+## Code
 
-#### Pull Requests
+### Pull Requests
 
 Contributions are made using Github [pull requests](https://help.github.com/en/articles/about-pull-requests):
 
@@ -58,7 +60,7 @@ Contributions are made using Github [pull requests](https://help.github.com/en/a
 10. Finally, make sure to run the `apiCheck` Gradle task. If it's not successful, run the `apiDump` Gradle task. Further information can be
    found [here](https://github.com/Kotlin/binary-compatibility-validator).
 
-#### Style Guides
+### Style Guides
 
 A few things to remember:
 
@@ -77,7 +79,7 @@ Test functions:
 * In the definition of test functions, use a block body instead of an assignment operator. 
   For example, do write `fun testMyTest() { withDb{} }`, and avoid writing `fun testMyTest() = withDb{}`.
 
-#### Commit messages
+### Commit messages
 
 * Commit messages should be written in English.
 * Their title should be prefixed according to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
@@ -86,20 +88,20 @@ Test functions:
 * When applicable, prefix the commit message with EXPOSED-{NUM} where {NUM} represents the YouTrack issue number.
 * Add the related bug reference to a commit message (bug number after a hash character between round braces).
 
-### Documentation
+## Documentation
 
 There are multiple ways in which you can contribute to Exposed docs:
 
 - Create an issue in [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED).
 - Submit a pull request containing your proposed changes. 
 Ensure that these modifications are applied directly within the `documentation-website` directory.
 
-### Community Support
+## Community Support
 
 If you'd like to help others, please join our Exposed [channel](https://kotlinlang.slack.com/archives/C0CG7E0A1) on the Kotlin Slack workspace and
 help out. It's also a great way to learn!
 
-### Issues and Feature Requests
+## Issues and Feature Requests
 
 If you encounter a bug or have an idea for a new feature, please submit it to us through [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED),
 our issue tracker.

documentation-website/Writerside/topics/Data-Types.md

@@ -1,3 +1,5 @@
+<show-structure for="chapter,procedure" depth="3"/>
+
 # Data Types
 
 Exposed supports the following data types in the table definition:
@@ -61,13 +63,13 @@ them when defining a `customEnumeration`.
 
 For a class like `enum class Foo { BAR, BAZ }`, you can use the provided code below for your specific database:
 
-**MySQL, H2**
+### MySQL, H2
 ```Kotlin
 val existingEnumColumn = customEnumeration("enumColumn", { value -> Foo.valueOf(value as String) }, { it.name })
 val newEnumColumn = customEnumeration("enumColumn", "ENUM('BAR', 'BAZ')", { value -> Foo.valueOf(value as String) }, { it.name })
 ```
 
-**PostgreSQL**
+### PostgreSQL
 
 PostgreSQL requires that ENUM is defined as a separate type, so you have to create it before creating your table. 
 Also, the PostgreSQL JDBC driver returns `PGobject` instances for such values, so a `PGobject` with its type manually set to the ENUM type needs to be used for the `toDb` parameter.

documentation-website/Writerside/topics/Deep-Dive-into-DAO.md

@@ -1,6 +1,7 @@
+<show-structure for="chapter,procedure" depth="2"/>
+
 # Deep Dive into DAO
 
-## Overview
 The DAO (Data Access Object) API of Exposed, is similar to ORM frameworks like Hibernate with a Kotlin-specific API.  
 A DB table is represented by an `object` inherited from `org.jetbrains.exposed.sql.Table` like this:
 ```kotlin
@@ -181,7 +182,7 @@ val updatedMovie2 = StarWarsFilm.findSingleByAndUpdate(StarWarsFilms.name eq "Th
 movie.delete() 
 ```
 ## Referencing
-### many-to-one reference
+### Many-to-one reference
 Let's say you have this table:
 ```kotlin
 object Users : IntIdTable() {
@@ -299,7 +300,7 @@ class User(id: EntityID<Int>) : IntEntity(id) {
     ...
 ```
 
-### many-to-many reference
+### Many-to-many reference
 In some cases, a many-to-many reference may be required.
 Let's assume you want to add a reference to the following Actors table to the StarWarsFilm class:
 ```kotlin
@@ -431,7 +432,9 @@ by using the respective overloads that accept an `IdTable` as an argument.
 These overloads will automatically resolve the foreign key constraint associated with the composite primary key.
 
 ### Eager Loading
-**Available since 0.13.1**.
+>This feature is available since version 0.13.1.
+{style="note"}
+
 References in Exposed are lazily loaded, meaning queries to fetch the data for the reference are made at the moment the reference is first utilised. For scenarios wherefore you know you will require references ahead of time, Exposed can eager load them at the time of the parent query, this is prevents the classic "N+1" problem as references can be aggregated and loaded in a single query.
 To eager load a reference you can call the "load" function and pass the DAO's reference as a KProperty:
 ```kotlin
@@ -445,12 +448,13 @@ Similarly, you can eagerly load references on Collections of DAO's such as Lists
 ```kotlin
 StarWarsFilm.all().with(StarWarsFilm::actors)
 ```
-NOTE: References that are eagerly loaded are stored inside the transaction cache;
-this means that they are not available in other transactions
-and thus must be loaded and referenced inside the same transaction.
-As of [0.35.1](https://github.com/JetBrains/Exposed/blob/master/docs/ChangeLog.md#0351:~:text=References%20can%20be%20stored%20within%20an%20Entity%20with%20enabled%20keepLoadedReferencesOutOfTransaction%20config%20parameter.%20It%20will%20allow%20getting%20referenced%20values%20outside%20the%20transaction%20block.),
-enabling `keepLoadedReferencesOutOfTransaction` in `DatabaseConfig`
-will allow getting referenced values outside the transaction block.
+>References that are eagerly loaded are stored inside the transaction cache;
+>this means that they are not available in other transactions
+>and thus must be loaded and referenced inside the same transaction.
+>As of [0.35.1](https://github.com/JetBrains/Exposed/blob/main/CHANGELOG.md#0351),
+>enabling `keepLoadedReferencesOutOfTransaction` in `DatabaseConfig`
+>will allow getting referenced values outside the transaction block.
+{style="note"}
 
 #### Eager loading for Text Fields
 Some database drivers do not load text content immediately (for performance and memory reasons) which means that you can obtain the column value only within the open transaction.

documentation-website/Writerside/topics/Deep-Dive-into-DSL.md

@@ -1,6 +1,6 @@
-# Deep Dive into DSL
+<show-structure for="chapter,procedure" depth="2"/>
 
-## Overview
+# Deep Dive into DSL
 
 The DSL (Domain-Specific Language) API of Exposed is similar to actual SQL statements, but with the type safety that Kotlin offers.
 

documentation-website/Writerside/topics/Exposed-Modules.md

@@ -1,4 +1,6 @@
-# Exposed Modules
+<show-structure for="chapter,procedure" depth="2"/>
+
+# Modules
 
 ## Dependencies
 
@@ -158,7 +160,7 @@ Dependencies mapping listed below is similar (by functionality) to the previous
 ### JDBC driver and logging
 
 You also need a JDBC driver for the database system you are using
-(see [Databases](Database-and-DataSource.md)) and a logger
+(see [Working with Databases](Working-with-Database.md)) and a logger
 for `addLogger(StdOutSqlLogger)`.
 Example (Gradle
 syntax):

documentation-website/Writerside/topics/Getting-Started-with-Exposed.topic

@@ -3,6 +3,7 @@
 <topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
        id="Getting-Started-with-Exposed" title="Get started with Exposed, an ORM framework for Kotlin">
+    <show-structure for="chapter,procedure" depth="2"/>
     <tldr>
         <var name="example_name" value="get-started-with-exposed"/>
         <include from="lib.topic" element-id="code_example"/>

documentation-website/Writerside/topics/Home.topic

@@ -15,12 +15,12 @@
 
         <spotlight>
             <a href="Getting-Started-with-Exposed.topic" type="learn"
-               summary="Start exploring Exposed step-by-step by building our sample project from scratch">
-                Getting Started with Exposed
+               summary="Learn how to create and query tables in Kotlin with Exposed DSL API">
+                Get Started with Exposed
             </a>
             <a href="https://jetbrains.github.io/Exposed/api/index.html" type="server"
-               summary="API Documentation">
-                API
+               summary="External API Documentation">
+                API Reference
             </a>
         </spotlight>
 
@@ -30,11 +30,9 @@
                summary="Learn how to configure Exposed in the existing project using Gradle or Maven build systems">
                 Adding Dependencies
             </a>
-            <a href="Table-Definition.md" summary="Start creating your first tables and get familiar with the column types">
-                Tables and Columns ABC
-            </a>
+            <a href="Table-Definition.md" summary="Start creating your first tables and get familiar with the column types"/>
             <a href="Deep-Dive-into-DSL.md" summary="Learn how to write database queries using Exposed query DSL">
-                Querying Database
+                Querying a Database
             </a>
             <a href="Deep-Dive-into-DAO.md"
                summary="Learn how to perform basic CRUD (Create, Read, Update, Delete) operations using entities mapping">

documentation-website/Writerside/topics/Migration-Guide.md

@@ -1,6 +1,4 @@
-# Migration Guide
-
-## Migrating from 0.45.0 to 0.46.0
+# Migrating from 0.45.0 to 0.46.0
 
 While Exposed provides migration support in the code itself (by using the `@Deprecated` annotation and `ReplaceWith` quickfix),
 this document serves as a reference point for the migration steps necessary to switch to the new query DSL.

documentation-website/Writerside/topics/SQL-Functions.md

@@ -1,3 +1,5 @@
+<show-structure for="chapter,procedure" depth="2"/>
+
 # SQL Functions
 
 Exposed provides basic support for classic SQL functions. This topic consists of definitions for those functions, and their