`buildHeaderElement` interpolated the header into a string that is then parsed
as HTML, so markup in a header became an element instead of text. The ten
captions on https://angular.dev/guide/i18n/translation-files read
`messages.fr.xlf ()`, having turned `(<trans-unit>)` into an empty element.
These are the only two headers in the guides containing markup.
(cherry picked from commit 9073469416)
#65848 renamed `messages.fr.xlf.html` to `messages.fr.xlf` and, in the same
lines, reverted `region=` back to `visibleRegion=`, undoing #65530 from two
weeks earlier. `visibleRegion` is not read by the tokenizer, and `xlf` is not
in `REGION_MATCHERS`, so both halves of the snippet handling broke at once.
Since then https://angular.dev/guide/i18n/translation-files has shown the same
78 line file ten times where the prose describes single `<trans-unit>`
elements, and https://angular.dev/guide/i18n/manage-marked-text three times,
each carrying the `#docregion` scaffolding into the rendered code.
Mapping `xlf` to the html matcher also cleans up
https://angular.dev/guide/i18n/example, which renders the whole file on purpose
but leaked 27 marker lines into it.
`docs-code.spec.mts` already loads this fixture but only asserted the block
existed, so it stayed green throughout. It now also asserts no marker survives.
(cherry picked from commit 61b353ebee)
`docs-alert` was the only marked extension in the pipeline without a `start`
hook, so marked never cut `inlineText` short at an alert and swallowed any
directive that was not at the start of the inline source. Writing the alert on
its own line without a blank line before it left the literal text in the body.
On https://angular.dev/guide/http/testing two alerts render as boxes and a
third shows as `IMPORTANT:` in the paragraph text. Also affects
https://angular.dev/errors/NG3003 and the first step of the first app tutorial.
The same renderer handles JSDoc, so one API page changes too:
https://angular.dev/api/upgrade/static/downgradeModule has three `NOTE:`
continuation lines inside bullets that now render as alerts.
`docs-video` and `docs-pill` already declare `start` the same way.
(cherry picked from commit 4043800ef2)
`isKnownRoute` exempted both families behind TODOs waiting on route extraction
for those packages. That extraction had already landed when the TODOs were
written in #66254: cdk pages since #60853 and aria pages since the cross-repo
workflow. `defined-routes.json` carries 70 `api/cdk` and 39 `api/aria` routes
today, and all 45 such link targets in the guides resolve, so the build stays
green without the exemptions.
The gap was not theoretical. `guide/aria/select.md` and
`guide/aria/multiselect.md` linked `api/cdk/overlay/CdkConnectedOverlay`, which
has never been a route, and it shipped as a 404 for six months. Link validation
landed four months into that and said nothing, because of this exemption. It
took a user filing #68914 and an outside contributor fixing it in #68915.
Pointing an existing `api/cdk` link at a symbol that does not exist passes the
build today and fails it with this change.
(cherry picked from commit b0cda277da)
`getTagSinceVersion` matched `\d+(\.\d+)?` anywhere in the tag comment. That
works for `@developerPreview`, `@experimental` and `@stable`, whose comment is
only a version, but `@deprecated` also carries a message, so any number in the
prose won. https://angular.dev/api/common/getLocaleCurrencyCode reads
"deprecated since v4217", taken from "a map of locale to ISO 4217 currency
codes", and eighteen sibling pages take v18 from the "i18n" in "relying on the
`Intl` API for i18n".
Anchoring the match, and allowing the `since`/`from`/`as of` prefixes the
comments use, leaves all seventy-nine correctly versioned comments untouched.
`generate_manifest` carries its own copy of the regex, so the API list badges
had the same values.
Those `@angular/common` comments never stated a version, so they now say `18.0`
explicitly, the release `d34c033902` (#54483) first shipped in, matching the
`@deprecated 18.0` already on `FormatWidth` in the same file. Nine tags in that
file had no version at all and were showing no badge; they are from the same
commit and now say `18.0` too.
(cherry picked from commit 0bdbbcf4a8)
Three ways a callout could be misparsed:
- A title quoted with `'` or a backtick was dropped, leaving an empty
heading. Two callouts lose their title on angular.dev today, on
guide/forms/template-driven-forms and guide/i18n/prepare. The first has
to use single quotes because its title contains `"pristine"`.
- A title containing `>` was dropped, because the attribute capture
stopped at the first `>` even inside a quoted value.
- The severity was matched anywhere in the tag, so a title such as
"Why this is important" silently rendered an important callout.
Scan attributes with quoting in mind, accept all three quote characters
as #69268 did for docs-code-block, and match the severity flags against
the tag with attribute values removed. The i18n callout also spelled the
attribute `header`, which the extension has never read.
(cherry picked from commit b70edd2768)
The 34 pages using `<docs-decorative-header>` render their title
through `getPageTitle()` without passing the markdown file path, so
the "Edit this page" link is silently dropped. Every other page keeps
it. Compare https://v19.angular.dev/guide/components, which still has
the pencil, against https://angular.dev/guide/components, which does
not.
`filePath` was required until #63536 made it optional, so API
descriptions with no editable source could render a title without a
link. That removed the compile error forcing the decorative header to
supply it, and the argument was lost with nothing to catch it.
Pass the path again and cover both header variants with tests, since
the edit link had no coverage at all.
(cherry picked from commit acdac1cb89)
An unclosed `<docs-step>` or `<docs-card>` produces no error, just wrong
output, so the two cases fixed in the previous commit went unnoticed for
years.
Validate that the paired custom elements balance before parsing. A
mismatch now names the file and the counts instead of silently
swallowing a section.
(cherry picked from commit d9afca095b)
The common tutorial scaffold's .gitignore opens with a link to
help.github.com/ignore-files/, which 404s. That directory is copied into every
tutorial and playground, so the dead link ships to anyone who opens one.
(cherry picked from commit 843a65cba0)
Two headings on the same page can generate the same anchor id, and every
link to it then resolves to whichever comes first. Nothing caught this
because the route manifest keeps anchors in a `Set`, so a repeat collapses
into one entry before any check runs, and the existing link validation only
asks whether an anchor exists, which a duplicate satisfies.
The generator now inspects each page's headings while they are still an
ordered list and fails with the offending pages and anchors. The scanning
and the duplicate check move to `heading.mts` so they are covered by tests
next to `getIdFromHeading`, which should keep this from coming back.
(cherry picked from commit 5e8a70a010)
Consolidates deindentation logic into formatCode so both docs-code and
docs-code-block are covered by a single fix. The original deindent
function incorrectly iterated over blank lines instead of non-blank
lines when computing minimum indentation, causing code blocks to render
with excessive leading whitespace. Also fixes region extraction which
had the same trim-before-deindent ordering issue.
(cherry picked from commit 7febf40e0d)
A leading UTF-8 byte order mark (U+FEFF) before the first `#` stops the
Markdown parser from recognizing the heading, so the guide renders its
title as a paragraph and drops the standard docs header. The character
is invisible, so it cannot be caught in review.
Add a check in the guides generation pipeline that throws when a source
file starts with a BOM, failing the build with the offending file name.
This sits alongside the existing unknown-anchor check and prevents the
regression fixed in #69889 from recurring.
Several adev states show only plain text today. This brings the Angie
mascot into them for warmer, more on-brand empty states, with no change
to copy or behavior:
- Search dialog: a magnifying-glass Angie on "Start typing to see
results", a questioning Angie on "No results found".
- API reference: a questioning Angie on "No API items found." and on the
package filter's "No results found".
- Deprecated API pages: the back-turned orthos pose in the shared
deprecation warning.
The mascots are decorative (aria-hidden) and sized per placement; the
poses are added as SVG assets under assets/images/angie/.
Also moves the Shiki highlighter init in the jsdoc-transforms spec into a
beforeAll, fixing a flake where the spec failed under randomized test
order.
Adds build-time validation to catch broken, stale, or miscased internal documentation links in both JSDoc and markdown, including `/api/` and `/guide/` URLs and their fragments. Updates the documentation pipeline to share the canonical route manifest, ensuring that all references are checked against the current navigation structure.
External links rendered via `@see {@link ...}` and `@see [label](url)`
were not opening in a new tab. The `getHtmlAdditionalLinks` function
now sets `target: '_blank'` on `LinkEntryRenderable` objects whose URL
is external, and `docs-pill-row.tsx` passes the `target` attribute to
the rendered anchor tag.
Fixes: #69593
When an inline code symbol is used as the text of an explicit markdown
link (e.g. [`httpResource`](/guide/http/http-resource)), the codespan
renderer recognized it as an API symbol and wrapped it in a second
anchor pointing at the API reference. This produced nested <a> tags, so
the explicit link was effectively replaced by the API symbol link.
Disable auto-linking while rendering a link's inner tokens so the
explicit href is preserved, matching the pattern already used by the
heading and docs-card renderers.
Fixes#69549
Update the `headerRule` regex to capture the complete quoted header value. The previous pattern excluded quote characters from the content and failed to parse headers such as:
```angular-ts {avoid, header: "Can't inject interface"}
```
The new pattern matches everything between the opening and closing quote delimiters.
The cross-repo dependency update in #69410 bumped rules_angular, whose
ts_project now requires every entry in `deps` to provide the JsInfo
provider. Two adev targets passed deps that don't, so `bazel build
//adev:build` fails analysis and the adev CI check has been red on main
since that PR.
Make generate_nav_items return JsInfo (with the generated routes.json as
its sources) so navigation-entries can keep importing routes.json through
its deps. Also drop the spurious deps entry on llms_lib: llms.mts reads
llms-list.md at runtime via readFile rather than importing it, and the
file is already provided to the binary via data.
Fixes#69429
Follow-up to #69205. After switching adev's COEP to `credentialless`, the
cross-origin YouTube iframe in `<docs-video>` loads in Chromium and Safari but
not Firefox, whose `credentialless` policy does not extend to nested frames. The
result was a COEP error screen instead of the player.
Render `<docs-video>` as a lightweight thumbnail facade instead of embedding the
iframe directly. The thumbnail is a cross-origin subresource, so it loads under
`credentialless` in every browser. `DocViewer` then upgrades the facade to the
inline player on hydration in browsers that can load the embed (Chromium,
Safari), preserving the previous behavior there. On Firefox the facade stays a
plain link that opens the video on YouTube (with autoplay), which replaces the
error screen.
The thumbnail uses `maxresdefault` and falls back to `hqdefault` when a video
has no max-resolution image.
Rename the tutorial and example template packages' package.json.template files to package.json on disk.
To comply with ng_package limitations (which forbids floating package.json files in package output), we added a copy_file rule in the BUILD files to generate the .template files during build/packaging, and excluded the source package.json files from the filegroups. This keeps package.json as standard files in the source tree while preserving docs packaging and runtime logic.
CLI option descriptions are sourced from `@angular/cli` schema JSON
files, several of which contain absolute `https://angular.dev/...` URLs
in their `description` text. Those URLs render with the external-link
icon and push preview users out to production when viewed on
`next.angular.dev` or other dev previews. The path bypasses the existing
`link.mts` ban on absolute angular.dev links because option descriptions
go through `marked.parse` directly, without `AdevDocsRenderer`. Rewrite
the rendered hrefs whose values begin with `https://angular.dev/` (or
the `http:` variant) to root-relative paths so the resulting anchors
route through Angular's Router and resolve against the active
deployment. Subdomains such as `next.angular.dev/...` are intentionally
not rewritten because they refer to genuinely different deployments.
Closes#68795
Add required, pattern, min, max, minLength and maxLength to LINK_EXEMPT
so FieldState property names stop auto-linking to the validator
functions of the same name.
Updates the Playground card copy and adds a `titleInline` attribute on
<docs-card> so the icon and title sit on the same row. Existing cards
are unaffected.
Kam