DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
...
We store Kafka version specific documentation under {{docs}} folder in the corresponding branch of core kafka repo: Convert the html source files as specified above and update the docs directory with their markdown equivalents. We will do this for the following branches:
| Documentation Directory | Github Branch |
|---|
...
| "39" | 3.9 |
...
...
| "38" | 3.8 |
...
...
| "37" | 3.7 |
...
...
| "36" | 3.6 |
...
...
| "35" | 3.5 |
...
...
| "34" | 3.4 |
...
...
| "33" | 3.3 |
...
...
| "32" | 3.2 |
...
...
| "31" | 3.1 |
...
...
| "30" | 3 |
| "28" | 2.8 |
...
...
| "27" | 2.7 |
...
...
| "26" | 2.6 |
...
...
| "25" | 2.5 |
...
...
| "24" | 2.4 |
...
...
| "23" | 2.3 |
...
...
| "22" | 2.2 |
...
...
| "21" | 2.1 |
...
...
| "20" | 2 |
| "11" | 1.1 |
...
...
| "10" | 1 |
| "0110" | 0.11.0 |
...
...
| "0102" | 0.10.2 |
...
...
| "0101" | 0.10.1 |
...
...
| "0100" | 0.10.0 |
...
...
| "090" | 0.9.0 |
...
...
| "082" | 0.8.2 |
...
...
| "081" | 0.8.1 |
...
...
| "08" | 0.8 |
...
...
| "07" | 0.7 |
...
Sample directory layout:{
| Code Block |
|---|
...
docs/ |
...
├── _index.md |
...
├── |
...
apis │ ├── _index.md |
...
│ └── api.md |
...
├── |
...
configuration │ ├── _index.md |
...
│ └── configuration.md |
...
├── |
...
design │ ├── _index.md |
...
│ ├── design.md |
...
│ └── protocol.md |
...
├── getting-started |
...
│ ├── _index.md |
...
│ ├── docker.md |
...
│ ├── ecosystem.md |
...
│ ├── introduction.md |
...
│ ├── quickstart.md |
...
│ ├── upgrade.md |
...
│ └── uses.md |
...
├── |
...
implementation │ ├── _index.md |
...
│ ├── distribution.md |
...
│ ├── log.md |
...
│ ├── message-format.md |
...
│ ├── messages.md |
...
│ └── network-layer.md |
...
├── kafka-connect |
...
│ ├── _index.md |
...
│ ├── administration.md |
...
│ ├── connector-development-guide.md |
...
│ ├── overview.md |
...
│ └── user-guide.md |
...
├── |
...
operations │ ├── _index.md |
...
│ ├── basic-kafka-operations.md |
...
│ ├── datacenters.md |
...
│ ├── enter-migration-mode-on-the-brokers.md |
...
│ ├── finalizing-the-migration.md |
...
│ ├── geo-replication-(cross-cluster-data-mirroring).md |
...
│ ├── hardware-and-os.md |
...
│ ├── java-version.md |
...
│ ├── kafka-configuration.md |
...
│ ├── kraft.md |
...
│ ├── limitations.md |
...
│ ├── migrating-brokers-to-kraft.md |
...
│ ├── migration-phases.md |
...
│ ├── monitoring.md |
...
│ ├── multi-tenancy.md |
...
│ ├── preparing-for-migration.md |
...
│ ├── provisioning-the-kraft-controller-quorum.md |
...
│ ├── reverting-to-zookeeper-mode-during-the-migration.md |
...
│ ├── terminology.md |
...
│ ├── tiered-storage.md |
...
│ └── zookeeper.md |
...
├── |
...
security │ ├── _index.md |
...
│ ├── authentication-using-sasl.md |
...
│ ├── authorization-and-acls.md |
...
│ ├── encryption-and-authentication-using-ssl.md |
...
│ ├── incorporating-security-features-in-a-running-cluster.md |
...
│ ├── listener-configuration.md |
...
│ ├── security-overview.md |
...
│ ├── zookeeper-authentication.md |
...
│ └── zookeeper-encryption.md |
...
└── |
...
streams ├── _index.md |
...
├── architecture.md |
...
├── core-concepts.md |
...
├── developer-guide |
...
│ ├── _index.md |
...
│ ├── app-reset-tool.md |
...
│ ├── config-streams.md |
...
│ ├── datatypes.md │ ├── dsl-api.md |
...
│ ├── dsl-topology-naming.md |
...
│ ├── interactive-queries.md |
...
│ ├── manage-topics.md |
...
│ ├── memory-mgmt.md |
...
│ ├── processor-api.md |
...
│ ├── running-app.md |
...
│ ├── security.md │ ├── testing.md │ └── write-streams-app.md |
...
├── introduction.md |
...
├── quickstart.md |
...
├── tutorial.md |
...
└── upgrade-guide.md |
{code}
...
Build and Deployment
Leverage {{hugo}} and {{docsy}} toolchain to generate static html website from markdown source. Package the website as a docker container and host it behind existing website serving infrastructure.
...
- Compatibility: This change is not expected to impact the compatibility of Apache Kafka itself. It only affects the documentation website.
- Deprecation: The existing HTML-based documentation website will be deprecated once the new Markdown-based version is launched.
- Migration Plan:
- Complete the conversion of any remaining HTML documentation to Markdown.
- Thoroughly test the migrated documentation to ensure accuracy and consistency.
- Deploy the new documentation website.
- Update any relevant links or references to the documentation.
Test Plan
...
Write automation to ensure all html source files are converted to markdown. Manual testing to ensure completeness, correctness and required functionality is present in the new website. Run broken link checker to verify that internal links within the documentation are correct.
Rejected Alternatives
- Maintaining the Status Quo: Continuing with the current raw HTML approach is not sustainable due to the issues outlined in the "Motivation" section.
- Alternative Static Site Generators: While other static site generators exist, Hugo was chosen for its popularity, maturity, and strong community support. The Docsy theme aligns well with the needs of technical documentation.
...