## What kind of change does this PR introduce?
Docs update. Resolves DEPR-634.
Stacked on #48664. The linter package and CI revision pins will be
updated after
[supa-mdx-lint#121](https://github.com/supabase-community/supa-mdx-lint/pull/121)
merges and is released.
## What is the current behavior?
Admonition body content can contain structural headings, which inherit
prose spacing and produce awkward callout layouts. Standalone Docs
actions are also rendered as ordinary body content in two places.
| Before |
| --- |
| <img width="1264" height="840" alt="70168"
src="https://github.com/user-attachments/assets/00aa7620-a6b4-452c-971f-b3ce2eda0e8c"
/> |
| _Recent violation with Markdown header in `children`. Notice the big
gap up top._ |
## What is the new behavior?
- Documents that admonition titles belong in the `title` prop,
standalone calls to action belong in `actions`, and document sections
belong outside admonitions.
- Configures heading-inside-admonition violations as errors for the
forthcoming linter release.
- Moves the UI-library and wrapper dashboard buttons into the existing
`actions` slot without changing the shared component.
Validated with the forthcoming linter across all 810 Docs sources, Docs
type-checking, targeted ESLint and Prettier checks, and desktop/mobile
rendering.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified admonition guidelines for optional titles, headings, rich
content, and standalone calls to action.
* Improved guidance on when contextual links and interactive examples
belong in admonition content.
* **Style**
* Updated documentation call-to-action buttons to use the designated
actions area.
* **Quality Improvements**
* Added validation to prevent headings inside admonitions and maintain
consistent formatting.
* Updated documentation linting to apply the latest validation rules.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Add a zizmor config and CI job that lints `.github/workflows` on every
PR touching it, downloading and attestation-verifying the pinned v1.26.1
release binary (cached across runs)
- Fix the mutable-tag and excess-permission findings zizmor surfaces in
`braintrust-evals.yml`, `publish_image.yml`, and
`self-host-tests-smoke.yml`: pin `actions/checkout`/`actions/setup-node`
to commit SHAs, and scope `pull-requests`/`packages`/`id-token`
permissions down to the specific jobs that need them
## Test plan
- [x] Confirm the `zizmor` job runs and passes on this PR
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added automated security scanning for workflow changes on pull
requests.
* Added configuration to allow specific workflow trigger exceptions.
* **Security**
* Tightened GitHub Actions permissions at the workflow level and
re-granted only where required per job.
* Pinned common build action versions to specific commits for more
consistent execution.
* **Maintenance**
* Updated workflow caching and action step annotations without changing
linting or fixing behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
chore
## Additional context
We will require all actions to be pinned going forward
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated CI/CD workflows to use pinned action versions for improved
reliability and consistency.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
* fix: rewrite relative URLs when syncing to GitHub discussion
Relative URLs back to supabse.com won't work in GitHub discussions, so
rewrite them back to absolute URLs starting with https://supabase.com
* fix: replace all supabase urls with relative urls
* chore: add linting for relative urls
* chore: bump linter version
* Prettier
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Workflow for external lints still not working quite right.
1. The lint workflow should fail if linting fails, to block merge. Right
now the exit status of the linter is ignored; added a step to fix that.
2. The workflow_run event is not triggered by completion of the first
workflow. Couldn't find an obvious problem with the two, but saw online
that some people had problems with a quoted workflow name, so tried
renaming the workflows to avoid having to quote the names.
The external PRs workflow is still broken: commenting on the PR with the
lint results doesn't work because pull_request events triggered from
forks do not have write permissions.
Following GitHub recommendations, I broke it down into two workflows:
1. First workflow writes the lint results (if any) to an uploaded
artifact.
2. Second workflow (triggered by workflow_run and thus has write
permissions) downloads the artifact and posts the results as a PR
comment.
Before:
The docs lint action doesn't run properly on forks because it tries to
use the branch name to identify the PR for updating, but the branch name is adapted on forks, so it is not `branch-name`, but `forking-account:branch-name`.
After:
Use the PR number instead to identify the PR instead.
Partials are currently defined via MDX includes. This PR switches to pre-compile-time partials, which have a new syntax:
```
<$Partial path="path/to/file.mdx" />
```
## Rationale
This produces two improvements:
1. Partial substitution can occur in pipelines that don't use MDX compilation. For example, we can now do partial substitution before building the search index, so partial content will also be indexed.
2. After the App Router migration, the MDXProviders should've been deprecated, but were kept around for the sole reason of making partials work, and leading to us shipping unnecessary client-side code. We get a minor decrease in overall client bundle size (5.74 MB to 5.6 MB) by getting rid of the Providers.
## Breaking changes
Besides the change to partial syntax, the arguments are also less powerful than before because we are doing string substitution and don't have the full power of JS. Defining string variables is still possible (documented in the Contributing guide), and since that's all we actually do in practice, this shouldn't be too cumbersome. There is always the escape hatch of making a custom component for more complex content reuse cases.
Conditional and required checks don't mix well on GitHub -- if a required check is skipped it still hangs, preventing PRs from getting merged indefinitely. Instead, we need to to run the action on every PR, but bail early if no docs content changes were made.
Since the logic for when/how this action runs is getting a bit convoluted, I also split up the tests against master (run against all files, no conditional checks) from the tests aginst PRs (run against changed files, with conditional checks)
Docs lint errors can make it into master through a race condition:
- PR with lint configuration changes is made
- Separately, a PR that is incompatible with the new configuration (but _is_ compatible with the old one) is merged
This can be annoying for downstream PRs, so lint post-merge, and create a PR with auto-fixes if possible.
PR to start introducing Linter V2!
Primary improvements from this linter:
Better parsing of MDX (fewer false positives)
More flexibility
And suggested autofixes! (see auto-generated PR comment below for how that works)
Turning this on for only a small portion of the repo at first to avoid an avalanche of alerts, will slowly expand from there.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Danny White
