[GitHub] [pulsar] labuladong opened a new issue, #18026: [Doc][improve] Auto-detect broken links and integrate into CI process

[GitBox]

labuladong opened a new issue, #18026:
URL: https://github.com/apache/pulsar/issues/18026

   ### Search before asking
   
   - [X] I searched in the [issues](https://github.com/apache/pulsar/issues) 
and found nothing similar.
   
   
   ### What issue do you find in Pulsar docs?
   
   After #17495 and #17599, we can see many broken links in the Pulsar 
document. And more links may break during further evolution.
   
   ### What is your suggestion?
   
   In #17599 I use a script but it's not reliable enough so I have to check the 
links list manually. I suggest developing a reliable script to auto-detect the 
incorrect links in the Pulsar document. Maybe we can integrate this script into 
the CI process which is related to document change.
   
   Before development, I'd like to enumerate all kinds of broken links.
   
   ### 1. wrong markdown file reference
   
   For example the link of [this 
page](https://pulsar.apache.org/docs/next/admin-api-tenants/#get-configuration):
   
   <img width="573" alt="image" 
src="https://user-images.githubusercontent.com/37220920/195486126-e8a3de23-4cc5-4319-a11f-7c222b2a1b4a.png";>
   
   The markdown content is `[configuration](reference-configuration.md)`, but 
the `reference-configuration.md` file not exists.
   
   ### 2. 404 URL path
   
   For example the link of [this 
page](https://pulsar.apache.org/docs/next/client-libraries-websocket/#query-param):
   
   <img width="827" alt="image" 
src="https://user-images.githubusercontent.com/37220920/195486601-aea69e74-005d-4c2c-8fb1-02fcc80d1f9c.png";>
   
   The markdown content is 
`[type](/api/client/index.html?org/apache/pulsar/client/api/CompressionType.html)`,
 but the Pulsar site doesn't have this path.
   
   
   ### 3. confusing URL path
   
   For example the link of [this 
page](https://pulsar.apache.org/docs/next/functions-debug-cli/):
   
   
![image](https://user-images.githubusercontent.com/37220920/195486878-5c44cfea-7b16-4bac-87cc-210f2ac0ca33.png)
   
   The markdown content is `[Pulsar Functions CLI](/tools/pulsar-admin/)`, but 
this refers to a confusing page:
   
   <img width="582" alt="image" 
src="https://user-images.githubusercontent.com/37220920/195488231-79bb5f13-e832-415b-81f5-36c0330908b4.png";>
   
   
   ### 4. invalid title anchor
   
   We can use `#` to refer to a specific block of HTML this way: 
`[dataDir](reference-configuration.md#zookeeper-dataDir)`. So if our script can 
detect the anchor will be better.
   
   Our script should be able to detect these broken links and print warning 
messages to users.
   
   cc @tisonkun @Anonymitaet @momo-jun @michaeljmarshall 
   
   
   
   ### Any reference?
   
   _No response_
   
   ### Are you willing to submit a PR?
   
   - [X] I'm willing to submit a PR!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@pulsar.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org