Skip to content

Commit 4c8d0ed

Browse files
authored
MINOR: Make Quickstart command examples copy-friendly (#23526)
This patch improves the copy usability of the Quickstart command examples by ensuring copied commands can be pasted directly into a shell without including prompts, terminal output, or interactive input. Currently, some Bash code blocks mix executable commands with shell prompts, terminal output, or interactive input. Since the website copy button copies the entire code block, the copied content is not always directly executable. ### Changes - Remove `$` prompts from executable command blocks. - Separate terminal output from executable commands. - Separate interactive input from the console producer command. This change is intentionally limited to the Quickstart so the formatting approach can be reviewed before applying it more broadly. Reviewers: Ming-Yen Chung <mingyen066@gmail.com>, Parker Chang <parkerhiphop027@gmail.com>, Ken Huang <s7133700@gmail.com>
1 parent af804b9 commit 4c8d0ed

1 file changed

Lines changed: 49 additions & 24 deletions

File tree

‎docs/getting-started/quickstart.md‎

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ type: docs
3131
[Download](https://www.apache.org/dyn/closer.cgi?path=/kafka/4.3.0/kafka_2.13-4.3.0.tgz) the latest Kafka release and extract it:
3232

3333
```bash
34-
$ tar -xzf kafka_2.13-4.3.0.tgz
35-
$ cd kafka_2.13-4.3.0
34+
tar -xzf kafka_2.13-4.3.0.tgz
35+
cd kafka_2.13-4.3.0
3636
```
3737

3838
## Step 2: Start the Kafka environment
@@ -46,19 +46,19 @@ Kafka can be run using local scripts and downloaded files or the docker image.
4646
Generate a Cluster UUID
4747

4848
```bash
49-
$ KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
49+
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
5050
```
5151

5252
Format Log Directories
5353

5454
```bash
55-
$ bin/kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID -c config/server.properties
55+
bin/kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID -c config/server.properties
5656
```
5757

5858
Start the Kafka Server
5959

6060
```bash
61-
$ bin/kafka-server-start.sh config/server.properties
61+
bin/kafka-server-start.sh config/server.properties
6262
```
6363

6464
Once the Kafka server has successfully launched, you will have a basic Kafka environment running and ready to use.
@@ -68,27 +68,27 @@ Once the Kafka server has successfully launched, you will have a basic Kafka env
6868
Get the Docker image:
6969

7070
```bash
71-
$ docker pull apache/kafka:4.3.0
71+
docker pull apache/kafka:4.3.0
7272
```
7373

7474
Start the Kafka Docker container:
7575

7676
```bash
77-
$ docker run -p 9092:9092 apache/kafka:4.3.0
77+
docker run -p 9092:9092 apache/kafka:4.3.0
7878
```
7979

8080
### Using GraalVM Based Native Apache Kafka Docker Image
8181

8282
Get the Docker image:
8383

8484
```bash
85-
$ docker pull apache/kafka-native:4.3.0
85+
docker pull apache/kafka-native:4.3.0
8686
```
8787

8888
Start the Kafka Docker container:
8989

9090
```bash
91-
$ docker run -p 9092:9092 apache/kafka-native:4.3.0
91+
docker run -p 9092:9092 apache/kafka-native:4.3.0
9292
```
9393

9494
## Step 3: Create a topic to store your events
@@ -100,13 +100,18 @@ Example events are payment transactions, geolocation updates from mobile phones,
100100
So before you can write your first events, you must create a topic. Open another terminal session and run:
101101

102102
```bash
103-
$ bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092
103+
bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092
104104
```
105105

106106
All of Kafka's command line tools have additional options: run the `kafka-topics.sh` command without any arguments to display usage information. For example, it can also show you [details such as the partition count](/{version}/getting-started/introduction/#main-concepts-and-terminology) of the new topic:
107107

108108
```bash
109-
$ bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092
109+
bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092
110+
```
111+
112+
The output should look similar to:
113+
114+
```text
110115
Topic: quickstart-events TopicId: NPmZHyhbR9y00wMglMH2sg PartitionCount: 1 ReplicationFactor: 1 Configs:
111116
Topic: quickstart-events Partition: 0 Leader: 0 Replicas: 0 Isr: 0
112117
```
@@ -118,9 +123,14 @@ A Kafka client communicates with the Kafka brokers via the network for writing (
118123
Run the console producer client to write a few events into your topic. By default, each line you enter will result in a separate event being written to the topic.
119124

120125
```bash
121-
$ bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
122-
>This is my first event
123-
>This is my second event
126+
bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
127+
```
128+
129+
When the `>` prompt appears, enter a few events, one per line:
130+
131+
```text
132+
This is my first event
133+
This is my second event
124134
```
125135

126136
You can stop the producer client with `Ctrl-C` at any time.
@@ -130,7 +140,12 @@ You can stop the producer client with `Ctrl-C` at any time.
130140
Open another terminal session and run the console consumer client to read the events you just created:
131141

132142
```bash
133-
$ bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
143+
bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
144+
```
145+
146+
Example output:
147+
148+
```text
134149
This is my first event
135150
This is my second event
136151
```
@@ -152,43 +167,53 @@ First, make sure to add `connect-file-4.3.0.jar` to the `plugin.path` property i
152167
Edit the `config/connect-standalone.properties` file, add or change the `plugin.path` configuration property match the following, and save the file:
153168

154169
```bash
155-
$ echo "plugin.path=libs/connect-file-4.3.0.jar" >> config/connect-standalone.properties
170+
echo "plugin.path=libs/connect-file-4.3.0.jar" >> config/connect-standalone.properties
156171
```
157172

158173
Then, start by creating some seed data to test with:
159174

160175
```bash
161-
$ echo -e "foo
176+
echo -e "foo
162177
bar" > test.txt
163178
```
164179

165180
Or on Windows:
166181

167182
```bash
168-
$ echo foo > test.txt
169-
$ echo bar >> test.txt
183+
echo foo > test.txt
184+
echo bar >> test.txt
170185
```
171186

172187
Next, we'll start two connectors running in _standalone_ mode, which means they run in a single, local, dedicated process. We provide three configuration files as parameters. The first is always the configuration for the Kafka Connect process, containing common configuration such as the Kafka brokers to connect to and the serialization format for data. The remaining configuration files each specify a connector to create. These files include a unique connector name, the connector class to instantiate, and any other configuration required by the connector.
173188

174189
```bash
175-
$ bin/connect-standalone.sh config/connect-standalone.properties config/connect-file-source.properties config/connect-file-sink.properties
190+
bin/connect-standalone.sh config/connect-standalone.properties config/connect-file-source.properties config/connect-file-sink.properties
176191
```
177192

178193
These sample configuration files, included with Kafka, use the default local cluster configuration you started earlier and create two connectors: the first is a source connector that reads lines from an input file and produces each to a Kafka topic and the second is a sink connector that reads messages from a Kafka topic and produces each as a line in an output file.
179194

180195
During startup you'll see a number of log messages, including some indicating that the connectors are being instantiated. Once the Kafka Connect process has started, the source connector should start reading lines from `test.txt` and producing them to the topic `connect-test`, and the sink connector should start reading messages from the topic `connect-test` and write them to the file `test.sink.txt`. We can verify the data has been delivered through the entire pipeline by examining the contents of the output file:
181196

182197
```bash
183-
$ more test.sink.txt
198+
more test.sink.txt
199+
```
200+
201+
Example output:
202+
203+
```text
184204
foo
185205
bar
186206
```
187207

188208
Note that the data is being stored in the Kafka topic `connect-test`, so we can also run a console consumer to see the data in the topic (or use custom consumer code to process it):
189209

190210
```bash
191-
$ bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning
211+
bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning
212+
```
213+
214+
Example output:
215+
216+
```text
192217
{"schema":{"type":"string","optional":false},"payload":"foo"}
193218
{"schema":{"type":"string","optional":false},"payload":"bar"}
194219
…
@@ -197,7 +222,7 @@ $ bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connec
197222
The connectors continue to process data, so we can add data to the file and see it move through the pipeline:
198223

199224
```bash
200-
$ echo "Another line" >> test.txt
225+
echo "Another line" >> test.txt
201226
```
202227

203228
You should see the line appear in the console consumer output and in the sink file.
@@ -233,7 +258,7 @@ Now that you reached the end of the quickstart, feel free to tear down the Kafka
233258
If you also want to delete any data of your local Kafka environment including any events you have created along the way, run the command:
234259

235260
```bash
236-
$ rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs
261+
rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs
237262
```
238263

239264
## Congratulations!

0 commit comments

Comments
 (0)