Improve and re-organize documentation

[kalinkostashki]

• restructured sidebar to be more user friendly and intuitive
• fixed not working links to pages
• added a common writing style for all pages
• added an indexed search via pagefind

[thjaeckle]

Documentation Content Integrity Review

Disclosure: This is a quick LLM-assisted analysis of the proposed changes — comparing old vs. new content across all 132 changed files to check whether the essence of the documented content is preserved. Manual verification of flagged items is recommended.

PR summary: Restructures sidebar, applies consistent writing style (TL;DR callouts, "Overview / How it works / Further reading" pattern), adds pagefind search. +8437/-12631 lines across 132 files.

Good news: No pages were dropped from the sidebar. All 291 URLs are preserved. Five new operating pages were added. The structural reorganization is clean (14 top-level sections → 10 logical groupings).

---

HIGH CONCERN — Significant technical content removed

These should be reviewed to decide if the removed content should be restored (e.g. as collapsible sections):

1. connectivity-mapping.md — Heaviest losses in the PR

• Full Java FooMapper class implementation → replaced with 3-line method summary
• Complete JavaScript helper implementations (buildDittoProtocolMsg, buildTopic, buildExternalMsg, arrayBufferToString, etc.) → replaced with function signatures only
• Full mapFromDittoProtocolMsgWrapper default impl (with hasChannel() logic, multi-content-type handling) → replaced with stub comment
• ConnectionStatus mapper feature JSON example with definition removed
• Normalized mapper _deleted event example and _deletedFields example removed
• RawMessage mapper complete before/after worked example (AMQP/MQTT message with hex bytes + headers) → replaced with table
• UpdateTwinWithLiveResponse mapper dittoHeadersForMerge/put-metadata config example removed
• Text/Bytes payload examples with mosquitto_pub command and hex byte-layout explanation removed
• ByteBuffer.js usage examples removed

2. connectivity-hmac-signing.md

• Full HOCON config block for algorithm registration removed
• Readable standalone JavaScript mapping functions for AWS SNS, S3, Azure IoT Hub, Azure Service Bus → removed (only inline compressed versions remain in JSON)
• Azure IoT Hub direct method JSON example and live message curl command removed
• Explicit parameter descriptions for each integration removed
• Algorithm/connection-type compatibility matrix removed

3. Protocol specification Things pages (create-or-modify, retrieve, delete, merge)

• All four sub-pages gutted to redirect stubs — content consolidated into protocol-specification-things.md
• Full Response/Event tables (topic, path, value, status per command) → reduced to one-line summaries
• Nuances lost: when value field is present vs. absent in responses, created-vs-modified event conditional logic

4. user-interface.md

• Complete TypeScript type definitions for AuthSettings, OidcProviderConfiguration, BasicAuthSettings, BearerAuthSettings, PreAuthSettings, AuthMethod enum → all removed
• local_ditto_ide pre-auth environment example removed
• oidc_example with full OIDC provider config (authority, client_id, redirect_uri, scope) removed
• post_logout_redirect_uri and silent refresh callback requirement removed

5. intro-hello-world.md

• Full 7-feature floor lamp Thing JSON (Spot1-3, ConnectionStatus, PowerConsumption, SmokeDetection, Status-LED) → removed entirely
• Explanation of attributes vs. features vs. definition removed
• Concrete org.eclipse.ditto:fancy-car example replaced with generic placeholders (no longer copy-pasteable)

6. basic-connections.md

• Response diversion examples with full JavaScript determineTargetConnection mapper function removed
• Target topics enrichment table (which topics support extraFields) removed
• nginx: prefix operational note for auth subjects removed
• Custom ack label in source config example dropped

7. basic-acknowledgements.md

• "HTTP cannot issue acks" note removed entirely
• WebSocket/connection label conflict warning removed
• Detailed QoS subsections (twin-persisted, live-response, custom label) reduced to bullet list
• Response headers (version, etag, location) removed from success example

---

MEDIUM CONCERN — Useful detail lost

File	What was lost
basic-signals.md	CQRS/DDD quotes from cqrs.nu removed; sub-page navigation links removed
basic-metadata.md	Combined wildcard+specific metadata example removed; /features-level wildcard table removed
basic-history.md	next/complete protocol message JSON examples removed
basic-conditional-requests.md	Empty-object removal before/after example removed; /features-level conditional merge removed
basic-search.md	Array query ne operator examples removed; limit(0,10) introductory example removed
httpapi-concepts.md	4 of 6 field selector worked examples with JSON responses removed
protocol-specification-things-messages.md	"Received message" and "message response" full JSON examples removed
connectivity-protocol-bindings-amqp10.md	Source-direction header mapping examples for amqp.application.property: prefix removed
connectivity-protocol-bindings-http.md	Full OAuth2 HOCON config with env variable overrides removed; implicit response field docs lost
connectivity-protocol-bindings-mqtt.md	reconnectForRedelivery false-case caveat removed; AWS IoT QoS 2 note removed
connectivity-protocol-bindings-mqtt5.md	clientCount collision detailed explanation removed; reconnectForRedelivery caveat removed
connectivity-protocol-bindings-kafka2.md	Debug-mode RecordMetadata fields list removed
installation-extending.md	Full gateway.conf health-check default config with env var override removed
client-sdk-java.md	Pekko streams integration example removed

---

LOW CONCERN / Corrections (likely intentional)

• basic-feature.md: "future releases will add processing" → "this is your application's responsibility" (likely intentional update)
• basic-connections.md: Target auth subject fixed from ditto:inbound-auth-subject to ditto:outbound-auth-subject (bug fix)
• protocol-specification.md: Custom header prefix example changed from ditto-* to myapp-* (correction — ditto-* is reserved)
• basic-overview.md: "API version 2" qualifier removed (v1 no longer exists)
• operating-mongodb.md and operating-monitoring.md: New files but empty — placeholder only