diff --git a/doc/annotations.md b/doc/annotations.md
index 49c9014aa..75a881086 100644
--- a/doc/annotations.md
+++ b/doc/annotations.md
@@ -1,567 +1,1505 @@
-# Annotation reference
+# Annotations Reference
 
-Bellow you will find all annotation descriptions used in these extensions.
-There will be introduction on usage with examples. For more detailed usage
-on extensions, refer to their specific documentation.
+> [!IMPORTANT]
+> To use annotations, you will need the deprecated [`doctrine/annotations`](https://www.doctrine-project.org/projects/annotations.html) library. PHP 8 users are encouraged to migrate to attributes as annotation support is deprecated in all supported Doctrine object managers.
 
-Content:
+Below you will a reference for annotations supported in this extensions library.
+There will be introduction on usage with examples. For more detailed usage of each
+extension, refer to the extension's documentation page.
 
-- Best [practices](#em-setup) for setting up
-- [Tree](#gedmo-tree)
-- [Translatable](#gedmo-translatable)
-- [Sluggable](#gedmo-sluggable)
-- [Timestampable](#gedmo-timestampable)
-- [Loggable](#gedmo-loggable)
+## Index
 
-## Annotation mapping
+- [Blameable Extension](#blameable-extension)
+- [IP Traceable Extension](#ip-traceable-extension)
+- [Loggable Extension](#loggable-extension)
+- [Reference Integrity Extension](#reference-integrity-extension)
+- [References Extension](#references-extension)
+- [Sluggable Extension](#sluggable-extension)
+- [Soft Deleteable Extension](#soft-deleteable-extension)
+- [Sortable Extension](#sortable-extension)
+- [Timestampable Extension](#timestampable-extension)
+- [Translatable Extension](#translatable-extension)
+- [Tree Extension](#tree-extension)
+- [Uploadable Extension](#uploadable-extension)
 
-Starting from **doctrine2.1.x** versions you have to import all used annotations
-by an **use** statement, see example bellow:
+## Reference
+
+### Blameable Extension
+
+The below annotations are used to configure the [Blameable extension](./blameable.md).
+
+#### `@Gedmo\Mapping\Annotation\Blameable`
+
+The `Blameable` annotation is a property annotation used to identify fields which are updated to show information
+about the last user to update the mapped object. A blameable field may have either a string value or a one-to-many
+relationship with another entity.
+
+Required Attributes:
+
+- **on** - By default, the annotation configures the property to be updated when an object is updated;
+           this can be set to one of \[`change`, `create`, `update`\]
+
+Optional Attributes:
+
+- **field** - An optional list of properties to limit updates to the blameable field; this option is only
+              used when the **on** option is set to "change" and can be a dot separated path to indicate
+              properties on a related object are watched (i.e. `user.email` to reference the `$email` property
+              of the `$user` relation on this object)
+
+- **value** - An optional value to require the configured **field** to match to update the blameable field;
+              this option is only used when the **on** option is set to "change"
+
+> [!WARNING]
+> When both the **field** and **value** options are set, the **field** can only be set to a single field; checking the value against multiple fields is not supported at this time
+
+Examples:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     */
+    public ?string $title = null;
+
+    /**
+     * @ORM\Column(type="string")
+     */
+    public ?string $body = null;
+
+    /**
+     * Blameable field storing a username for the user who created the entity
+     *
+     * @ORM\Column(type="string")
+     * @Gedmo\Blameable(on="create")
+     */
+    public ?string $createdBy = null;
+
+    /**
+     * Blameable field storing a User relation for the user who updated the entity
+     *
+     * @ORM\ManyToOne(targetEntity="App\Entity\User")
+     * @Gedmo\Blameable(on="update")
+     */
+    public ?User $updatedBy = null;
+
+    /**
+     * Blameable field storing a username for the user who last changed either the title or body fields
+     *
+     * @ORM\Column(type="string", nullable=true)
+     * @Gedmo\Blameable(on="change", field={"title", "body"})
+     */
+    public ?string $contentChangedBy = null;
+}
+```
+
+### IP Traceable Extension
+
+The below annotations are used to configure the [IP Traceable extension](./ip_traceable.md).
+
+#### `@Gedmo\Mapping\Annotation\IpTraceable`
+
+The `IpTraceable` annotation is a property annotation used to identify fields which are updated to record the
+IP address from the last user to update the mapped object. A traceable field must be a string.
+
+Required Attributes:
+
+- **on** - By default, the annotation configures the property to be updated when an object is updated;
+           this can be set to one of \[`change`, `create`, `update`\]
+
+Optional Attributes:
+
+- **field** - An optional list of properties to limit updates to the IP traceable field; this option is only
+              used when the **on** option is set to "change" and can be a dot separated path to indicate
+              properties on a related object are watched (i.e. `user.email` to reference the `$email` property
+              of the `$user` relation on this object)
+
+- **value** - An optional value to require the configured **field** to match to update the IP traceable field;
+              this option is only used when the **on** option is set to "change"
+
+> [!WARNING]
+> When both the **field** and **value** options are set, the **field** can only be set to a single field; checking the value against multiple fields is not supported at this time
+
+Examples:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     */
+    public ?string $title = null;
+
+    /**
+     * @ORM\Column(type="string")
+     */
+    public ?string $body = null;
+
+    /**
+     * Traceable field storing an IP address for the user who created the entity
+     *
+     * @ORM\Column(type="string")
+     * @Gedmo\IpTraceable(on="create")
+     */
+    public ?string $createdByIp = null;
+
+    /**
+     * Traceable field storing an IP address for the user who updated the entity
+     *
+     * @ORM\Column(type="string")
+     * @Gedmo\IpTraceable(on="update")
+     */
+    public ?string $updatedByIp = null;
+
+    /**
+     * Traceable field storing an IP address for the user who last changed either the title or body fields
+     *
+     * @ORM\Column(type="string", nullable=true)
+     * @Gedmo\IpTraceable(on="change", field={"title", "body"})
+     */
+    public ?string $contentChangedByIp = null;
+}
+```
+
+### Loggable Extension
+
+The below annotations are used to configure the [Loggable extension](./loggable.md).
+
+#### `@Gedmo\Mapping\Annotation\Loggable`
+
+The `Loggable` annotation is a class annotation used to identify objects which can have changes logged,
+all loggable objects **MUST** have this annotation.
+
+Required Attributes:
+
+- **logEntryClass** - A custom model class implementing `Gedmo\Loggable\LogEntryInterface` to use for logging changes;
+                      defaults to `Gedmo\Loggable\Entity\LogEntry` for Doctrine ORM users or
+                      `Gedmo\Loggable\Document\LogEntry` for Doctrine MongoDB ODM users
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ * @Gedmo\Loggable(logEntryClass="App\Entity\ArticleLogEntry")
+ */
+class Article {}
+```
+
+#### `@Gedmo\Mapping\Annotation\Versioned`
+
+The `Versioned` annotation is a property annotation used to identify properties whose changes should be logged.
+This annotation can be set for properties with a single value (i.e. a scalar type or an object such as
+`DateTimeInterface`), but not for collections. Versioned fields can be restored to an earlier version.
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ * @Gedmo\Loggable
+ */
+class Comment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Article", inversedBy="comments")
+     * @Gedmo\Versioned
+     */
+    public ?Article $article = null;
+
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\Versioned
+     */
+    public ?string $body = null;
+}
+```
+
+### Reference Integrity Extension
+
+The below annotations are used to configure the [Reference Integrity extension](./reference_integrity.md).
+
+> [!WARNING]
+> This extension is only usable with the Doctrine MongoDB ODM
+
+#### `@Gedmo\Mapping\Annotation\ReferenceIntegrity`
+
+The `ReferenceIntegrity` annotation is a property annotation used to identify fields where referential integrity
+should be checked. The annotation must be used on a property which references another document, and the reference
+configuration must have a `mappedBy` configuration.
+
+Required Attributes:
+
+- **value** - The type of action to take for the reference, must be one of \[`nullify`, `pull`, `restrict`\]
+
+Example:
+
+```php
+<?php
+namespace App\Document;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ODM\Document(collection="articles")
+ */
+class Article
+{
+    /**
+     * @ODM\Id
+     */
+    public ?string $id = null;
+
+    /**
+     * @ODM\Field(type="string")
+     */
+    public ?string $title = null;
+
+    /**
+     * @ODM\ReferenceOne(targetDocument="App\Document\User", mappedBy="articles")
+     * @Gedmo\ReferenceIntegrity("nullify")
+     */
+    public ?User $author = null;
+
+    /**
+     * @var Collection<int, Comment>
+     *
+     * @ODM\ReferenceMany(targetDocument="App\Document\Comment", mappedBy="article")
+     * @Gedmo\ReferenceIntegrity("nullify")
+     */
+    private Collection $comments;
+
+    public function __construct()
+    {
+        $this->comments = new ArrayCollection();
+    }
+}
+```
+
+### References Extension
+
+The below annotations are used to configure the [References extension](./references.md).
+
+#### `@Gedmo\Mapping\Annotation\ReferenceOne`
+
+The `ReferenceOne` annotation is a property annotation used to create a reference between two objects in different
+databases or object managers. This is similar to a `ReferenceOne` relationship in the MongoDB ODM.
+
+Required Attributes:
+
+- **value** - The type of action to take for the reference, must be one of \[`nullify`, `pull`, `restrict`\]
+
+- **type** - The type of object manager to use for the reference, must be one of \[`document`, `entity`\]
+
+- **class** - The class name of the object to reference
+
+Optional Attributes:
+
+- **identifier** - The name of the property to store the identifier value in
+
+- **inversedBy** - The name of the property on the inverse side of the reference
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use App\Document\Article;
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ */
+class Comment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @Gedmo\ReferenceOne(type="document", class="App\Document\Article", inversedBy="comments", identifier="articleId")
+     */
+    public ?Article $article = null;
+
+    /**
+     * @ORM\Column(type="string")
+     */
+    public ?string $articleId = null;
+}
+```
+
+#### `@Gedmo\Mapping\Annotation\ReferenceMany`
+
+The `ReferenceMany` annotation is a property annotation used to create a reference between two objects in different
+databases or object managers. This is similar to a `ReferenceMany` relationship in the MongoDB ODM.
+
+Required Attributes:
+
+- **value** - The type of action to take for the reference, must be one of \[`nullify`, `pull`, `restrict`\]
+
+- **type** - The type of object manager to use for the reference, must be one of \[`document`, `entity`\]
+
+- **class** - The class name of the object to reference
+
+Optional Attributes:
+
+- **identifier** - The name of the property to store the identifier value in
+
+- **mappedBy** - The name of the property on the owning side of the reference
+
+Example:
+
+```php
+<?php
+namespace App\Document;
+
+use App\Entity\Comment;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ODM\Document(collection="articles")
+ */
+class Article
+{
+    /**
+     * @ODM\Id
+     */
+    public ?string $id = null;
+
+    /**
+     * @var Collection<int, Comment>
+     *
+     * @Gedmo\ReferenceMany(type="entity", class="App\Entity\Comment", mappedBy="comments")
+     */
+    private Collection $comments;
+
+    public function __construct()
+    {
+        $this->comments = new ArrayCollection();
+    }
+}
+```
+
+#### `@Gedmo\Mapping\Annotation\ReferenceMany`
+
+The `ReferenceMany` annotation is a property annotation used to create a reference between two objects in different
+databases or object managers. This is similar to a `ReferenceMany` relationship in the MongoDB ODM.
+
+Required Attributes:
+
+- **value** - The type of action to take for the reference, must be one of \[`nullify`, `pull`, `restrict`\]
+
+- **type** - The type of object manager to use for the reference, must be one of \[`document`, `entity`\]
+
+- **class** - The class name of the object to reference
+
+Optional Attributes:
+
+- **identifier** - The name of the property to store the identifier value in
+
+Example:
+
+```php
+<?php
+namespace App\Document;
+
+use App\Entity\Comment;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ODM\Document(collection="articles")
+ */
+class Article
+{
+    /**
+     * @ODM\Id
+     */
+    public ?string $id = null;
+
+    /**
+     * @var Collection<int, Comment>
+     *
+     * @Gedmo\ReferenceManyEmbed(type="entity", class="App\Entity\Comment", identifier="metadata.commentId")
+     */
+    private Collection $comments;
+
+    public function __construct()
+    {
+        $this->comments = new ArrayCollection();
+    }
+}
+```
+
+### Sluggable Extension
+
+The below annotations are used to configure the [Sluggable extension](./sluggable.md).
+
+#### `@Gedmo\Mapping\Annotation\Slug`
+
+The `Slug` annotation is a property annotation used to identify the field the slug is stored to.
+
+Required Attributes:
+
+- **fields** - A list of fields on the object to use for generating a slug, this must be a non-empty list of strings
+
+Optional Attributes:
+
+- **updatable** - Flag indicating the slug can be automatically updated if any of the fields have changed,
+                  defaults to `true`
+
+- **style** - The style to use while generating the slug, defaults to `default` (no style changes) and ignores
+              unsupported styles; supported styles are:
+    - `camel` - Converts the slug to a camel-case string
+    - `lower` - Converts the slug to a fully lowercased string
+    - `upper` - Converts the slug to a fully uppercased string
+
+- **unique** - Flag indicating the slug must be unique, defaults to `true`
+
+- **unique_base** - The name of the object property that should be used as a key when doing a uniqueness check,
+                    can only be set when the **unique** flag is `true`
+
+- **separator** - The separator to use between words in the slug, defaults to `-`
+
+- **prefix** - An optional prefix for the generated slug
+
+- **suffix** - An optional suffix for the generated slug
+
+- **handlers** - A list of `@Gedmo\Mapping\Annotation\SlugHandler` annotations used to further customize the slug
+                 generator behavior
+
+Basic Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     */
+    public ?string $title = null;
+
+    /**
+     * @ORM\Column(type="string", unique=true)
+     * @Gedmo\Slug(fields={"title"})
+     */
+    public ?string $slug = null;
+}
+```
+
+#### `@Gedmo\Mapping\Annotation\SlugHandler`
+
+The `SlugHandler` annotation is used with the `Slug` annotation's **handlers** attribute to configure slug handlers for
+the object. Slug handlers can be used to further manipulate and validate the generated slug. Please see the
+[using slug handlers](./sluggable.md#using-slug-handlers) section of the documentation for more information on how
+to use these handlers.
+
+Required Attributes:
+
+- **class** - The class name of a `Gedmo\Sluggable\Handler\SlugHandlerInterface` implementation to use as a handler
+
+Optional Attributes:
+
+- **options** - A list of `@Gedmo\Mapping\Annotation\SlugHandlerOption` annotations used to configure the
+                slug handler's behavior
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Category", inversedBy="articles")
+     */
+    public ?Category $category = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     */
+    public ?string $title = null;
+
+    /**
+     * @ORM\Column(type="string", unique=true)
+     * @Gedmo\Slug(
+     *   fields={"title"},
+     *   handlers={
+     *     @Gedmo\SlugHandler(
+     *       class="Gedmo\Sluggable\Handler\TreeSlugHandler",
+     *       options={
+     *         @Gedmo\SlugHandlerOption(name="parentRelationField", value="category"),
+     *         @Gedmo\SlugHandlerOption(name="separator", value="/")
+     *       }
+     *     )
+     *   }
+     * )
+     */
+    public ?string $slug = null;
+}
+```
+
+#### `@Gedmo\Mapping\Annotation\SlugHandlerOption`
+
+The `SlugHandlerOption` annotation is used with the `SlugHandler` annotation's **options** attribute to configure
+the slug handler.
+
+Required Attributes:
+
+- **name** - The name of the option for the slug handler, must be a non-empty string
+
+Optional Attributes:
+
+- **value** - A value for the option, defaults to null
+
+### Soft Deleteable Extension
+
+The below annotations are used to configure the [Soft Deleteable extension](./softdeleteable.md).
+
+#### `@Gedmo\Mapping\Annotation\SoftDeleteable`
+
+The `SoftDeleteable` annotation is a class annotation used to identify objects which are soft deleteable.
+
+Required Attributes:
+
+- **fieldName** - The name of the property in which the soft delete timestamp is stored, defaults to `deletedAt`;
+                  this field must be a field support a `DateTimeInterface`
+
+Optional Attributes:
+
+- **timeAware** - Flag indicating the object supports scheduled soft deletes, defaults to `false`
+
+- **hardDelete** - Flag indicating the object supports hard deletes, defaults to `true`
+
+Examples:
 
 ```php
-namespace MyApp\Entity;
+<?php
+namespace App\Entity;
 
-use Gedmo\Mapping\Annotation as Gedmo; // this will be like an alias for Gedmo extensions annotations
-use Doctrine\ORM\Mapping\Id; // includes single annotation
-use Doctrine\ORM\Mapping as ORM; // alias for doctrine ORM annotations
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
 /**
  * @ORM\Entity
- * @Gedmo\TranslationEntity(class="something")
+ * @Gedmo\SoftDeleteable
  */
 class Article
 {
     /**
-     * @Id
-     * @Gedmo\Slug(fields={"title"}, updatable=false, separator="_")
-     * @ORM\Column(length=32, unique=true)
-     */
-    private $id;
-
-    /**
-     * @Gedmo\Translatable
-     * @ORM\Column(length=64)
-     */
-    private $title;
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
 
     /**
-     * @Gedmo\Timestampable(on="create")
-     * @ORM\Column(type="datetime")
+     * @ORM\Column(type="datetime_immutable")
      */
-    private $created;
+    public ?\DateTimeImmutable $deletedAt = null;
 }
 ```
 
-**Note:** this mapping applies only if you use **doctrine-common** library at version **2.1.x** or higher,
-extension library still supports old mapping styles if you manually set the mapping drivers
-
-<a name="em-setup"></a>
-
-## Best practices for setting up with annotations
-
-New annotation reader does not depend on any namespaces, for that reason you can use
-single reader instance for whole project. The example bellow shows how to setup the
-mapping and listeners:
-
-**Note:** using this repository you can test and check the [example demo configuration](../example/em.php)
-
-```php
-<?php
-// WARNING: setup, assumes that autoloaders are set
-
-// globally used cache driver, in production use APC or memcached
-$cache = new Doctrine\Common\Cache\ArrayCache;
-// standard annotation reader
-$annotationReader = new Doctrine\Common\Annotations\AnnotationReader;
-$cachedAnnotationReader = new Doctrine\Common\Annotations\CachedReader(
-    $annotationReader, // use reader
-    $cache // and a cache driver
-);
-// create a driver chain for metadata reading
-$driverChain = new Doctrine\ORM\Mapping\Driver\DriverChain();
-// load superclass metadata mapping only, into driver chain
-// also registers Gedmo annotations.NOTE: you can personalize it
-Gedmo\DoctrineExtensions::registerAbstractMappingIntoDriverChainORM(
-    $driverChain, // our metadata driver chain, to hook into
-    $cachedAnnotationReader // our cached annotation reader
-);
-
-// now we want to register our application entities,
-// for that we need another metadata driver used for Entity namespace
-$annotationDriver = new Doctrine\ORM\Mapping\Driver\AnnotationDriver(
-    $cachedAnnotationReader, // our cached annotation reader
-    array(__DIR__.'/app/Entity') // paths to look in
-);
-// NOTE: driver for application Entity can be different, Attribute, Xml or whatever
-// register annotation driver for our application Entity namespace
-$driverChain->addDriver($annotationDriver, 'Entity');
+### Sortable Extension
+
+The below annotations are used to configure the [Sortable extension](./sortable.md).
+
+#### `@Gedmo\Mapping\Annotation\SortableGroup`
+
+The `SortableGroup` annotation is a property annotation used to identify fields which are used to group objects of
+this type for sorting.
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
-// general ORM configuration
-$config = new Doctrine\ORM\Configuration;
-$config->setProxyDir(sys_get_temp_dir());
-$config->setProxyNamespace('Proxy');
-$config->setAutoGenerateProxyClasses(false); // this can be based on production config.
-// register metadata driver
-$config->setMetadataDriverImpl($driverChain);
-// use our already initialized cache driver
-$config->setMetadataCacheImpl($cache);
-$config->setQueryCacheImpl($cache);
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
 
-// create event manager and hook preferred extension listeners
-$evm = new Doctrine\Common\EventManager();
-// gedmo extension listeners, remove which are not used
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Category", inversedBy="articles")
+     * @Gedmo\SortableGroup
+     */
+    public ?Category $category = null;
+}
+```
 
-// sluggable
-$sluggableListener = new Gedmo\Sluggable\SluggableListener;
-// you should set the used annotation reader to listener, to avoid creating new one for mapping drivers
-$sluggableListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($sluggableListener);
+#### `@Gedmo\Mapping\Annotation\SortablePosition`
 
-// tree
-$treeListener = new Gedmo\Tree\TreeListener;
-$treeListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($treeListener);
+The `SortablePosition` annotation is a property annotation used to identify the field where the sorted position
+(optionally within a group) is stored for the current object type. This field must be an integer field type.
 
-// loggable, not used in example
-$loggableListener = new Gedmo\Loggable\LoggableListener;
-$loggableListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($loggableListener);
+Example:
 
-// timestampable
-$timestampableListener = new Gedmo\Timestampable\TimestampableListener;
-$timestampableListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($timestampableListener);
+```php
+<?php
+namespace App\Entity;
 
-// translatable
-$translatableListener = new Gedmo\Translatable\TranslatableListener;
-// current translation locale should be set from session or hook later into the listener
-// most important, before entity manager is flushed
-$translatableListener->setTranslatableLocale('en');
-$translatableListener->setDefaultLocale('en');
-$translatableListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($translatableListener);
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
-// sortable, not used in example
-$sortableListener = new Gedmo\Sortable\SortableListener;
-$sortableListener->setAnnotationReader($cachedAnnotationReader);
-$evm->addEventSubscriber($sortableListener);
+/**
+ * @ORM\Entity
+ */
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
 
-// mysql set names UTF-8 if required
-$evm->addEventSubscriber(new Doctrine\DBAL\Event\Listeners\MysqlSessionInit());
-// DBAL connection
-$driverParams = array(
-    'driver' => 'pdo_mysql',
-    'host' => '127.0.0.1',
-    'dbname' => 'test',
-    'user' => 'root',
-    'password' => ''
-);
-// Finally, create entity manager
-$connection = DriverManager::getConnection($driverParams, $config);
-$em = new EntityManager($connection, $config, $evm);
+    /**
+     * @ORM\Column(type="integer")
+     * @Gedmo\SortablePosition
+     */
+    public ?int $position = null;
+}
 ```
 
-**Note:** that Symfony StofDoctrineExtensionsBundle does it automatically this
-way you will maintain a single instance of annotation reader. It relates only
-to doctrine-common-2.1.x branch and newer.
+### Timestampable Extension
+
+The below annotations are used to configure the [Timestampable extension](./timestampable.md).
 
-<a name="gedmo-tree"></a>
+#### `@Gedmo\Mapping\Annotation\Timestampable`
 
-## Tree annotations
+The `Timestampable` annotation is a property annotation used to identify fields which are updated to record the
+timestamp of the update the mapped object. A timestampable field must be a field supporting a `DateTimeInterface`.
 
-Tree can use different adapters. Currently **Tree** extension supports **NestedSet**
-and **Closure** strategies which has a difference for annotations used. Note, that
-tree will automatically map indexes which are considered necessary for best performance.
+Required Attributes:
 
-### @Gedmo\Mapping\Annotation\Tree (required for all tree strategies)
+- **on** - By default, the annotation configures the property to be updated when an object is updated;
+  this can be set to one of \[`change`, `create`, `update`\]
 
-**class** annotation
+Optional Attributes:
 
-Is the main identificator of tree used for domain object which should **act as Tree**.
+- **field** - An optional list of properties to limit updates to the timestampable field; this option is only
+  used when the **on** option is set to "change" and can be a dot separated path to indicate
+  properties on a related object are watched (i.e. `user.email` to reference the `$email` property
+  of the `$user` relation on this object)
 
-**options:**
+- **value** - An optional value to require the configured **field** to match to update the timestampable field;
+  this option is only used when the **on** option is set to "change"
 
-- **type** - (string) _optional_ default: **nested**
+> [!WARNING]
+> When both the **field** and **value** options are set, the **field** can only be set to a single field; checking the value against multiple fields is not supported at this time
 
-example:
+Examples:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Tree(type="nested")
- * @Doctrine\ORM\Mapping\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @ORM\Entity
  */
-class Category ...
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     */
+    public ?string $title = null;
+
+    /**
+     * @ORM\Column(type="string")
+     */
+    public ?string $body = null;
+
+    /**
+     * @ORM\Column(type="datetime_immutable")
+     * @Gedmo\Timestampable(on="create")
+     */
+    public ?\DateTimeImmutable $createdAt = null;
+
+    /**
+     * @ORM\Column(type="datetime_immutable")
+     * @Gedmo\Timestampable(on="update")
+     */
+    public ?\DateTimeImmutable $updatedAt = null;
+
+    /**
+     * @ORM\Column(type="datetime_immutable", nullable=true)
+     * @Gedmo\Timestampable(on="change", field={"title", "body"})
+     */
+    public ?\DateTimeImmutable $contentChangedAt = null;
+}
 ```
 
-### @Gedmo\Mapping\Annotation\TreeParent (required for all tree strategies)
+### Translatable Extension
+
+The below annotations are used to configure the [Translatable extension](./translatable.md).
 
-**property** annotation
+#### `@Gedmo\Mapping\Annotation\TranslationEntity`
 
-This annotation forces to specify the **parent** field, which must be a **ManyToOne**
-relation
+The `TranslationEntity` annotation is a class annotation used to configure the class used to store translations
+for the translatable object.
 
-example:
+Required Attributes:
+
+- **class** - The class to use to define translations for this object; defaults to `Gedmo\Translatable\Entity\Translation`
+              for Doctrine ORM users or `Gedmo\Translatable\Document\Translation` for Doctrine MongoDB ODM users
+
+> [!TIP]
+> Although not strictly required, translation classes are encouraged to extend from the `AbstractPersonalTranslation` or `AbstractTranslation` classes in the `Gedmo\Translatable\<type>\MappedSuperclass` namespace
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TreeParent
- * @Doctrine\ORM\Mapping\ManyToOne(targetEntity="Category")
- * @Doctrine\ORM\Mapping\JoinColumn(name="parent_id", referencedColumnName="id", onDelete="CASCADE")
+ * @ORM\Entity
+ * @Gedmo\TranslationEntity(logEntryClass="App\Entity\ArticleTranslation")
  */
-private $parent;
+class Article {}
 ```
 
-### @Gedmo\Mapping\Annotation\TreeLeft (required for nested tree)
+#### `@Gedmo\Mapping\Annotation\Translatable`
 
-**property** annotation
+The `Translatable` annotation is a property annotation used to mark a field as being translatable.
 
-This annotation forces to specify the **left** field, which will be used for generation
-of nestedset left values. Property must be **integer** type.
+Optional Attributes:
 
-example:
+- **fallback** - When set to true, indicates this field should use the content of the original object if a translation
+                 is not available
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TreeLeft
- * @Doctrine\ORM\Mapping\Column(type=integer)
+ * @ORM\Entity
+ * @Gedmo\TranslationEntity(logEntryClass="App\Entity\ArticleTranslation")
  */
-private $lft;
-```
+class Article
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string", length=128)
+     * @Gedmo\Translatable
+     */
+    public ?string $title = null;
 
-### @Gedmo\Mapping\Annotation\TreeRight (required for nested tree)
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\Translatable(fallback=true)
+     */
+    public ?string $body = null;
+}
+```
 
-**property** annotation
+#### `@Gedmo\Mapping\Annotation\Locale`
 
-This annotation forces to specify the **right** field, which will be used for generation
-of nestedset right values. Property must be **integer** type.
+The `Locale` annotation is a property annotation used to indicate the field that the translation locale is stored on.
+This field must not be a mapped property (i.e. no `@ORM\Column` annotation).
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TreeRight
- * @Doctrine\ORM\Mapping\Column(type=integer)
+ * @ORM\Entity
+ * @Gedmo\TranslationEntity(logEntryClass="App\Entity\ArticleTranslation")
  */
-private $rgt;
+class Article
+{
+    /**
+     * @Gedmo\Locale
+     */
+    public ?string $locale = null;
+}
 ```
 
-### @Gedmo\Mapping\Annotation\TreeRoot (optional for nested tree)
+#### `@Gedmo\Mapping\Annotation\Language`
 
-**property** annotation
+The `Language` annotation is an alias of the `Locale` annotation.
 
-This annotation will use **integer** type field to specify the root of tree. This way
-updating tree will cost less because each root will act as separate tree.
+### Tree Extension
 
-example:
+The below annotations are used to configure the [Tree extension](./tree.md).
+
+#### All Tree Strategies
+
+##### `@Gedmo\Mapping\Annotation\Tree`
+
+The `Tree` annotation is a class annotation used to identify objects which are part of a tree implementation,
+all tree objects **MUST** have this annotation.
+
+Required Attributes:
+
+- **type** - The type of tree represented by this object, defaults to `nested`; supported values are:
+             \[`closure`, `materializedPath`, `nested`\]
+
+> [!WARNING]
+> Only the `materializedPath` tree type is supported for the MongoDB ODM at this time
+
+Optional Attributes:
+
+- **activateLocking** - Indicates that a materialized path tree should be locked during write transactions,
+                        defaults to true
+
+- **lockingTimeout** - The time (in seconds) for the lock timeout, defaults to 3
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TreeRoot
- * @Doctrine\ORM\Mapping\Column(type=integer, nullable=true)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree
  */
-private $root;
+class Category {}
 ```
 
-### @Gedmo\Mapping\Annotation\TreeLevel (optional for nested tree)
+##### `@Gedmo\Mapping\Annotation\TreeParent`
 
-**property** annotation
+The `TreeParent` annotation is a property annotation used to identify the relationship for a tree object to its parent.
+All tree objects **MUST** have this annotation and the annotation must be defined on a many-to-one relationship.
 
-This annotation lets to store the **level** of each node in the tree, in other word it
-is depth. Can be used for indentation for instance. Property must be **integer** type.
-
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TreeLevel
- * @Doctrine\ORM\Mapping\Column(type=integer)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree(type="nested")
  */
-private $lvl;
+class Category 
+{
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Category")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Gedmo\TreeParent
+     */
+    public ?self $parent = null;
+}
 ```
 
-### @Gedmo\Mapping\Annotation\TreeClosure (required for closure tree)
+#### Closure Tree Strategy
 
-**class** annotation
+##### `@Gedmo\Mapping\Annotation\TreeClosure`
 
-This annotation forces to specify the closure domain object, which must
-extend **AbstractClosure** in order to have personal closures.
+The `TreeClosure` annotation is a class annotation used to configure a closure domain object
+for a closure tree strategy.
 
-**options:**
+Required Attributes:
 
-- **class** - (string) _required_
+- **class** - The class to be used for the closure domain object, this must be a
+              subclass of `Gedmo\Tree\Entity\MappedSuperclass\AbstractClosure`
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Tree(type="closure")
- * @Gedmo\Mapping\Annotation\TreeClosure(class="Entity\CategoryClosure")
- * @Doctrine\ORM\Mapping\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\ClosureTreeRepository")
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\ClosureTreeRepository")
+ * @Gedmo\Tree
+ * @Gedmo\TreeClosure(class="App\Entity\CategoryClosure")
  */
-class Category ...
+class Category {}
 ```
 
-<a name="gedmo-translatable"></a>
+#### Materialized Path Strategy
 
-## Translatable annotations
+##### `@Gedmo\Mapping\Annotation\TreePath`
 
-Translatable additionally can have unmapped property, which would override the
-locale used by listener.
+The `TreePath` annotation is a property annotation used to identify the property that the calculated path is stored in.
 
-### @Gedmo\Mapping\Annotation\TranslationEntity (optional)
+Optional Attributes:
 
-**class** annotation
+- **separator** - The separator used to separate path segments, defaults to `,`
 
-This class annotation can force translatable to use **personal Entity** to store
-translations. In large tables this can be very handy.
+- **appendId** - Flag indicating the object ID should be appended to the computed path, defaults to `null`
 
-**options:**
+- **startsWithSeparator** - Flag indicating the path should begin with a separator, defaults to `false`
 
-- **class** - (string) _required_
+- **endsWithSeparator** - Flag indicating the path should end with a separator, defaults to `true`
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\TranslationEntity(class="Entity\ProductTranslation")
- * @Doctrine\ORM\Mapping\Entity
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\MaterializedPathRepository")
+ * @Gedmo\Tree(type="materializedPath")
  */
-class Product ...
+class Category 
+{
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\TreePath
+     */
+    public ?string $path = null;
+}
 ```
 
-### @Gedmo\Mapping\Annotation\Translatable (required in order to translate)
-
-**property** annotation
+##### `@Gedmo\Mapping\Annotation\TreePathSource`
 
-This annotation simply marks **any type** of field to be tracked and translated into
-currently used locale. Locale can be forced through entity or set by **TranslationListener**.
+The `TreePathSource` annotation is a property annotation used to identify the property that the tree path is
+calculated from.
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Translatable
- * @Doctrine\ORM\Mapping\Column(type=text)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\MaterializedPathRepository")
+ * @Gedmo\Tree(type="materializedPath")
  */
-private $content;
+class Category 
+{
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\TreePathSource
+     */
+    public ?string $title = null;
+}
 ```
 
-### @Gedmo\Mapping\Annotation\Locale or @Gedmo\Mapping\Annotation\Language (optional)
+##### `@Gedmo\Mapping\Annotation\TreePathHash`
 
-**unmapped property** annotation
+The `TreePathHash` annotation is a property annotation used to identify the property that a hash of the tree path is
+stored in.
 
-Both annotations will do exactly the same - mark property as one which can override
-the locale set by **TranslationListener**. Property must not be mapped, that means
-it cannot be stored in database.
-
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Locale
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\MaterializedPathRepository")
+ * @Gedmo\Tree(type="materializedPath")
  */
-private $locale;
+class Category 
+{
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\TreePathHash
+     */
+    public ?string $pathHash = null;
+}
 ```
 
-<a name="gedmo-sluggable"></a>
+##### `@Gedmo\Mapping\Annotation\TreeLockTime`
+
+> [!WARNING]
+> This annotation is only usable with the Doctrine MongoDB ODM
+
+The `TreeLockTime` annotation is a property annotation used to identify the property that the tree lock time is
+stored in. This must be a date field.
+
+Example:
 
-## Sluggable annotations
+```php
+<?php
+namespace App\Document;
 
-Sluggable ensures unique slugs and correct length of the slug. It also uses utf8 to ascii
-table map to create correct ascii slugs.
+use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
-### @Gedmo\Mapping\Annotation\Slug (required)
+/**
+ * @ODM\Document(repositoryClass="Gedmo\Tree\Document\MongoDB\Repository\MaterializedPathRepository")
+ * @Gedmo\Tree(type="materializedPath", activateLocking=true)
+ */
+class Category 
+{
+    /**
+     * @ODM\Field(type="date")
+     * @Gedmo\TreeLockTime
+     */
+    public ?\DateTime $treeLockTime = null;
+}
+```
 
-**property** annotation
+#### Nested Tree Strategy
 
-It will use this **string** property to store the generated slug.
+##### `@Gedmo\Mapping\Annotation\TreeRoot`
 
-**options:**
+The `TreeRoot` annotation is a property annotation used to identify the relationship for a tree object to its root node.
+This is an optional annotation for nested trees which improves performance and allows supporting multiple trees within
+a single table, and when used, the annotation must be defined on a many-to-one relationship.
 
-- **fields** - (array) _required_, must at least contain one field
-- **updatable** - (boolean) _optional_ default: **true**
-- **separator** - (string) _optional_ default: **-**
-- **unique** - (boolean) _optional_ default: **true**
-- **style** - (string) _optional_ default: **default** lowercase, can be **camel** also
-- **handlers** - (array) _optional_ default: empty array, refer to the documentation below, possible elements: **Gedmo\Mapping\Annotation\SlugHandler**
+This annotation will use **integer** type field to specify the root of tree. This way
+updating tree will cost less because each root will act as separate tree.
 
-### Slug handlers:
+Optional Attributes:
 
-- Gedmo\Sluggable\Handler\TreeSlugHandler - transforms a tree slug into path based, example "food/fruits/apricots/king-apricots"
-- Gedmo\Sluggable\Handler\RelativeSlugHandler - takes a relation slug and prefixes the slug, example "singers/michael-jackson"
-in order to synchronize updates regarding the relation changes, you will need to hood **InversedRelativeSlugHandler** to the relation mentioned.
-- Gedmo\Sluggable\Handler\InversedRelativeSlugHandler - updates prefixed slug for an inversed relation which is mapped by **RelativeSlugHandler**
+- **identifierMethod** - Allows specifying a a method on the related object to call to retrieve the identifier;
+                         when not configured, the root property value will be used
 
-examples:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Slug
- * @Doctrine\ORM\Mapping\Column(length=64, unique=true)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree(type="nested")
  */
-private $slug;
+class Category 
+{
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Category")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Gedmo\TreeRoot
+     */
+    public ?self $root = null;
+}
 ```
 
-with TreeSlugHandler
+##### `@Gedmo\Mapping\Annotation\TreeLeft`
+
+The `TreeLeft` annotation is a property annotation used to identify the field used to track the left value for a
+nested tree. This annotation **MUST** be set on a property when using the nested tree strategy and should use an
+integer field for its value.
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Slug(handlers={
- *      @Gedmo\Mapping\Annotation\SlugHandler(class="Gedmo\Sluggable\Handler\TreeSlugHandler", options={
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="parentRelationField", value="parent"),
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="separator", value="/")
- *      })
- * }, separator="-", updatable=true)
- * @Doctrine\ORM\Mapping\Column(length=64, unique=true)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree(type="nested")
  */
-private $slug;
+class Category 
+{
+    /**
+     * @ORM\Column(type="integer")
+     * @Gedmo\TreeLeft
+     */
+    public ?int $lft = null;
+}
 ```
 
-with **RelativeSlugHandler**:
+##### `@Gedmo\Mapping\Annotation\TreeRight`
+
+The `TreeRight` annotation is a property annotation used to identify the field used to track the right value for a
+nested tree. This annotation **MUST** be set on a property when using the nested tree strategy and should use an
+integer field for its value.
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * Person domain object class
- *
- * @Gedmo\Mapping\Annotation\Slug(handlers={
- *      @Gedmo\Mapping\Annotation\SlugHandler(class="Gedmo\Sluggable\Handler\RelativeSlugHandler", options={
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="relationField", value="category"),
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="relationSlugField", value="slug"),
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="separator", value="/")
- *      })
- * })
- * @Doctrine\ORM\Mapping\Column(length=64, unique=true)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree(type="nested")
  */
-private $slug;
+class Category 
+{
+    /**
+     * @ORM\Column(type="integer")
+     * @Gedmo\TreeRight
+     */
+    public ?int $rgt = null;
+}
 ```
 
-if you used **RelativeSlugHandler** - relation object should use **InversedRelativeSlugHandler**:
+##### `@Gedmo\Mapping\Annotation\TreeLevel`
+
+The `TreeLevel` annotation is a property annotation used to identify the field used to track the level for a
+nested tree. This is an optional annotation for nested trees, and when used, should use an integer field for its value.
+
+Optional Attributes:
+
+- **base** - Allows configuring the base level for objects in this tree, defaults to 0
+
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * Category domain object class
- *
- * @Gedmo\Mapping\Annotation\Slug(handlers={
- *      @Gedmo\Mapping\Annotation\SlugHandler(class="Gedmo\Sluggable\Handler\InversedRelativeSlugHandler", options={
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="relationClass", value="App\Entity\Person"),
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="mappedBy", value="category"),
- *          @Gedmo\Mapping\Annotation\SlugHandlerOption(name="inverseSlugField", value="slug")
- *      })
- * })
- * @Doctrine\ORM\Mapping\Column(length=64, unique=true)
+ * @ORM\Entity(repositoryClass="Gedmo\Tree\Entity\Repository\NestedTreeRepository")
+ * @Gedmo\Tree(type="nested")
  */
-private $slug;
+class Category 
+{
+    /**
+     * @ORM\Column(type="integer")
+     * @Gedmo\TreeLevel
+     */
+    public ?int $lvl = null;
+}
 ```
 
-<a name="gedmo-timestampable"></a>
+### Uploadable Extension
+
+The below annotations are used to configure the [Uploadable extension](./uploadable.md).
 
-## Timestampable annotations
+#### `@Gedmo\Mapping\Annotation\Uploadable`
 
-Timestampable will update date fields on create, update or property change. If you set/force
-date manually it will not update it.
+The `Uploadable` annotation is a class annotation used to identify objects which can store information about
+uploaded files.
 
-### @Gedmo\Mapping\Annotation\Timestampable (required)
+Optional Attributes:
 
-**property** annotation
+- **allowOverwrite** - Flag indicating that an existing uploaded file can be overwritten, defaults to `false`
 
-Marks a **date, datetime or time** field as timestampable.
+- **appendNumber** - Flag indicating that a number should be appended to the filename when the **allowOverwrite** 
+                     attribute is `true` and a file already exists, defaults to `false`
 
-**options:**
+- **path** - The file path to store files for this uploadable at; this must be configured unless the **pathMethod**
+             attribute is configured or a default path is set on the uploadable listener
 
-- **on** - (string) _optional_ default: **update**, other choice is **create** or **change**
-- **field** - (string) _conditional_ required only if it triggers on **change**, name of the **field**
-or if it is a relation **property.field**
-- **value** - (mixed) _conditional_ required only if it triggers on **change**, value of property
-which would trigger an update.
+- **pathMethod** - A method name on this class to use to retrieve the file path to store files for this uploadable;
+                   this must be configured unless the **path** attribute is configured or a default path is set on
+                   the uploadable listener
 
-example:
+- **callback** - A method name on this class to use to call after the file has been moved
+
+- **filenameGenerator** - A filename generator to use when moving the uploaded file to be used to normalize/customize
+                          the file name and defaults to `NONE`; supported styles are:
+    - `ALPHANUMERIC` - Normalizes the filename, leaving only alphanumeric characters
+    - `NONE` - No conversion
+    - `SHA1` - Creates a SHA1 hash of the filename
+    - A class name of a class implementing `Gedmo\Uploadable\FilenameGenerator\FilenameGeneratorInterface`
+
+- **maxSize** - An optional maximum file size for this uploadable object; defaults to `0`
+
+- **allowedTypes** - An optional list of allowed MIME types for this uploadable object;
+                     cannot be set at the same time as the **disallowedTypes** attribute
+
+- **disallowedTypes** - An optional list of disallowed MIME types for this uploadable object
+                        cannot be set at the same time as the **allowedTypes** attribute
+
+Example:
 
 ```php
 <?php
-/**
- * @Gedmo\Mapping\Annotation\Timestampable(on="create")
- * @Doctrine\ORM\Mapping\Column(type="datetime")
- */
-private $created;
+namespace App\Entity;
 
-/**
- * @Gedmo\Mapping\Annotation\Timestampable(on="change", field="status.title", value="Published")
- * @Doctrine\ORM\Mapping\Column(type="date")
- */
-private $published;
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
 /**
- * @Doctrine\ORM\Mapping\ManyToOne(targetEntity="Status")
+ * @ORM\Entity
+ * @Gedmo\Uploadable
  */
-private $status;
+class ArticleAttachment {}
 ```
 
-<a name="gedmo-loggable"></a>
+#### `@Gedmo\Mapping\Annotation\UploadableFileMimeType`
 
-## Loggable annotations
+The `UploadableFileMimeType` annotation is a property annotation used to identify the field that the uploadable's
+MIME type is stored to.
 
-Loggable is used to log all actions made on annotated object class, it logs insert, update
-and remove actions for a username which currently is logged in for instance.
-Further more, it stores all **Versioned** property changes in the log which allows
-a version management implementation for this object.
+Example:
+
+```php
+<?php
+namespace App\Entity;
 
-### @Gedmo\Mapping\Annotation\Loggable (required)
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
-**class** annotation
+/**
+ * @ORM\Entity
+ * @Gedmo\Uploadable
+ */
+class ArticleAttachment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
 
-This class annotation marks object as being loggable and logs all actions being done to
-this class records.
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\UploadableFileMimeType
+     */
+    public ?string $mimeType = null;
+}
+```
 
-**options:**
+#### `@Gedmo\Mapping\Annotation\UploadableFileName`
 
-- **logEntryClass** - (string) _optional_ personal log storage class
+The `UploadableFileName` annotation is a property annotation used to identify the field that the uploadable's
+file name is stored to.
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Loggable(logEntryClass="Entity\ProductLogEntry")
- * @Doctrine\ORM\Mapping\Entity
+ * @ORM\Entity
+ * @Gedmo\Uploadable
  */
-class Product ...
-```
+class ArticleAttachment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
 
-### @Gedmo\Mapping\Annotation\Versioned (optional)
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\UploadableFileName
+     */
+    public ?string $name = null;
+}
+```
 
-**property** annotation
+#### `@Gedmo\Mapping\Annotation\UploadableFilePath`
 
-Tracks the marked property for changes to be logged, can be set to single valued associations
-but not for collections. Using these log entries as revisions, objects can be reverted to
-a specific version.
+The `UploadableFilePath` annotation is a property annotation used to identify the field that the uploadable's
+file path is stored to.
 
-example:
+Example:
 
 ```php
 <?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
 /**
- * @Gedmo\Mapping\Annotation\Versioned
- * @Doctrine\ORM\Mapping\Column(type="text")
+ * @ORM\Entity
+ * @Gedmo\Uploadable
  */
-private $content;
+class ArticleAttachment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\UploadableFilePath
+     */
+    public ?string $path = null;
+}
+```
+
+#### `@Gedmo\Mapping\Annotation\UploadableFileSize`
+
+The `UploadableFileSize` annotation is a property annotation used to identify the field that the uploadable's
+file size is stored to. This must be a decimal field.
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
 
 /**
- * @Gedmo\Mapping\Annotation\Versioned
- * @Doctrine\ORM\Mapping\ManyToOne(targetEntity="Article", inversedBy="comments")
+ * @ORM\Entity
+ * @Gedmo\Uploadable
  */
-private $article;
+class ArticleAttachment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\Column(type="decimal")
+     * @Gedmo\UploadableFileSize
+     */
+    public ?string $size = null;
+}
 ```