asyncapi / asyncapi/markdown-template

[Bug] Incorrect server rendering in AsyncAPI v3: protocol prefix added (`kafka://`) instead of just host

Open Beginner friendly
#658 4 comments 0 reactions 0 assignees View on GitHub
bug stale
Dominant language
JavaScript
Stars
36
Forks
38
Avg merge
3m
Merged PRs (30d)
3

Description

### Describe the bug.

When generating Markdown documentation from an AsyncAPI v3.0.0 specification using `@asyncapi/markdown-template@2.0.0`, the server section renders the full URL with protocol prefix (e.g., `kafka://kafka.example.com:9092/`) instead of just the `host` value as defined in the v3 spec (`kafka.example.com:9092`).

This is incorrect because AsyncAPI v3.0.0 uses separate `host` (required) and `pathname` (optional) fields, with `protocol` separate — no combined `url` with protocol prefix like in v2.

### Expected behavior

The server should render as:
**Host:** `kafka.example.com:9092`
**Protocol:** `kafka`

No `kafka://` prefix or trailing `/` should appear unless `pathname` is defined.

### Screenshots

Image

### How to Reproduce

1. Use this minimal AsyncAPI v3.0.0 YAML file (`asyncapi.yaml`):

```yaml
asyncapi: '3.0.0'
id: 'urn:example:com:demo:app'
info:
title: Demo Event-Driven API
version: '1.0.0'
servers:
production:
host: kafka.example.com:9092
protocol: kafka
description: Production Kafka broker
channels:
userSignedUp:
address: user/signedup
messages:
UserSignedUp:
$ref: '#/components/messages/UserSignedUp'
operations:
sendUserSignedUp:
action: send
channel:
$ref: '#/channels/userSignedUp'
messages:
- $ref: '#/channels/userSignedUp/messages/UserSignedUp'
components:
messages:
UserSignedUp:
name: UserSignedUp
title: User Signed Up Event
contentType: application/json
payload:
type: object
properties:
userId: { type: string, description: Unique user identifier }
email: { type: string, format: email }
required: [userId, email]
```
2 .Generate Markdown documentation using the latest template:
```yaml
npx -p @asyncapi/cli \
asyncapi generate fromTemplate \
asyncapi.yaml \
@asyncapi/markdown-template \
-o output-md
```
3. Open the generated file: output-md/asyncapi.md

**Observed result:**
In the Servers section, it shows:
URL: `kafka://kafka.example.com:9092/`
**Expected:**
Host: `kafka.example.com:9092`

### 🖥️ Device Information [optional]

- Operating System (OS): Windows(WSL2)
- Browser: Chrome(Latest)
- Browser Version: Latest

### 👀 Have you checked for similar open issues?

- [x] I checked and didn't find similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue ?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue with the minimal asyncapi.yaml and the documented AsyncAPI CLI command, then inspect output-md/asyncapi.md in the Servers section. Done means the output shows Host as kafka.example.com:9092 and Protocol as kafka, without a protocol prefix or trailing slash unless pathname is defined.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nodejs
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.