MQTT docs updates and fixes (#105)

* MQTT docs updates and fixes

- clean up outputs
- update link recommendation
- fix double spaces
- update kafka proxy conent and sidebar
- update the mqtt intro configs
- update route exit yaml example
- point to new quickstart folder (#94)
- Remove capabilities (#103)
- Add server to options (#102)
- update the new feature tag
- boostrap fixes
- add mqtt kafka proxy
- add mqtt instructions for the quickstart

* update mqtt quickstart instructions

* add topic descriptions and links in the quickstart

* update links

* update logo images and Intro text

* update quickstart for clarity

* update urls

* remove local build and update landing page wording

* wording length changes

.config/vale/styles/Vocab/Base/accept.txt

@@ -1,17 +1,18 @@
+(?i)config
+(?i)datacenter
 (?i)http
 (?i)https
 (?i)jwt
 (?i)keystore
+(?i)middleware
+(?i)otlp
 (?i)pkcs12
 (?i)prometheus
+(?i)proxying
+(?i)realtime
 (?i)subnet(s)?
 (?i)todo
 (?i)truststore
-(?i)proxying
-(?i)realtime
-(?i)datacenter
-(?i)middleware
-(?i)config
 (?i)yaml
 acks
 Aiven
@@ -23,13 +24,15 @@ artifacthub
 Bidi
 bitnami
 BOMs
+CA(s)?
 cleartext
 CLIs
 config
 confluentinc
 CQRS
 cspell
 datagram
+declaratively
 docsearch
 etag
 fanout
@@ -38,6 +41,8 @@ gitea
 grpc
 grpcurl
 GSSAPI
+heroImage
+heroText
 hostname
 http
 idempotency
@@ -88,6 +93,3 @@ yaml
 Zilla
 zpm
 zpmw
-heroImage
-heroText
-declaratively

.github/contributing/writing-guide.md

@@ -19,7 +19,7 @@ The docs will be organized according to the [Diataxis](https://diataxis.fr/) fra
 
 The Diataxis framework will dictate what content should be created and and keep the conent scoped to a purpose: Tutorials, How-Tos, Concepts, Reference.
 
-The user navigation can be a collection of any content organized by primary feature. This way a user can find the solution to their problem and  see different kinds of content all related to that solution.
+The user navigation can be a collection of any content organized by primary feature. This way a user can find the solution to their problem and see different kinds of content all related to that solution.
 
 ### File structure
 
@@ -62,6 +62,33 @@ Your users need reference material because they need truth and certainty - firm
 - **Get Started**: This is where users will start and learn what they need to be successful
 - **Reference**: This is an echo of the Diataxis definition and should remain as dry and generated as possible. The structure is set up for direct linking to individual components that readers may need more context on. Each component should have some sort of example to give context for it's usage
 
+### Links and References
+
+Links to other md files should use the local files path reference to the new document in order for any file render to correctly add links.
+
+- `[grpc-kafka](../../reference/config/bindings/binding-grpc-kafka.md)`
+
+When referencing specific attributes of the Zilla api always use and highlight the syntactically correct words found in the reference docs or config. Add any extra descriptive words before or after.
+
+- `[grpc-kafka](../../reference/config/bindings/binding-grpc-kafka.md) Binding`
+- `[jwt](../../reference/config/guards/guard-jwt.md) Guard`
+- `[produce capability](../../reference/config/bindings/binding-grpc-kafka.md#produce-capability)`
+
+[Reference-style links](https://www.markdownguide.org/basic-syntax/#reference-style-links) should only be used to clarify reading the raw text document when it is needed. This should be used in lists, tables, or complicated paragraphs. When used the reference definition should be placed in a group with other references and as close the the usage as makes sense. Exact highlighted context should be used unless there is a case when reuse of the same link is needed in the same section.
+
+Good examples improve readability without adding extra work for a plain text reader:
+
+- [vuejs-example]
+- [github-example]
+
+A bad example has no consistency which doesn't improve readability while navigation and maintenance are worse:
+
+- [electron-example]
+
+[vuejs-example]: https://github.com/vuejs/vue/blob/main/README.md?plain=1
+[github-example]: https://github.com/github/gitignore/blob/main/README.md?plain=1
+[electron-example]: https://github.com/electron/electron/blob/main/docs/faq.md?plain=1
+
 ## Writing & Grammar
 
 ### Style

README.md

@@ -2,8 +2,8 @@
 
 <!-- markdownlint-disable -->
 <div align="center">
-  <img src="./src/.vuepress/public/logo-dark.png#gh-light-mode-only" height="100">
-  <img src="./src/.vuepress/public/logo.png#gh-dark-mode-only" height="100">
+  <img src="./src/.vuepress/public/logo.png#gh-light-mode-only" height="100">
+  <img src="./src/.vuepress/public/logo-dark.png#gh-dark-mode-only" height="100">
 </div>
 
 </br>

src/.vuepress/sidebar/en.ts

@@ -119,11 +119,11 @@ export const enSidebar = sidebar({
       ],
     },
     {
-      text: "Apache Kafka Proxying",
+      text: "Kafka Proxying",
       link: "concepts/kafka-proxies/rest-proxy.md",
       children: [
         {
-          text: "REST-Kafka Proxy",
+          text: "REST Kafka Proxy",
           collapsible: true,
           link: "concepts/kafka-proxies/rest-proxy.md",
           children: [
@@ -152,7 +152,7 @@ export const enSidebar = sidebar({
           ],
         },
         {
-          text: "SSE-Kafka Proxy",
+          text: "SSE Kafka Proxy",
           collapsible: true,
           link: "concepts/kafka-proxies/sse-proxy.md",
           children: [
@@ -181,7 +181,7 @@ export const enSidebar = sidebar({
           ],
         },
         {
-          text: "gRPC-Kafka Proxy",
+          text: "gRPC Kafka Proxy",
           collapsible: true,
           link: "concepts/kafka-proxies/grpc-proxy.md",
           children: [
@@ -195,6 +195,25 @@ export const enSidebar = sidebar({
             },
           ],
         },
+        {
+          text: "MQTT Kafka Proxy",
+          collapsible: true,
+          link: "concepts/kafka-proxies/mqtt-proxy.md",
+          children: [
+            {
+              text: "Overview",
+              link: "concepts/kafka-proxies/mqtt-proxy.md",
+            },
+            {
+              text: "Run the Taxi Demo",
+              link: "https://github.com/aklivity/zilla-demos/tree/main/taxi",
+            },
+            {
+              text: "Create a Simple MQTT Broker",
+              link: "tutorials/mqtt/mqtt-intro.md",
+            }
+          ],
+        },
         {
           text: "Amazon MSK Pubic Proxy",
           collapsible: true,

src/.vuepress/styles/index.scss

@@ -104,3 +104,25 @@ table.no-head {
     }
 
 }
+
+
+.language-output {
+    border-radius: 0px !important;
+    background: transparent !important;
+
+    pre {
+        border-inline-start: 0.2rem solid #333;
+        margin: 1rem 0;
+        padding: 0.25rem 0 0.25rem 1rem;
+        font-size: 1rem;
+        overflow-wrap: break-word;
+        code {
+            color: #666 !important;
+
+        }
+    }
+
+    .copy-code-button {
+        display: none;
+    }
+}

src/.vuepress/theme.ts

@@ -5,8 +5,8 @@ import { hostnameSEO, docsRepo, docsBranch } from "./env.js";
 
 export default hopeTheme({
   hostname: hostnameSEO,
-  logo: "/logo-dark.png",
-  logoDark: "/logo.png",
+  logo: "/logo.png",
+  logoDark: "/logo-dark.png",
   iconAssets: "fontawesome-with-brands",
   favicon: "favicon.ico",
 

src/README.md

@@ -2,10 +2,10 @@
 home: true
 icon: home
 title: Home
-heroImage: /zilla-rings@2x.png
-heroImageDark: /zilla-rings@2x.png
+heroImage: /zilla-rings.webp
+heroImageDark: /zilla-rings.webp
 heroText: Introduction
-tagline: Zilla is an API Gateway for event-driven architectures. It securely interfaces web apps, IoT clients, and microservices to Apache Kafka® via declaratively defined API endpoints.
+tagline: Zilla is a multi-protocol, edge and service proxy. It abstracts Apache Kafka® for non-native clients, such as browsers and IoT devices, by exposing Kafka topics via user-defined REST, Server-Sent Events (SSE), MQTT, or gRPC API entry points.
 actions:
   - text: Quickstart
     link: /tutorials/quickstart/kafka-proxies.md

src/concepts/kafka-proxies/grpc-proxy.md

@@ -2,7 +2,7 @@
 description: This guide will walk through each unique gRPC message request and response design and how Zilla is configured to manage the connection for each.
 ---
 
-# gRPC Proxy
+# gRPC Kafka Proxy
 
 This guide will walk through each unique gRPC message request and response design and how Zilla is configured to manage the connection for each.