docs: add guide for managing short URLs on AsyncAPI website #4491
Conversation
vishvamsinh28
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
asyncapi-bot-eve,
derberg and
thulieblack
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughThe pull request adds a new guide section to README.md documenting how to create and manage short URLs on the AsyncAPI website using Netlify redirects via the Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4491 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 780 780
Branches 144 144
=========================================
Hits 780 780 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-4491--asyncapi-website.netlify.app/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
README.md (1)
290-292: Expand redirect syntax documentation with working examples.The redirect syntax documentation is minimal and could benefit from more concrete examples. Line 292 shows the template format (
/short-path destination-url status-code!), but clarifying real-world usage would improve contributor understanding.Consider expanding this section with actual examples. For instance:
## 🧩 Redirect Syntax `/short-path destination-url status-code!` + +**Examples:** + +``` +/slack-invite https://slack.com/asyncapi-invite 302 +/modelina /tools/modelina 301 +/docs https://example.com/documentation 301 +``` + +- `/short-path`: The short URL path on the website +- `destination-url`: Full URL or relative path to redirect to +- `status-code!`: HTTP status code (301 for permanent, 302 for temporary; the `!` indicates a rewrite)This provides contributors with a clearer mental model of the syntax.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🔇 Additional comments (2)
README.md (2)
276-278: Thepublic/_redirectsfile exists and is properly tracked in the repository.Verification confirms that
public/_redirectsexists at the expected location with valid Netlify redirect rules. The README.md instructions at lines 276-278 correctly reference this file. No action is required.Likely an incorrect or invalid review comment.
221-293: No duplication found — original review comment is inaccurate.The search results confirm the short URLs guide appears only once in the README. All distinctive phrases from the section (lines 221-293) matched only within their expected location, with no instances elsewhere in the document. The AI summary's claim that "The content appears twice: once under the Case studies area and again later in the document" is incorrect. There is a single, isolated short URLs guide section between the Case studies section (ending at line 220) and JSON Schema definitions section (starting at line 294).
Likely an incorrect or invalid review comment.
|
@asyncapi/bounty_team |
|
hii @vishvamsinh28 |
derberg
left a comment
derberg
left a comment
There was a problem hiding this comment.
@vishvamsinh28 smells AI from a distance 😞
|
@derberg yes it is, but i think its good, isn’t it ? we already support short urls with the help of redirect thing. I also think it shouldn’t be part of bounty because there’s really not much work to do for this issue. |
|
generating docs with chatgpt is definitely not worth any money if you just copy/paste. see comment: #3005 (comment) what is worth the money is spending time on figuring out with other community members where such document should be located, what content is needed, maybe we need one simple short url as example - stuff like that that need extra effort. docs are like code, you need to align and design first to have good quality result 😉 |
README.md
Outdated
| A case study becomes publicly available right after merging and rebuilding the website. | ||
| # 🌐 Adding Short URLs to the AsyncAPI Website |
There was a problem hiding this comment.
Never use emojis in headings, they break anchor urls.
README.md
Outdated
| ## ✅ When to Create a Short URL | ||
| - **Community resources:** Slack, GitHub repositories | ||
| - **Frequently accessed tools:** AsyncAPI Studio, Generator, Modelina | ||
| - **Docs shortcuts:** Specification, Getting Started, Tutorials | ||
| - **Events & campaigns:** Conferences | ||
| ### Avoid Short URLs For | ||
| - Frequently changing internal pages | ||
| - Temporary content without clear end dates | ||
| - URLs that conflict with existing site routes | ||
| - Personal or private organization links | ||
| - Already short, self-explanatory URLs |
There was a problem hiding this comment.
I would move these sections above instead of lines 226-229, as they repeat the same information
README.md
Outdated
| - Personal or private organization links | ||
| - Already short, self-explanatory URLs | ||
| --- |
README.md
Outdated
| ### Step 1: Plan | ||
| 1. **Identify the target URL** you want to redirect to. | ||
| 2. **Choose a descriptive short path** (see naming conventions below). |
There was a problem hiding this comment.
see naming conventions below
Where? 🤔
There was a problem hiding this comment.
it was above not below 😅
README.md
Outdated
| 3. **Select the correct redirect type** — permanent (301) or temporary (302). | ||
| 4. **Check for conflicts** with existing routes or redirects. | ||
| ### Step 2: Edit the Redirects File |
There was a problem hiding this comment.
Some examples would be helpful here
README.md
Outdated
| ### Step 3: Submit and Test | ||
| 1. **Create a Pull Request (PR)** with your changes. | ||
| 2. Add **context in the PR description** — why this short URL is needed. |
There was a problem hiding this comment.
| 2. Add **context in the PR description** — why this short URL is needed. | |
| 2. Add **context in the PR description** describing why this short URL is needed. |
README.md
Outdated
| 1. **Identify the target URL** you want to redirect to. | ||
| 2. **Choose a descriptive short path** (see naming conventions below). | ||
| 3. **Select the correct redirect type** — permanent (301) or temporary (302). |
There was a problem hiding this comment.
| 3. **Select the correct redirect type** — permanent (301) or temporary (302). | |
| 3. **Select the appropriate redirect type**, for example, permanent (301) or temporary (302). |
README.md
Outdated
| 1. **Create a Pull Request (PR)** with your changes. | ||
| 2. Add **context in the PR description** — why this short URL is needed. | ||
| 3. **Test the redirect** after deployment to staging/production. |
There was a problem hiding this comment.
Do we have staging env?
README.md
Outdated
| 1. **Create a Pull Request (PR)** with your changes. | ||
| 2. Add **context in the PR description** — why this short URL is needed. | ||
| 3. **Test the redirect** after deployment to staging/production. | ||
| 4. **Monitor for issues** and update if necessary. |
There was a problem hiding this comment.
Does it mean that the author of a new short url will forever be its maintainer?
README.md
Outdated
| ## 🧩 Redirect Syntax | ||
| `/short-path destination-url status-code!` |
There was a problem hiding this comment.
This section should be a part of the step 2 of the guide above
vishvamsinh28
requested review from
anshgoyalevil and
sambhavgupta0705
as code owners
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
README.md (1)
288-293: Consider adding explicit staging environment testing guidance.Line 292 mentions testing "after deployment to production," but there's no guidance on testing in a staging environment first. Add a note clarifying the full testing workflow (test locally/in preview → deploy → verify in production) to align with best practices and address the staging question raised in previous review.
### Step 3: Submit and Test 1. **Create a Pull Request (PR)** with your changes. 2. Add **context in the PR description** describing why this short URL is needed. +3. **Test on the preview deployment** to ensure the redirect works as expected. -3. **Test the redirect** after deployment to production. -4. **Monitor for issues** - while the author isn't necessarily the permanent maintainer, they should help resolve any initial issues that arise. +4. **Test the redirect** after deployment to production. +5. **Monitor for issues** - while the author isn't necessarily the permanent maintainer, they should help resolve any initial issues that arise.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.md(1 hunks)config/adopters.json(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- config/adopters.json
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2025-07-19T20:58:34.040Z
Learnt from: bandantonio
Repo: asyncapi/website PR: 4264
File: markdown/docs/tutorials/getting-started/coming-from-openapi.md:24-25
Timestamp: 2025-07-19T20:58:34.040Z
Learning: In the AsyncAPI website documentation, anchor references to specification sections can use camelCase format (e.g., #serverObject, #parameterObject, #messageObject) even if the actual HTML IDs on the spec page use hyphenated lowercase format. This is acceptable and should not be changed.
Applied to files:
README.md
📚 Learning: 2025-01-19T04:51:41.255Z
Learnt from: anshgoyalevil
Repo: asyncapi/website PR: 3557
File: tests/fixtures/markdown/check-edit-links-data.js:3-11
Timestamp: 2025-01-19T04:51:41.255Z
Learning: In the AsyncAPI website repository, the test data in `tests/fixtures/markdown/check-edit-links-data.js` intentionally includes inconsistent paths (with and without 'docs' prefix) to verify the script's ability to normalize and handle ambiguous path structures.
Applied to files:
README.md
📚 Learning: 2024-11-13T20:34:18.998Z
Learnt from: bandantonio
Repo: asyncapi/website PR: 3393
File: markdown/blog/2024-Q1-docs-report.md:10-12
Timestamp: 2024-11-13T20:34:18.998Z
Learning: In the markdown files for the AsyncAPI website, avatar image paths should be referenced without the `public` prefix (e.g., use `/img/avatars/...` instead of `/public/img/avatars/...`).
Applied to files:
README.md
📚 Learning: 2025-01-14T14:58:38.076Z
Learnt from: anshgoyalevil
Repo: asyncapi/website PR: 3557
File: tests/markdown/check-edit-links.test.js:20-46
Timestamp: 2025-01-14T14:58:38.076Z
Learning: In the AsyncAPI website codebase, the edit-page-config.json contains a fallback match entry that ensures determineEditLink function always has a valid target.value, making null checks unnecessary.
Applied to files:
README.md
🪛 markdownlint-cli2 (0.18.1)
README.md
280-280: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Test NodeJS PR - macos-13
- GitHub Check: Test NodeJS PR - windows-latest
🔇 Additional comments (1)
README.md (1)
221-224: Guide structure and introduction are well done.The section provides a clear overview of the short URL feature with practical context about use cases and benefits. The organization (when to use → how to use → step-by-step guide) is logical and easy to follow.
8 participants
Update readme to add a guide explaining how to create, organize, and maintain short URLs using Netlify redirects (public/_redirects).
#3005
Summary by CodeRabbit