DX Guide: Using Organization Slugs in URLs #1664
Conversation
izaaklauer
force-pushed
the
izaak/orgs-132-dx-guide
branch
from
7fa4f9e to
edf0892
Compare
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/1664 |
docs/guides/using-org-slugs.mdx
Outdated
| > links with their coworkers. Public documentation, marketing, and third-party blogs are also | ||
| > made easier to write if links aren't tied to any specific organization. |
There was a problem hiding this comment.
Does this feel clear enough to folks? If not, I can add an example. It would be something like:
For example, if someone is writing a public post that includes a link to settings, if that link is
/orgs/acmecorp/settings, it will only be useful to employees of Acmecorp! If the URL is just/settings, then it's universally applicable and automatically contextualized into the click-er's organization by virtue of the organization encoded on the Clerk session.
docs/guides/using-org-slugs.mdx
Outdated
| > Skipping organization activation. | ||
| > [!CAUTION] | ||
| > It is ultimately the responsibility of the page to ensure that it renders the appropriate content for a given URL, and |
There was a problem hiding this comment.
IMO those "caution" blocks can be a bit alarming to developers. I'd suggest removing this block and putting more specific guidance with comments on the code block below.
There was a problem hiding this comment.
Agree with Laura. We should avoid having multiple callouts especially ones that are lengthy.
There was a problem hiding this comment.
I'll be honest, inspiring mild alarm in the reader is what I was going for. If a developer were to just look at the organization slug in the URL, assume this meant that the middleware authorized access to the org, then render some sensitive org-specific content from their backend, that would be a very bad bug.
Hey @brkalow , do you happen to have an opinion on the best way to communicate this one?
Thank you @LauraBeatris for the suggestions! Co-authored-by: victoria <github@victoriahchang.com> Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com>
Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com>
There was a problem hiding this comment.
🏅 Looking good! I'll leave the rest of the feedback here to @victoriaxyz
victoriaxyz
left a comment
victoriaxyz
left a comment
There was a problem hiding this comment.
Looking great! 🎉
Some notes:
- headings should be in active voice
- use contractions for verbs
- avoid using too many callouts
Thank you @victoriaxyz and @alexisintech for the suggestions! Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Co-authored-by: victoria <github@victoriahchang.com>
Co-authored-by: victoria <github@victoriahchang.com> Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Co-authored-by: victoria <github@victoriahchang.com> Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
alexisintech
force-pushed
the
izaak/orgs-132-dx-guide
branch
from
0df3fd6 to
5d7de1a
Compare
Co-authored-by: victoria <github@victoriahchang.com>
Thanks victoria! #1664 (comment)
Thanks alexis and victoria!
I think this is more descriptive for the body anyway. Context: https://clerkinc.slack.com/archives/C078JFZLLQ3/p1734561625263129?thread_ts=1734560220.385059&cid=C078JFZLLQ3
Thanks @Laura! Laura Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com>
|
Hey @izaaklauer, here are my update: 3957f81 and ba9a40b
|
Preview: https://clerk.com/docs/pr/1664/organizations/org-slugs-in-urls
✅ Depends on https://github.com/clerk/clerk-docs/pull/1634/files
✅ Depends on publication of https://github.com/clerk/orgs
What changed?
This adds a new DX guide based on new middleware options (introduced in clerk/javascript#3977) for managing the active clerk organization with URL patterns.