docs: update add-provider.mdx

.github/workflows/publish-docs.yml

@@ -3,7 +3,7 @@ name: Publish Documentation
 on:
     push:
         paths: [ 'docs/**' ]
-        branches-ignore: [ demo-instance ]
+        branches: [ develop ]
 
 jobs:
     build:

docs/astro.config.mjs

@@ -1,6 +1,8 @@
 // @ts-check
 import {defineConfig} from 'astro/config'
 import starlight from '@astrojs/starlight'
+import starlightLinksValidator from 'starlight-links-validator'
+import mermaid from "astro-mermaid"
 
 const BASE_URL = 'https://domainwatchdog.eu'
 
@@ -25,8 +27,12 @@ export default defineConfig({
             sidebar: [
                 {label: 'Getting started', slug: 'features'},
                 {
-                    label: 'Self hosting',
-                    autogenerate: {directory: 'self-hosting'},
+                    label: 'Installation & Configuration',
+                    items: [
+                        {label: 'Installation', autogenerate: {directory: 'install-config/install'}},
+                        {slug: 'install-config/configuration'},
+                        {slug: 'install-config/upgrade'},
+                    ]
                 },
                 {
                     label: 'Features',
@@ -44,10 +50,9 @@ export default defineConfig({
                         {slug: 'developing/translation'},
                         {label: 'Contributing', autogenerate: {directory: 'developing/contributing'}}
                     ],
-                    collapsed: true
                 },
-                {label: 'Legal', autogenerate: {directory: 'legal'}, collapsed: true}
-
+                {label: 'Legal', autogenerate: {directory: 'legal'}, collapsed: true},
+                {slug: 'acknowledgment'}
             ],
             locales: {
                 en: {
@@ -106,7 +111,11 @@ _paq.push(['enableHeartBeatTimer']);
     s.parentNode.insertBefore(g, s);
 })();`
                 }
-            ]
-        })
+            ],
+            plugins: [starlightLinksValidator({
+                errorOnLocalLinks: false
+            })]
+        }),
+        mermaid()
     ]
 })

docs/package.json

@@ -18,6 +18,10 @@
   "dependencies": {
     "@astrojs/starlight": "^0.36.2",
     "astro": "^5.6.1",
-    "sharp": "^0.34.2"
+    "astro-mermaid": "^1.1.0",
+    "mermaid": "^11.12.1",
+    "sharp": "^0.34.2",
+    "starlight-contributor-list": "^0.3.1",
+    "starlight-links-validator": "^0.19.1"
   }
-}
+}

docs/src/content/docs/en/acknowledgment.mdx

@@ -0,0 +1,11 @@
+---
+title: Acknowledgment
+---
+import { ContributorList } from "starlight-contributor-list"
+
+## Contributors
+
+A huge thank-you to everyone who has contributed to this project!
+Your ideas, bug reports, code improvements, and translations all help make this project better for everyone.
+
+<ContributorList githubRepo="maelgangloff/domain-watchdog" ignore={['weblate']} />

docs/src/content/docs/en/developing/add-provider.md

@@ -1,3 +0,0 @@
----
-title: Add a provider
----

docs/src/content/docs/en/developing/add-provider.mdx

@@ -0,0 +1,220 @@
+---
+title: Add a Provider
+---
+import {FileTree, Steps, Code, LinkCard} from "@astrojs/starlight/components";
+
+This project aims to be compatible with as many registrars as possible, giving users a choice when creating a Connector.
+
+::::caution
+Only registrars with a public and documented API can be offered. Using a registrar's private API is strictly prohibited.
+::::
+
+Adding a new Provider is straightforward. Simply follow the steps below.
+
+This guide explains how to add support for a new domain registrar.
+You’ll implement both the Backend (Provider logic) and the Frontend (configuration form).
+
+## Prerequisites
+
+<Steps>
+1. Read the API documentation of the new Provider and identify the sections related to user authentication and domain name registration.
+1. Set up your development environment.
+    <LinkCard title="Manual Installation" href="/en/install-config/install/manual-install" description='Install the project from source to begin development' />
+</Steps>
+
+## Backend
+
+In this section, you’ll implement the logic required to interact with the new Provider’s API.
+
+<Steps>
+    1. Create a new DTO class to validate user authentication data.
+        <FileTree>
+            - src
+              - Dto.Connector
+                - DefaultProviderDto.php default DTO, which will also be used
+                - **MySuperRegistrarProviderDto.php** your new DTO class
+        </FileTree>
+
+    1. Add the necessary class properties and assertions.
+       The DTO class must extend `DefaultProviderDto`.
+
+        Only include properties required for user authentication, domain name registration, and any legally required consents.
+        <Code code={`namespace App\\Dto\\Connector;
+
+            class MySuperRegistrarProviderDto extends DefaultProviderDto
+        `} lang="php" title='MySuperRegistrarProviderDto.php' mark={['extends DefaultProviderDto']} />
+
+    1. Create a new Provider class.
+        <FileTree>
+            - src
+              - Service
+                - Provider
+                  - AbstractProvider.php                defines the signature of methods
+                  - **MySuperRegistrarProvider.php**    your new Provider
+        </FileTree>
+
+    1. The class must extend `AbstractProvider`.
+        Refer to the existing Providers for implementation examples.
+        <Code code={`namespace App\\Service\\Provider;
+
+        #[Autoconfigure(public: true)]
+        class MySuperRegistrarProvider extends AbstractProvider
+        {
+            protected string $dtoClass = MySuperRegistrarProviderDto::class;
+
+            /** @var MySuperRegistrarProviderDto */
+            protected DefaultProviderDto $authData;
+        `} lang="php" title='MySuperRegistrarProvider.php' mark={['extends AbstractProvider']} />
+       ::::note
+        You now need to implement the methods defined in `AbstractProvider`.
+
+        Refer to the official Provider API documentation as needed.
+        ::::
+
+    1. Implement the `assertAuthentication` method.
+
+       This method validates user authentication data.
+       Make a request to the Provider’s API to verify that the user’s credentials are valid.
+
+       The method must return `void` when authentication succeeds.
+       ::::tip
+       If an issue occurs, throw an appropriate exception from the `App\Exception\Provider` namespace.
+       ::::
+        <Code code={`
+        protected function assertAuthentication(): void
+        {
+            // TODO: Implement assertAuthentication() method.
+        }`} lang="php" title='MySuperRegistrarProvider.php' mark={['protected function assertAuthentication()']} />
+
+    1. Implement the `getCachedTldList` method.
+        <Code code={`
+        protected function getCachedTldList(): CacheItemInterface
+        {
+            return $this->cacheItemPool->getItem('app.provider.my-super-registrar.supported-tld');
+        }`} lang="php" title='MySuperRegistrarProvider.php' mark={['my-super-registrar']} />
+
+        This method returns the cache entry holding the list of TLDs supported by this Provider.
+        Even if the API does not currently provide this information, implement the method for future compatibility.
+
+    1. Implement the `getSupportedTldList` method.
+
+        If the Provider API does not offer a way to retrieve supported TLDs, return an empty array `[]`.
+        Otherwise, call the API and return the list of supported TLDs.
+        <Code code={`
+        protected function getSupportedTldList(): array
+        {
+            // TODO: Implement getSupportedTldList() method.
+        }`} lang="php" title='MySuperRegistrarProvider.php' />
+
+    1. Implement the `isSupported` method (if necessary).
+        Override `isSupported` **only if** the Provider API cannot list supported TLDs. In that case, return `true` to indicate that all TLDs are potentially valid.
+
+    1. Implement the `orderDomain` method.
+
+        Follow the Provider's API documentation to implement domain ordering using the required properties.
+        ::::tip
+        As with authentication, you may throw generic Provider exceptions in case of an error.
+        ::::
+        <Code code={`
+        public function orderDomain(Domain $domain, bool $dryRun): void
+        {
+            // TODO: Implement orderDomain() method.
+        }`} lang="php" title='MySuperRegistrarProvider.php' />
+
+    1. Add your Provider to the `ConnectorProvider` enumeration.
+        <Code code={`
+        namespace App\Config;
+
+        enum ConnectorProvider: string
+        {
+            // ...
+            case MY_SUPER_REGISTRAR = 'my-super-registrar';
+
+            public function getConnectorProvider(): string
+            {
+                return match ($this) {
+                    // ...
+                    ConnectorProvider::MY_SUPER_REGISTRAR => MySuperRegistrarProvider::class,
+            };
+        }`} lang="php" title='src/Config/ConnectorProvider.php' />
+</Steps>
+
+**Well done!** 🎉
+You have now completed the Backend implementation.
+Let’s continue with the Frontend! 🚀
+
+## Frontend
+
+<Steps>
+    1. Create a form containing the necessary fields for your Provider.
+        <FileTree>
+            - assets
+              - utils
+                - providers
+                  - forms
+                    - DefaultConnectorFormItems.tsx             fields shared by all
+                    - **MySuperRegistrarConnectorForm.tsx**
+        </FileTree>
+
+    1. Add the fields corresponding to the DTO you created earlier.
+       Check existing forms for reference.
+       If the Provider API does not allow retrieving supported TLDs, display this information as in the other forms.
+
+    1. Add your Provider to the `ConnectorProvider` enumeration.
+       The value must exactly match the one defined in PHP.
+
+       <Code code={`
+        export enum ConnectorProvider {
+            // ...
+            MY_SUPER_REGISTRAR = 'my-super-registrar'
+        }`} lang="ts" title='assets/utils/api/connectors.ts' />
+
+    1. Add the API terms of service link and the reference to your new form in the `index.ts` configuration file.
+        <Code code={`
+        export const providersConfig: Record<ConnectorProvider, ProviderConfig> = {
+            // ...
+            [ConnectorProvider.MY_SUPER_REGISTRAR]: {
+                tosLink: 'https://...',
+                form: MySuperRegistrarConnectorForm
+            }
+        }`} lang="ts" title='assets/utils/providers/index.ts' />
+
+    1. Ensure the interface renders correctly and fix any display issues.
+</Steps>
+
+**Great job!** 🎉
+Your Frontend implementation is now complete.
+
+## Testing
+
+<Steps>
+    1. Add the corresponding test function in the Provider test collection.
+        <Code code={`
+        #[DependsExternal(RDAPServiceTest::class, 'testUpdateRdapServers')]
+        public function testMySuperRegistrar()
+        {
+            $token = static::getContainer()->getParameter('my_super_registrar_token');
+            if (!$token) {
+                $this->markTestSkipped('Missing My Super Registrar token');
+            }
+
+            $this->testGenericProvider(ConnectorProvider::MY_SUPER_REGISTRAR, [
+                'waiveRetractationPeriod' => true,
+                'acceptConditions' => true,
+                'ownerLegalAge' => true,
+                'token' => $token,
+            ]);
+        }`} lang="php" title='tests/Service/Provider/AbstractProviderTest.php' />
+
+    1. Create a Symfony configuration parameter connecting the environment variable to the credentials.
+
+    1. Run the tests with PHPUnit:
+        ```shell
+        php vendor/bin/phpunit
+        ```
+    1. Ensure the test passes.
+    If it fails, fix the implementation accordingly.
+    Consider enabling code coverage to identify executed sections.
+</Steps>
+
+That's it! You’ve now finished implementing a new Provider. ✨

docs/src/content/docs/en/features/backorder/connector.mdx

@@ -11,7 +11,7 @@ domain registration.
 
 <Steps>
 1. Choose an external API provider from the list of supported registrars.
-    <LinkCard title="Supported registrar" description="List of supported registrars for creating a Connector" href="../supported-registrar"/>
+    <LinkCard title="Supported registrar" description="List of supported registrars for creating a Connector" href="/en/features/backorder/supported-registrar"/>
 2. Enter the required information using the credentials obtained from your provider’s customer area
     :::tip{icon="heart"}
     A link allows you to directly access the Provider's page to retrieve this authentication information

docs/src/content/docs/en/features/index.mdx

@@ -43,7 +43,7 @@ To read the documentation related to domain name search, please click on the lin
 
 <LinkCard title="Domain search"
           description="Obtain the details of a domain name registration and the history of observed events"
-          href="../features/search/domain-search"/>
+          href="/en/features/search/domain-search"/>
 :::
 
 ---
@@ -63,7 +63,7 @@ To read the documentation related to the Watchlist, please click on the link bel
 
 <LinkCard title="Watchlist"
           description="Add domain names to a Watchlist to track them, be notified of any changes, and potentially buy them when they expire"
-          href="../features/tracking/watchlist"/>
+          href="/en/features/tracking/watchlist"/>
 :::
 
 ### Watchlist notifications
@@ -84,14 +84,14 @@ To read the documentation related to Connector, please click on the link below.
 
 <LinkCard title="Connector"
           description="Create a Connector to enable domain name purchases by linking it to your Watchlists"
-          href="../features/backorder/connector"/>
+          href="/en/features/backorder/connector"/>
 :::
 
 ### Supported registrar list
 
 <LinkCard title="Supported registrar list"
           description="List of registrars supported by this project"
-          href="../features/backorder/supported-registrar"/>
+          href="/en/features/backorder/supported-registrar"/>
 
 ---
 
@@ -107,5 +107,5 @@ To read the documentation related to the Tracking table, please click on the lin
 
 <LinkCard title="Tracking table"
           description="List all the domains you're monitoring in your Watchlist and track the status of those domains"
-          href="../features/tracking/tracking-table"/>
+          href="/en/features/tracking/tracking-table"/>
 :::

docs/src/content/docs/en/install-config/configuration.mdx

@@ -4,7 +4,7 @@ title: Configuration
 
 import {LinkCard} from '@astrojs/starlight/components';
 
-<LinkCard title="Install with Docker" href="../docker-install"/>
+<LinkCard title="Install with Docker" href="/en/install-config/install/docker-compose"/>
 
 ## Environment variables
 

docs/src/content/docs/en/install-config/install/docker-compose.mdx

@@ -1,12 +1,12 @@
 ---
-title: Install with Docker
+title: Docker Compose installation
 ---
 
 import {LinkCard} from '@astrojs/starlight/components';
 
 1. Download the [docker-compose.yml](https://github.com/maelgangloff/domain-watchdog/blob/develop/docker-compose.yml) and modify it as needed
 2. Download the [.env](https://github.com/maelgangloff/domain-watchdog/blob/develop/.env) and modify it as needed
-<LinkCard title="Configuration" description="List of environment variables" href="../configuration/#environment-variables"/>
+<LinkCard title="Configuration" description="List of environment variables" href="/en/install-config/configuration/#environment-variables"/>
 
 3. Add static files to customize your instance (under `public/content`)
 4. Pull the latest version of the Domain Watchdog image from Docker Hub

docs/src/content/docs/en/install-config/install/manual-install.mdx

@@ -1,15 +1,13 @@
 ---
-title: Manual Install
+title: Manual installation
 ---
 
 import {FileTree, LinkCard, Steps} from '@astrojs/starlight/components';
 
-## Installation
-
 To deploy a Domain Watchdog instance, please refer to the Symfony documentation
 on [How to deploy a Symfony application](https://symfony.com/doc/current/deployment.html).
 
-### Prerequisites
+## Prerequisites
 
 - PHP 8.4 or higher
 - PostgreSQL 16 or higher
@@ -19,7 +17,7 @@ It is crucial that the Domain Watchdog instance is placed in a clean environment
 queried.
 In particular, the DNS servers and root certificates of the system must be trusted.
 
-### Steps
+## Steps
 
 Clone the repository:
 
@@ -27,7 +25,7 @@ Clone the repository:
 git clone https://github.com/maelgangloff/domain-watchdog.git
 ```
 
-#### Backend
+### Backend
 
 <Steps>
 1. Install dependencies
@@ -38,7 +36,7 @@ git clone https://github.com/maelgangloff/domain-watchdog.git
     ```shell
     cp .env .env.local
     ```
-    <LinkCard title="Configuration" description="List of environment variables" href="../configuration"/>
+    <LinkCard title="Configuration" description="List of environment variables" href="/en/install-config/configuration"/>
 
 3. Generate the cryptographic key pair for the JWT signature
     ```shell
@@ -59,7 +57,7 @@ git clone https://github.com/maelgangloff/domain-watchdog.git
 7. Don't forget to set up workers to process the [message queue](https://symfony.com/doc/current/messenger.html)
 </Steps>
 
-#### Frontend
+### Frontend
 
 <Steps>
 1. Install dependencies
@@ -87,51 +85,3 @@ git clone https://github.com/maelgangloff/domain-watchdog.git
                 - favicon.ico
     </FileTree>
 </Steps>
-
-## Update
-
-**Any updates are your responsibility. Make a backup of the data if necessary.**
-
-Fetch updates from the remote repository:
-
-```shell
-git pull origin master
-```
-
-### Backend
-
-<Steps>
-1. Install dependencies
-    ```shell
-    composer install
-    ```
-2. Run database migrations
-    ```shell
-    php bin/console doctrine:migrations:migrate
-    ```
-3. Clearing the Symfony cache
-    ```shell
-    php bin/console cache:clear
-    ```
-4. Build assets
-    ```shell
-    php bin/console assets:install
-    ```
-</Steps>
-
-### Frontend
-
-<Steps>
-1. Install dependencies
-    ```shell
-    yarn install
-    ```
-2. Generate language files
-    ```shell
-    yarn run ttag:po2json
-    ```
-3. Make the final build
-    ```shell
-    yarn build
-    ```
-</Steps>

docs/src/content/docs/en/install-config/upgrade.mdx

@@ -0,0 +1,50 @@
+---
+title: Manual Upgrade
+---
+import {Steps} from "@astrojs/starlight/components";
+
+**Any updates are your responsibility. Make a backup of the data if necessary.**
+
+Fetch updates from the remote repository:
+
+```shell
+git pull origin master
+```
+
+## Backend
+
+<Steps>
+1. Install dependencies
+    ```shell
+    composer install
+    ```
+2. Run database migrations
+    ```shell
+    php bin/console doctrine:migrations:migrate
+    ```
+3. Clearing the Symfony cache
+    ```shell
+    php bin/console cache:clear
+    ```
+4. Build assets
+    ```shell
+    php bin/console assets:install
+    ```
+</Steps>
+
+## Frontend
+
+<Steps>
+1. Install dependencies
+    ```shell
+    yarn install
+    ```
+2. Generate language files
+    ```shell
+    yarn run ttag:po2json
+    ```
+3. Make the final build
+    ```shell
+    yarn build
+    ```
+</Steps>