docs: no em-dashes in header article and new guide pages

[oleksandr-kazimirov]

Typography pass on the new header docs: em-dash character removed everywhere (plain hyphens and colons instead), article title uses a colon, article body synced with the published dev.to version and links back to it. mkdocs build --strict passes.

Summary by CodeRabbit

• Documentation
  • Expanded Kafka record header guidance, including writing headers, numeric and null-value handling, topic opt-in behavior, forwarding, compatibility, and deployment guidance.
  • Clarified header APIs, encoding choices, builder overloads, testing guidance, and protocol compatibility.
  • Standardized punctuation, formatting, and line wrapping across article, guide, and landing pages.

[coderabbitai]

Walkthrough

Documentation updates expand Kafka record header guidance, covering writing, encoding, null values, opt-in forwarding, protocol compatibility, testing, and upgrades. Other documentation pages receive punctuation and formatting normalization.

Changes

Kafka header documentation

Layer / File(s)	Summary
Header usage and semantics docs/articles/kafka-record-headers.md, docs/guides/kafka-headers.md	Documents header writing, encoding choices, null handling, accessors, forwarding behavior, and per-topic opt-in capture.
Testing and compatibility guidance docs/articles/kafka-record-headers.md, docs/guides/kafka-headers.md	Updates capture testing, byte-exact validation, additive protocol compatibility, upgrade guidance, and reference links.
Site copy punctuation normalization docs/articles/index.md, docs/guides/kafka-io.md, docs/index.md	Normalizes dash punctuation, line wrapping, and formatting across article indexes, Kafka I/O guidance, and the documentation landing page.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• kzmlabs/flink-statefun#266: Introduced or announced the Kafka record header documentation expanded by this PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main docs typography cleanup across the header article and guide pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/no-emdash-article

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/articles/kafka-record-headers.md`:
- Line 56: The accessor nullability guarantee is too broad: update the note at
docs/articles/kafka-record-headers.md lines 56-56 to apply only to
value-decoding accessors, preserving the non-null key() and boolean hasValue()
contracts; align the corresponding note at docs/guides/kafka-headers.md lines
100-100 with the accessor table, with no other changes.
- Line 95: Replace “zero overhead” with “no header allocation or payload
overhead” in the header-less path description, while preserving the note that
opt-in and header-count checks still occur. Apply this wording in
docs/articles/kafka-record-headers.md at lines 95-95 and
docs/guides/kafka-headers.md at lines 54-56.

In `@docs/guides/kafka-headers.md`:
- Around line 218-219: Update the documentation near the repeated header field
description to state that has_value distinguishes Kafka null values from empty
byte arrays: false preserves null, while true allows an empty value.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8f020e19-7351-4aab-9054-a8f1c7951b21

📥 Commits

Reviewing files that changed from the base of the PR and between 62f2a97 and d8eed82.

📒 Files selected for processing (5)

• docs/articles/index.md
• docs/articles/kafka-record-headers.md
• docs/guides/kafka-headers.md
• docs/guides/kafka-io.md
• docs/index.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

The accessor nullability guarantee is overbroad in both documents.

key() and hasValue() have non-null/boolean contracts; only value-decoding accessors should be described as returning null for null or undecodable values.

• docs/articles/kafka-record-headers.md#L56-L56: limit the guarantee to value accessors.
• docs/guides/kafka-headers.md#L100-L100: align the note with the accessor table.

📍 Affects 2 files

• docs/articles/kafka-record-headers.md#L56-L56 (this comment)
• docs/guides/kafka-headers.md#L100-L100

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/articles/kafka-record-headers.md` at line 56, The accessor nullability
guarantee is too broad: update the note at docs/articles/kafka-record-headers.md
lines 56-56 to apply only to value-decoding accessors, preserving the non-null
key() and boolean hasValue() contracts; align the corresponding note at
docs/guides/kafka-headers.md lines 100-100 with the accessor table, with no
other changes.

[coderabbitai]

🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

Replace “zero overhead” with the narrower implementation guarantee.

The code avoids header metadata allocation and wire payload overhead on the header-less path, but still performs opt-in/header-count checks.

• docs/articles/kafka-record-headers.md#L95-L95: state “no header allocation or payload overhead.”
• docs/guides/kafka-headers.md#L54-L56: use the same wording.

📍 Affects 2 files

• docs/articles/kafka-record-headers.md#L95-L95 (this comment)
• docs/guides/kafka-headers.md#L54-L56

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/articles/kafka-record-headers.md` at line 95, Replace “zero overhead”
with “no header allocation or payload overhead” in the header-less path
description, while preserving the note that opt-in and header-count checks still
occur. Apply this wording in docs/articles/kafka-record-headers.md at lines
95-95 and docs/guides/kafka-headers.md at lines 54-56.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Describe has_value as distinguishing null from empty.

The flag represents whether a header has a value: false preserves Kafka’s null value, while true permits an empty byte array. It does not distinguish “empty from absent” as written.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/kafka-headers.md` around lines 218 - 219, Update the
documentation near the repeated header field description to state that has_value
distinguishes Kafka null values from empty byte arrays: false preserves null,
while true allows an empty value.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!