WIP: PortalJS Cloud docs#1503
Open
demenech wants to merge 3 commits into
Open
Conversation
Add a user-facing admin documentation section for PortalJS Cloud at /cloud/docs, covering getting started, the portal, datasets, visualizations, groups, organizations, users, account, harvesters, and the MCP server. Wires a dedicated sidebar (content/assets/cloud-sidebar.json) via the [...slug] route, adds a "Cloud Docs" navbar link, and stores screenshots under public/static/img/cloud-docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Unquoted title/description values containing colons broke the mddb YAML parse. Wrap all title and description values in double quotes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
MDX parses <email> autolink syntax as a JSX tag, and the `@` broke the prerender of /cloud/docs/account. Use a standard markdown mailto link. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
9 Skipped Deployments
|
📝 WalkthroughWalkthroughThis PR adds a complete Cloud admin documentation suite covering account, organization, user, dataset, and group management alongside portal setup and integrations documentation. It includes sidebar navigation configuration, route handling, and docstring/reference material spanning onboarding through advanced features like harvesters and MCP server connectivity. ChangesPortalJS Cloud Admin Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 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 docstrings
🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
site/content/cloud/docs/harvesters.md (1)
47-47:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd newline at end of file.
Markdown files should end with a newline character per POSIX convention.
📝 Proposed fix
- Assign harvested datasets to a dedicated [Organization](/cloud/docs/organizations) (for example, "External sources") to keep them separated from datasets authored directly in the portal. +🤖 Prompt for 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. In `@site/content/cloud/docs/harvesters.md` at line 47, The file harvesters.md is missing a trailing newline; add a single newline character at the end of the file so the file ends with a newline per POSIX convention (save the file with a final line break).site/content/cloud/docs/mcp-server.md (1)
69-69:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd newline at end of file.
Markdown files should end with a newline character per POSIX convention.
📝 Proposed fix
- **Chatbot sees no datasets** — make sure at least one dataset is marked **Public**. See [Datasets → Visibility](/cloud/docs/datasets#visibility-public-vs-private). +🤖 Prompt for 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. In `@site/content/cloud/docs/mcp-server.md` at line 69, Add a trailing newline character to the end of the Markdown file mcp-server.md so the file ends with a single blank line (POSIX convention); open the file, place the cursor at the end of the last line and insert a newline, then save the file.
🤖 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 `@site/content/cloud/docs/account.md`:
- Around line 67-69: Update the fenced code block that currently contains the
URL "https://api.cloud.portaljs.com/@<your-org>/api/3/docs" to include a
language identifier (e.g., change the opening backticks from ``` to ```text or
```plain) so the block has a language specifier for proper syntax highlighting
and to satisfy markdownlint MD040.
In `@site/content/cloud/docs/groups.md`:
- Line 68: The docs currently use three different slug/Name constraints
(groups.md Name forbids spaces and `.`, `+`, `&`; datasets.md Name forbids
spaces and `.`; visualizations.md allows lowercase, numbers, underscores,
dashes), which is inconsistent; choose and apply one consistent validation rule
for Name/slug across all entity docs (or explicitly document per-entity
exceptions), then update the Name lines in groups.md, datasets.md, and
visualizations.md to the unified wording (or add a brief justification next to
each Name entry explaining the specific exception), and ensure the phrasing
clearly lists allowed characters (e.g., "lowercase letters, numbers, dashes
only" or "URL-safe: no spaces or `.`, `+`, `&`") so users see the same
constraint everywhere.
In `@site/content/cloud/docs/mcp-server.md`:
- Around line 17-19: The fenced code block containing the example URL should
include a language identifier for proper highlighting; update the block
delimiter from ``` to ```text (or ```bash) so the snippet showing
"https://mcp.portaljs.com/@<your-org-name>/sse" is written as a text code block
and tooling will render it correctly.
In `@site/content/cloud/docs/users.md`:
- Line 22: The two sentences "Sysadmins themselves are not shown in the list"
and "sysadmins see every user in the portal" conflict; update the Users doc to
explicitly state whether sysadmins can view other sysadmins in the Users list
and clarify where sysadmin management occurs. Replace or augment the sentence at
line 22 with a rephrase such as "Sysadmins are not shown on the Users page;
sysadmins can view all non-sysadmin users in the portal, and management of
sysadmin accounts is handled via the main organization's Members tab." Also add
a brief note that sysadmin account changes should be made in the Members tab
rather than the Users page to avoid confusion.
---
Outside diff comments:
In `@site/content/cloud/docs/harvesters.md`:
- Line 47: The file harvesters.md is missing a trailing newline; add a single
newline character at the end of the file so the file ends with a newline per
POSIX convention (save the file with a final line break).
In `@site/content/cloud/docs/mcp-server.md`:
- Line 69: Add a trailing newline character to the end of the Markdown file
mcp-server.md so the file ends with a single blank line (POSIX convention); open
the file, place the cursor at the end of the last line and insert a newline,
then save the file.
🪄 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: 01030afc-6087-49b5-ba22-dc9359066b9d
📒 Files selected for processing (15)
site/content/assets/cloud-sidebar.jsonsite/content/cloud/docs/account.mdsite/content/cloud/docs/datasets.mdsite/content/cloud/docs/getting-started.mdsite/content/cloud/docs/groups.mdsite/content/cloud/docs/harvesters.mdsite/content/cloud/docs/index.mdsite/content/cloud/docs/mcp-server.mdsite/content/cloud/docs/organizations.mdsite/content/cloud/docs/portal.mdsite/content/cloud/docs/users.mdsite/content/cloud/docs/visualizations.mdsite/content/config.jssite/pages/[...slug].tsxsite/public/static/img/cloud-docs/.gitkeep
Comment on lines
+67
to
+69
| ``` | ||
| https://api.cloud.portaljs.com/@<your-org>/api/3/docs | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to the code fence.
The code block should include a language identifier for proper syntax highlighting and to satisfy Markdown linting rules.
📝 Proposed fix
-```
+```text
https://api.cloud.portaljs.com/@<your-org>/api/3/docs</details>
As per coding guidelines, fenced code blocks should have a language specified (markdownlint MD040).
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for 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.
In `@site/content/cloud/docs/account.md` around lines 67 - 69, Update the fenced
code block that currently contains the URL
"https://api.cloud.portaljs.com/@<your-org>/api/3/docs" to include a language
identifier (e.g., change the opening backticks from ``` to ```text or ```plain)
so the block has a language specifier for proper syntax highlighting and to
satisfy markdownlint MD040.
| | Field | Type | Required | Description | | ||
| |-------|------|----------|-------------| | ||
| | **Title** | string | yes | Human-readable name shown across the portal. | | ||
| | **Name** | string (slug) | yes | URL-safe identifier. Cannot contain spaces or the characters `.`, `+`, `&`. Use lowercase letters, numbers, and dashes. | |
There was a problem hiding this comment.
Inconsistent slug validation rules across entity types.
The Name field constraint for groups forbids spaces, ., +, and &, but the dataset Name field (datasets.md line 146) only forbids spaces and .. Visualizations.md (line 68) specifies yet another rule: "lowercase letters, numbers, underscores, and dashes only."
These inconsistencies will confuse users. Consider either:
- Unifying the validation rules across all entity types, or
- Clearly documenting why different entities have different constraints
🤖 Prompt for 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.
In `@site/content/cloud/docs/groups.md` at line 68, The docs currently use three
different slug/Name constraints (groups.md Name forbids spaces and `.`, `+`,
`&`; datasets.md Name forbids spaces and `.`; visualizations.md allows
lowercase, numbers, underscores, dashes), which is inconsistent; choose and
apply one consistent validation rule for Name/slug across all entity docs (or
explicitly document per-entity exceptions), then update the Name lines in
groups.md, datasets.md, and visualizations.md to the unified wording (or add a
brief justification next to each Name entry explaining the specific exception),
and ensure the phrasing clearly lists allowed characters (e.g., "lowercase
letters, numbers, dashes only" or "URL-safe: no spaces or `.`, `+`, `&`") so
users see the same constraint everywhere.
Comment on lines
+17
to
+19
| ``` | ||
| https://mcp.portaljs.com/@<your-org-name>/sse | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to code block.
The code block should specify a language for proper syntax highlighting and tooling support. For a URL example, use text or bash.
📝 Proposed fix
- ```
+ ```text
https://mcp.portaljs.com/@<your-org-name>/sse
```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| https://mcp.portaljs.com/@<your-org-name>/sse | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 17-17: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for 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.
In `@site/content/cloud/docs/mcp-server.md` around lines 17 - 19, The fenced code
block containing the example URL should include a language identifier for proper
highlighting; update the block delimiter from ``` to ```text (or ```bash) so the
snippet showing "https://mcp.portaljs.com/@<your-org-name>/sse" is written as a
text code block and tooling will render it correctly.
| | Edit your own profile | Any user (see [Account](/cloud/docs/account)) | | ||
| | Delete users | Sysadmin | | ||
|
|
||
| Sysadmins themselves are not shown in the list. |
There was a problem hiding this comment.
Clarify sysadmin visibility to avoid confusion.
Line 22 states "Sysadmins themselves are not shown in the list," but line 35 says "sysadmins see every user in the portal." This could be read as contradictory—does "every user" include other sysadmins or not?
Consider rephrasing to explicitly state whether sysadmins can see other sysadmins in the Users list, or add a brief note explaining that sysadmin management happens via the main organization's Members tab rather than the Users page.
📝 Suggested clarification
-Sysadmins themselves are not shown in the list.
+Sysadmins are not shown in the Users list. To manage sysadmin membership, use the main organization's Members tab (see [Organizations → Managing sysadmins](/cloud/docs/organizations#managing-sysadmins)).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Sysadmins themselves are not shown in the list. | |
| Sysadmins are not shown in the Users list. To manage sysadmin membership, use the main organization's Members tab (see [Organizations → Managing sysadmins](/cloud/docs/organizations#managing-sysadmins)). |
🤖 Prompt for 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.
In `@site/content/cloud/docs/users.md` at line 22, The two sentences "Sysadmins
themselves are not shown in the list" and "sysadmins see every user in the
portal" conflict; update the Users doc to explicitly state whether sysadmins can
view other sysadmins in the Users list and clarify where sysadmin management
occurs. Replace or augment the sentence at line 22 with a rephrase such as
"Sysadmins are not shown on the Users page; sysadmins can view all non-sysadmin
users in the portal, and management of sysadmin accounts is handled via the main
organization's Members tab." Also add a brief note that sysadmin account changes
should be made in the Members tab rather than the Users page to avoid confusion.
6 tasks
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
1 participant
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 by CodeRabbit