[Docs Mintlify] - Updates and new additions#1401
Open
madster456 wants to merge 5 commits into
Open
Conversation
… known-errors, and revamped self-host
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedReview was skipped due to path filters ⛔ Files ignored due to path filters (1)
CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for the Stack CLI and local emulator, establishes a known-errors reference guide, restructures the self-hosting guide toward production deployments, and replaces under-construction placeholders with detailed local-development and showcase content. Supporting CSS styling, navigation configuration, and dependency updates are included. ChangesDocumentation and Configuration Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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 |
Contributor
Greptile SummaryThis PR adds several new documentation pages to the Mintlify docs site — a Stack CLI reference, a local emulator guide, a known-errors reference, and a fully rewritten self-host guide — while expanding the previously stub-only local-development page and populating the showcase page. Non-doc changes are minimal: a trivial import-order swap in
Confidence Score: 4/5Safe to merge; the only real concern is an orphaned archive file unreachable from nav that could surface in search. All findings are P2. The orphaned self-host-old.mdx carries no runtime risk. Code changes are trivial. docs-mintlify/guides/other/self-host-old.mdx — confirm whether this should be deleted or intentionally kept out of navigation Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
GF["Going Further"]
GF --> CLI["cli.mdx\n(Stack CLI reference)"]
GF --> LE["local-emulator.mdx\n(QEMU emulator guide)"]
GF --> LD["local-development.mdx\n(cloud-backed & emulator workflows)"]
CLI -->|links to| LE
LD -->|links to| LE
LD -->|links to| CLI
Other["Other"]
Other --> SH["self-host.mdx\n(revamped Docker deploy)"]
Other --> KE["known-errors.mdx\n(new SDK error reference)"]
Other --> OLD["self-host-old.mdx\n(orphaned archive ⚠️)"]
SH -.->|content moved from| OLD
Prompt To Fix All With AIFix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
docs-mintlify/guides/other/self-host-old.mdx:1-5
**Orphaned archive file not linked in navigation**
`self-host-old.mdx` is not referenced in `docs.json`, so it is unreachable from the docs nav. It contains the old local-development setup section that now contradicts the new guides (it still tells contributors to clone the repo and run `pnpm run dev` as a local dev workflow). If this is intentional archival, consider removing it entirely; otherwise search engines may surface it as conflicting documentation.
### Issue 2 of 2
docs-mintlify/guides/apps/authentication/jwts.mdx:17-20
**Leftover blank line after JWT viewer removal**
Removing the "JWT Viewer" section left two consecutive blank lines between the `header.payload.signature` paragraph and the `## Stack Auth JWT Structure` heading. Consider removing the extra blank line for cleaner rendering.
Reviews (1): Last reviewed commit: "Updates to jwts, setup. Added cli, local..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-mintlify/guides/apps/authentication/jwts.mdx`:
- Line 264: Insert a clear security warning immediately before the sentence "Use
a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify
their contents." advising readers to never paste live production tokens into
external sites and to use only redacted/test tokens; also add a local-decoding
alternative suggestion (e.g., jwt-cli, built-in language libraries, or browser
devtools) and a short example phrase like "prefer local decoding or redaction"
to steer users away from exposing secrets.
In `@docs-mintlify/guides/going-further/local-development.mdx`:
- Line 96: Replace the phrase "config-file backed development" with the
hyphenated compound modifier "config-file-backed development" in the sentence
that currently reads "If you use config-file backed development,
`stack.config.ts` becomes the local source of truth for Stack Auth settings." to
improve readability.
In `@docs-mintlify/guides/other/self-host-old.mdx`:
- Line 39: Fix the grammar in the sentence that reads "Use a cloud hosted
Postgres or start a example Postgres database. Don't use this setting in
production:" by changing "a example" to "an example" so it reads "Use a cloud
hosted Postgres or start an example Postgres database. Don't use this setting in
production:"; update the string exactly where it appears in
docs-mintlify/guides/other/self-host-old.mdx.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9f5a9351-848c-4a94-b072-f7f20a1ad34c
⛔ Files ignored due to path filters (3)
docs-mintlify/images/showcase/browser-use.pngis excluded by!**/*.pngdocs-mintlify/images/showcase/over.world.pngis excluded by!**/*.pngpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (14)
docs-mintlify/docs.jsondocs-mintlify/guides/apps/authentication/cli-authentication.mdxdocs-mintlify/guides/apps/authentication/jwts.mdxdocs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/guides/going-further/cli.mdxdocs-mintlify/guides/going-further/local-development.mdxdocs-mintlify/guides/going-further/local-emulator.mdxdocs-mintlify/guides/other/known-errors.mdxdocs-mintlify/guides/other/self-host-old.mdxdocs-mintlify/guides/other/self-host.mdxdocs-mintlify/guides/other/showcase.mdxdocs-mintlify/style.csspackage.jsonpackages/stack-cli/src/commands/emulator.ts
💤 Files with no reviewable changes (1)
- docs-mintlify/guides/getting-started/setup.mdx
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-mintlify/guides/going-further/local-emulator.mdx`:
- Line 7: The intro sentence uses an un-hyphenated compound modifier
"config-file backed projects"; update the sentence in the local emulator intro
(the line starting "The Stack Auth local emulator runs the Stack Auth
dashboard...") to use the hyphenated compound adjective "config-file-backed
projects" so it reads "...config-file-backed projects, or an isolated Stack Auth
environment for testing."
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 36e382e2-9116-4e85-9079-a723d12ea558
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (2)
docs-mintlify/guides/going-further/local-emulator.mdxpackage.json
✅ Files skipped from review due to trivial changes (1)
- package.json
Collaborator
Author
|
Added a root Without the override, Mintlify pulls an older |
mantrakp04
approved these changes
May 1, 2026
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-mintlify/guides/going-further/local-emulator.mdx`:
- Line 186: The exported token line uses angle brackets which the shell treats
as input redirection; update the export of GITHUB_TOKEN to use a literal,
shell-safe placeholder (e.g., a quoted placeholder string) instead of `<token>`
so the shell won't interpret it as a redirection when running the line with the
GITHUB_TOKEN variable.
In `@docs-mintlify/guides/other/self-host.mdx`:
- Line 71: Replace the future ClickHouse image tag string
"clickhouse/clickhouse-server:25.10" with a currently published tag (for example
"clickhouse/clickhouse-server:25.8" or "clickhouse/clickhouse-server:latest") in
the docs-mintlify/guides/other/self-host.mdx content so the smoke-test Docker
pull succeeds; update the single line containing the exact token
clickhouse/clickhouse-server:25.10 to the chosen published tag.
- Around line 162-173: Add a short clarifying note near the scheduler curl
examples explaining that the `/api/latest/internal/...` endpoints (e.g.,
`/api/latest/internal/email-queue-step`,
`/api/latest/internal/external-db-sync/sequencer`,
`/api/latest/internal/external-db-sync/poller`) are internal operational
endpoints intended for cron/devops use and may change with deploys, whereas
`/api/v1/internal/...` (e.g., `/api/v1/internal/backend-urls`) is a versioned
API namespace used for stable public/internal API contracts; update the text to
state they are not interchangeable and to use `/api/latest/internal/` for
scheduled operational tasks and `/api/v1/` for versioned API calls.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8e73e411-ed49-4067-8cb8-aec80a9a16f7
📒 Files selected for processing (2)
docs-mintlify/guides/going-further/local-emulator.mdxdocs-mintlify/guides/other/self-host.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refreshes the docs around Stack Auth setup, CLI workflows, local development, the local emulator, known SDK errors, self-hosting, and the public showcase. This also wires the new docs into Mintlify navigation and normalizes
sharpdependency resolution for docs/image tooling.Base:
dev-> Head:docs-mintlify/updatesScope: 17 files, +1154 / -435
What's New
stack exec, and emulator commands.stackauth/serverDocker deployment path, including Postgres, ClickHouse, cron scheduling, seeded admin access, reverse proxy setup, SDK env vars, email, webhooks, S3 storage, upgrades, and common issues.errorCodevalues, and REST API handling.stackcommand.sharpto0.34.5through pnpm overrides and lockfile cleanup.Review Notes
self-host-old.mdxis kept as a legacy reference file and is not added to navigation.emulator rundocumentation now matches CLI behavior: it stops the emulator only when it started that emulator instance.Test Plan
origin/dev...HEAD.git diff --check origin/dev...HEAD.Summary by CodeRabbit
Release Notes
Documentation
New Features