Repository navigation
Rebuild docs on Astro Starlight and add the Jabali Studio guide - #1
Merged
Merged
Conversation
Contributor
Author
|
Updating docs. |
vatsal-vb
marked this pull request as ready for review
October 7, 2026 13:45
PR Summary by QodoMigrate Jabali docs to Starlight and publish the Studio guide
AI Description
Diagram
High-Level Assessment
Files changed (34)
|
Code Review by Qodo
1. The documentation build fails on missing images
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+27
to
+29
| logo: { | ||
| light: './src/assets/brand/logo-light.png', | ||
| dark: './src/assets/brand/logo-dark.png', |
There was a problem hiding this comment.
1. The documentation build fails on missing images 🐞 Bug ≡ Correctness
astro.config.mjs names two logo files that are absent, and the home page names a hero image that is absent. When npm run build processes those image inputs, the site cannot be built; the configured favicon and social-image files are missing as well.
Agent Prompt
## Issue description
The Astro configuration and content reference build-time images that are not present in the branch.
## Fix Focus Areas
- astro.config.mjs[27-29]
- src/content/docs/index.mdx[8-10]
- astro.config.mjs[44-51]
## Recommended Fix
Add the referenced logo and screenshot files under `src/assets/`, and add the favicon, social image, and touch icon under `public/`. Run `npm run build` against the resulting commit.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
Author
There was a problem hiding this comment.
Fixed in #2: adds the 16 screenshots under src/assets/studio/, both logos under src/assets/brand/, and favicon.png, og-image.png and apple-touch-icon.png under public/. npm run build passes on the patched branch.
Comment on lines
+19
to
+21
| | Pull request opened | `.github/workflows/check.yml` builds the site and validates every internal link | | ||
| | Review | A code owner from `.github/CODEOWNERS` must approve | | ||
| | Merge to `main` | `.github/workflows/deploy.yml` builds and deploys to GitHub Pages | |
There was a problem hiding this comment.
2. Merges cannot publish the new docs site 🐞 Bug ☼ Reliability
README.md makes pull-request checks and Pages deployment depend on .github/workflows/check.yml and .github/workflows/deploy.yml, but neither workflow is in this branch. Even after the image inputs are supplied, merging to main will not run the described Astro deployment, and the required build status check cannot be produced.
Agent Prompt
## Issue description
The documented GitHub Actions check and deployment have no workflow files in the branch.
## Fix Focus Areas
- README.md[19-29]
- package.json[7-12]
## Recommended Fix
Commit `.github/workflows/check.yml` and `.github/workflows/deploy.yml` with the documented pull-request and main-branch triggers, then confirm the check runs and a merged change deploys through GitHub Pages.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
Author
There was a problem hiding this comment.
Fixed in #2: adds .github/workflows/check.yml (PRs, job "Build and validate links") and deploy.yml (push to main, withastro/action + deploy-pages), plus package-lock.json.
Comment on lines
+9
to
+11
| 'web.html': 'web/', | ||
| 'support.html': 'support/', | ||
| 'studio.html': 'studio/', |
There was a problem hiding this comment.
3. Old markdown links lose their destinations 🐞 Bug ≡ Correctness
legacyRedirects emits only .html paths, while the old home page links to web.md, core/prompting.md, and support.md. Once the old files are removed, visitors following those existing links reach paths for which the integration writes no redirect.
Agent Prompt
## Issue description
Existing links to old `.md` paths are not covered by the new redirect table.
## Fix Focus Areas
- src/legacy-redirects.mjs[8-29]
- src/integrations/seo-extras.mjs[39-45]
## Recommended Fix
Inventory the old site's linked `.md` URLs and add matching redirect entries alongside the `.html` entries. Verify the generated output contains files at those exact paths.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
Author
There was a problem hiding this comment.
Fixed in #2: every legacy entry now also gets a .md redirect. GitHub Pages serves .md files as plain text, so it's written as page.md/index.html (34 redirect pages in total, checked in dist/).
| contact_links: | ||
| - name: Get help with Jabali (Discord) | ||
| url: https://discord.gg/jabali | ||
| about: Questions about using Jabali Studio, Jabali Web or the Discord bot are answered fastest on Discord. |
There was a problem hiding this comment.
4. Issue chooser points users at retired bot 🐞 Bug ⚙ Maintainability
The about text for the Discord contact link in the issue template config still says questions about "the Discord bot" are answered on Discord. This PR removes the Jabali on Discord docs because that product is retired, so users choosing an issue type are told about a product that no longer exists.
Agent Prompt
## Issue description
The issue template contact link still mentions the retired Discord bot.
## Fix Focus Areas
- .github/ISSUE_TEMPLATE/config.yml[5-5]
## Recommended Fix
Change the text to: "Questions about using Jabali Studio or Jabali Web are answered fastest on Discord."
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| Product changes reach the docs through pull requests, so a maintainer still approves everything: | ||
|
|
||
| - **Anyone** can open a "Product update needs docs" issue or a PR. | ||
| - **Automated drafts:** every Monday a scheduled Claude task checks for new **stable** Jabali Studio releases (alpha/prerelease builds are ignored), updates the affected pages plus `studio/whats-new`, and opens a PR titled `Docs: Jabali Studio <version> updates` with the `product-update` label. A maintainer reviews and merges it like any other PR. Internal details, private links and unreleased features are left out. |
There was a problem hiding this comment.
5. Weekly update task targets a missing page 🐞 Bug ⚙ Maintainability
The README says the scheduled Claude task updates studio/whats-new with each stable release, but there is no src/content/docs/studio/whats-new.md and no matching slug in the sidebar. The first automated PR will have to invent that page or fail to update it, and adding it would also need a sidebar entry that the described workflow doesn't mention.
Agent Prompt
## Issue description
The README says the weekly automation updates `studio/whats-new`, but that page doesn't exist.
## Fix Focus Areas
- README.md[61-61]
- astro.config.mjs[64-75]
## Recommended Fix
Either add `src/content/docs/studio/whats-new.md` (with a valid 50–160 character description) and add `'studio/whats-new'` to the Studio sidebar, or remove the mention from the README.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
Author
There was a problem hiding this comment.
Fixed in #2: the README now says the first product-update PR creates studio/whats-new.md and its sidebar entry. The scheduled task already does both, so no empty page goes live before there's a release to list.
| ## If sign-in fails | ||
|
|
||
| - Restart Jabali Studio and try again. | ||
| - If you use Discord, try logging out of Discord in your browser, then sign in again. |
There was a problem hiding this comment.
6. Discord sign-in fixes contradict each other 🐞 Bug ≡ Correctness
The sign-in page tells users to log out of Discord in their browser and sign in again, while the FAQ's "Why is sign-in failing or freezing?" answer tells them to make sure they are logged in to Discord in their default browser. A user stuck at Discord login gets opposite advice depending on which page they read, and the FAQ version is also published as FAQPage structured data that AI assistants quote.
Agent Prompt
## Issue description
The sign-in page and the FAQ give opposite advice about the Discord browser session when sign-in fails.
## Fix Focus Areas
- src/content/docs/studio/sign-in.md[27-27]
- src/content/docs/studio/faq.md[19-19]
## Recommended Fix
Confirm the correct troubleshooting step with the product team and use the same wording on both pages, e.g. "Make sure you're logged in to the right Discord account in your default browser; if not, log out and sign in again."
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
Author
There was a problem hiding this comment.
Fixed in #2: both pages now say to make sure you're logged in to the right Discord account in your default browser, and if sign-in still fails, to log out of Discord, log back in, then try again. That keeps both tips from the source Google Doc, in order.
vatsal-vb
added a commit
that referenced
this pull request
Oct 7, 2026
- Redirect the old `.md` URLs (web.md, core/prompting.md, …) as well as the `.html` ones - Drop the retired Discord bot from the issue chooser's Discord link - Give the same Discord sign-in advice on the Sign in page and in the FAQ - README: say that the first product-update PR creates the What's new page and its sidebar entry Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QF9wi4kciRPby5RsfkB4Xv
vatsal-vb
added a commit
that referenced
this pull request
Oct 7, 2026
The weekly product-update task creates studio/whats-new.md and its sidebar entry in its first PR, so the README no longer points at a page that doesn't exist yet (Qodo finding 5 on PR #1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QF9wi4kciRPby5RsfkB4Xv
5 tasks done
vatsal-vb
added a commit
that referenced
this pull request
Oct 10, 2026
* Fix Qodo review findings 3–6 from PR #1 - Redirect the old `.md` URLs (web.md, core/prompting.md, …) as well as the `.html` ones - Drop the retired Discord bot from the issue chooser's Discord link - Give the same Discord sign-in advice on the Sign in page and in the FAQ - README: say that the first product-update PR creates the What's new page and its sidebar entry Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QF9wi4kciRPby5RsfkB4Xv * README: explain how the What's new page gets created The weekly product-update task creates studio/whats-new.md and its sidebar entry in its first PR, so the README no longer points at a page that doesn't exist yet (Qodo finding 5 on PR #1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QF9wi4kciRPby5RsfkB4Xv * Remove old Jekyll site: animation/discord-make.mp4 * Remove old Jekyll site: animation/discord-make-genres.mp4 * Remove old Jekyll site: _config.yml * Remove old Jekyll site: index.md * Remove old Jekyll site: studio.md * Remove old Jekyll site: support.md * Remove old Jekyll site: web.md * Remove old Jekyll site: core/generation-and-management.md * Remove old Jekyll site: core/how-it-works.md * Remove old Jekyll site: core/prompting.md * Remove old Jekyll site: core/story-characters-assets.md * Remove old Jekyll site: discord-docs/build-publish.md * Remove old Jekyll site: discord-docs/create-discord-genres.md * Remove old Jekyll site: discord-docs/create-discord.md * Remove old Jekyll site: discord-docs/discord-upload-knowledge.png * Remove old Jekyll site: discord-docs/discord.md * Remove old Jekyll site: discord-docs/edit-upload.md * Remove old Jekyll site: discord-docs/game-seed.md * Remove old Jekyll site: discord-docs/prompt-editing.md * Remove old Jekyll site: discord-docs/upload-content.md * Remove old Jekyll site: discord-docs/upload-image.png * Remove old Jekyll site: images/agentic-chatter.png * Remove old Jekyll site: images/bali-chat.png * Remove old Jekyll site: images/bali-genre.png * Remove old Jekyll site: images/bali-play.png * Remove old Jekyll site: images/bali-upload.png * Remove old Jekyll site: images/build-publish.png * Remove old Jekyll site: images/game-edit.png * Remove old Jekyll site: images/jabali-play-website.jpg * Remove old Jekyll site: images/jabali-web.png * Remove old Jekyll site: images/logo.jpeg * Remove old Jekyll site: tutorials/chapters.png * Remove old Jekyll site: tutorials/char.png * Remove old Jekyll site: tutorials/character-sim.md * Remove old Jekyll site: tutorials/image-1.png * Remove old Jekyll site: tutorials/image.png * Remove old Jekyll site: tutorials/interactive-story.md * Remove old Jekyll site: tutorials/locations.png * Remove old Jekyll site: tutorials/tutorial-is-prompt.png * Remove old Jekyll site: tutorials/tutorial-is-seed.png * Add files via upload * Add files via upload --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.
What this does
Moves the docs from Jekyll/Just the Docs to Astro Starlight, and turns the Jabali Studio Google Doc into 10 proper pages. Today the homepage just links out to that doc.
Content
noindexand left out of the sitemap and llms.txt until the new Web docs are writtenCommunity contributions + approval
CODEOWNERS(@vatsal-vb), a PR template, issue templates (docs problem, new page request, product update) andCONTRIBUTING.mdcheck.ymlbuilds every PR. The build fails on broken internal links or a missing page descriptionSEO / AEO
descriptionon every page; canonical URLs, Open Graph/Twitter cards and a social imagerobots.txtdateModified) and BreadcrumbList, plus FAQPage on the FAQ, built automatically from its###questionsllms.txt,llms-full.txtandllms-small.txtfor AI assistants.htmlURLdocs.jabali.ailater: see README → "Moving to docs.jabali.ai"main: require a PR, 1 approval, review from Code Owners, and theBuild and validate linkscheck.deploy.ymlpublishes to https://jaabaali.github.io/docs/Notes for review
🤖 Generated with Claude Code
https://claude.ai/code/session_01T8NkDNU8At9SeLvz6Q4JX4