docs: New documentation site! #668
Conversation
This commit introduces the Starlight documentation site, replacing the old static HTML. It includes configuration, package updates, and necessary file additions/removals for the new documentation build process. Co-authored-by: burak.kaya <burak.kaya@sentry.io>
|
Cursor Agent can help with this pull request. Just |
Co-authored-by: burak.kaya <burak.kaya@sentry.io>
Co-authored-by: burak.kaya <burak.kaya@sentry.io>
|
The --base CLI flag wasn't working correctly with Starlight. Using an environment variable (DOCS_BASE_PATH) in astro.config.mjs ensures CSS and other assets load correctly in PR previews.
GitHub Pages uses Jekyll by default, which ignores files/folders starting with underscore. The .nojekyll file disables Jekyll processing so the _astro folder is served correctly.
The .nojekyll file needs to be at the root of the gh-pages branch, not just in the preview subdirectory, to disable Jekyll processing for the entire site including PR previews.
Simpler approach - place .nojekyll at repo root and copy it to docs/dist/ during build. Both the main build workflow and the PR preview workflow now copy this file to the output.
The .nojekyll file must be at the root of the gh-pages branch for GitHub Pages to disable Jekyll processing. This step checks if it exists and adds it if missing before deploying the preview.
Changed hardcoded /craft/ paths to relative paths so links work correctly with both production and PR preview base paths.
Document the workspace discovery feature including: - workspaces, includeWorkspaces, excludeWorkspaces options - artifactTemplate for custom artifact naming - Dependency ordering, private package filtering, validation
Consistent with the main project which uses yarn. - Updated workflows to use yarn install/build - Updated package.json scripts to use yarn - Replaced package-lock.json with yarn.lock
Update README, Dockerfile, and documentation for craft. Add support for floating tags in GitHub target. Co-authored-by: burak.kaya <burak.kaya@sentry.io>
![sentry[bot]](https://avatars.githubusercontent.com/u/1396951?s=60&v=4){kind=small}
| else | ||
| echo "Adding .nojekyll to gh-pages root" | ||
| git checkout gh-pages | ||
| touch .nojekyll | ||
| git add .nojekyll | ||
| git config user.name "github-actions[bot]" | ||
| git config user.email "github-actions[bot]@users.noreply.github.com" | ||
| git commit -m "Add .nojekyll to disable Jekyll processing" | ||
| git push origin gh-pages | ||
| git checkout - | ||
| fi |
There was a problem hiding this comment.
Bug: The workflow will crash on git checkout gh-pages if the gh-pages branch does not exist, as the preceding git fetch command fails silently.
Severity: HIGH | Confidence: High
🔍 Detailed Analysis
The workflow attempts to fetch the gh-pages branch using git fetch origin gh-pages:gh-pages 2>/dev/null || true. If the branch doesn't exist on the remote, such as in a new repository, this command fails silently. The script then proceeds to an else block that unconditionally runs git checkout gh-pages. Since the branch was never fetched or created locally, this checkout command fails with an error, causing the entire workflow to crash. This will prevent the documentation preview from being deployed on the first documentation-related PR in a new repository.
💡 Suggested Fix
Before attempting to git checkout gh-pages, add a check to verify if the branch exists locally after the fetch command. If it does not exist, create it. For example, you could use git branch --list gh-pages to check for its existence and then create it if necessary before the checkout.
🤖 Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.
Location: .github/workflows/docs-preview.yml#L32-L47
Potential issue: The workflow attempts to fetch the `gh-pages` branch using `git fetch
origin gh-pages:gh-pages 2>/dev/null || true`. If the branch doesn't exist on the
remote, such as in a new repository, this command fails silently. The script then
proceeds to an `else` block that unconditionally runs `git checkout gh-pages`. Since the
branch was never fetched or created locally, this checkout command fails with an error,
causing the entire workflow to crash. This will prevent the documentation preview from
being deployed on the first documentation-related PR in a new repository.
Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 7919765
Implement an Astro + Starlight documentation site to replace the old placeholder and improve the documentation experience.
This PR introduces a new Astro + Starlight documentation site, migrating content from
README.mdandCONTRIBUTING.mdinto a structured, searchable, and responsive format. It cleans up legacy documentation artifacts, updates the CI build workflow to generate the new site, and adds convenient development scripts. The existinggh-pagesCraft target is retained for deployment simplicity.