Strings baked into pages by the markdown renderer can now be overridden
per locale via `locales.<index>.markdown` in the site config: container
titles (including GitHub-flavored alerts and custom containers) and the
code copy button title. Values resolve against `env.localeIndex` at
render time and fall back to the root markdown options, so the single
shared renderer keeps working unchanged.
close#4431
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New containers can be registered via
`markdown.container.customContainers`, mapping a container name to its
default title. Registered names work as `::: name` blocks and as
GitHub-style alerts (`> [!NAME]`), with custom titles, attributes, and
no-title behaving like the built-in types. Styling is left to the theme
via `.custom-block.name`.
close#3591close#3603close#4228
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A no-title attribute (`::: tip {no-title}`) renders a container without
its title element, and the theme reduces the top padding for containers
without one. It has no effect on `details`, which always needs its
summary. The docs previously hand-rolled this with a raw div and an
inline style - those are now switched to the new syntax.
close#4928close#4932close#4929
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replaces markdown-it-container and merges the GitHub alerts plugin into
the containers module so both share one title map. Rendered output is
byte-compatible with the previous implementation.
This also restores fence-line attributes on containers ({open}, {.class},
etc.), which broke when markdown-it-attrs was replaced with
@mdit/plugin-attrs - its fence rule handled containers too, but had to be
disabled to keep code block meta intact. The container plugin now parses
the trailing braces itself, so the old markdown-it-attrs patch is not
needed in any form.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per-module hooks (resolveId / load / transform) now declare filters,
so rolldown skips the Rust-to-JS call for modules they cannot act on
instead of invoking every hook for every module in the graph.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Plugin options that could be disabled with `false` (`attrs`, `emoji`,
`tasklist`, `anchor`, `toc`, `image`, `component`) now also accept
`true`, which - like leaving them unset - enables the plugin with its
default options. Only object values are forwarded to the plugins.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Renders `- [ ] task` syntax via `@mdit/plugin-tasklist`, enabled by
default and configurable through the new `tasklist` markdown option
(set to `false` to disable). The default theme hides list markers for
task items and pulls checkboxes into the list gutter, GitHub-style.
close#413close#1923close#3648close#5110
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The `fence` rule is disabled by default, replacing the patch we carried
to stop curly attributes from consuming code block meta (line
highlighting etc.). Drops both attrs patches and
`@types/markdown-it-attrs`.
BREAKING CHANGE: `markdown.attrs` options are now typed by
`@mdit/plugin-attrs`: `leftDelimiter`, `rightDelimiter`, and
`allowedAttributes` are renamed to `left`, `right`, and `allowed`. A
`rule` option is available for toggling individual attribute rules
(VitePress disables `fence` by default).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Captures what the markdown-it-attrs patch enforces (curly attributes
never consume fence info, preserving line-highlight syntax) plus the
supported attribute placements, as a regression baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
attrs registers its core rule at a fixed position (before linkify)
while anchor pushes to the end of the chain, so user-defined ids from
curly attributes win regardless of registration order. Remove the
comment that claimed the order matters.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- group `MarkdownOptions` into sections by concern (general, syntax
highlighting, code blocks, markdown extensions, vue integration) and
rewrite the jsdocs with a consistent voice, documenting the previously
undocumented `externalLinks` default and correcting the `container`
description (label customization, not plugin pass-through)
- register plugins in accurately-labeled groups (vitepress
customizations, community plugins, mdit-vue plugins) and note the
order-sensitive couplings inline (lineNumbers after preWrapper,
anchor after attrs)
- add a test for the `cjkFriendlyEmphasis` toggle
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Allows custom themes to opt out of markup and behavior added on top of
vanilla markdown rendering:
- `anchor`, `emoji`, `toc`, `component`, `image` now also accept `false`
- new `preWrapper` and `snippet` boolean options (default true)
- `lineNumbers` is a no-op when `preWrapper` is disabled, as its markup
depends on the wrapper
close#4484close#4556
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- split __tests__/tsconfig.json into per-suite projects so unit tests
check against src (via path aliases) while e2e/init check against the
built package, avoiding mixing both type universes in one program
- explicitly include the .vitepress dir in the e2e project - dotted
directories are skipped by default, so it was never type-checked
- add a `*.vue` shim for the e2e custom theme (named env.d.ts because a
shims.d.ts would be dropped in favor of the adjacent shims.ts)
- add a tsconfig for docs, checked with vue-tsc
- wire everything into `pnpm test` as `test:types`
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BREAKING CHANGE: The `markdown.image.lazyLoading` option has been renamed to `markdown.image.lazyLoad`.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace the standalone `useData().hash` ref (backed by its own
`hashchange` listener in `initData`) with the `hash` already tracked on
the route, so the current URL is observed in one place and behaves
consistently during SSR.
- `isActive()` no longer reads `location.hash` at call time; it takes
the current hash as an argument (plus an optional `skipHashCheck`)
and `matchPath` is now required, making it pure and SSR-safe
- nav bar menus, nav screen menus, and menu links now react to hash-only
navigation too
- sidebar active-state tracking is reworked on top of the route: items
without a link are handled, and collapsed groups reliably auto-expand
when a child link becomes active (including on hash changes)
- prev/next links now properly ignore query strings and hashes when
deduplicating sidebar candidates (via `normalize`) and when matching
the current page
- custom `i18nRouting` functions receive the whole current `Route`
instead of only the hash string; language menu links are resolved
from the route (en + ru docs updated)
- `useLangs()` / `resolveLocaleLink()` are refactored with
self-documenting, JSDoc'd options (`linkToCorrespondingPage`,
`targetLocaleLink`, `currentLocaleLink`), and `resolveLocaleLink`
gained focused unit tests covering locale-home links, corresponding
links, cleanUrls, index pages, root-locale switching, and custom
routing functions
- unavoidable hydration mismatches are silenced with
`data-allow-mismatch` (viewport-dependent inline styles, per-locale
alternate links that embed the current query/hash)
- the `Route` interface moved to the shared types so
`DefaultTheme.I18nRouting` can reference it; the `vitepress` type
export is unchanged
- misc cleanups: `uniqBy` moved to theme support utils, `smartComputed`
comparator now called as `(newValue, oldValue)`, import ordering
BREAKING CHANGE: `useData().hash` has been removed. Read the hash from
`useRoute()` instead.
BREAKING CHANGE: custom `themeConfig.i18nRouting` functions now receive
the current `Route` as their second argument instead of the hash
string: `(data, route, targetLocale) => string`. Use `route.hash` for
the previous value; `route.path`, `route.query`, and `route.data` are
available as well.
BREAKING CHANGE: `includeFiles` option in `postcssIsolateStyles` now defaults to `[/vp-doc\.css/, /base\.css/]` You can remove explicit `includeFiles` if you were using it just to run it on `vp-doc.css`. To revert back to older behavior pass `includeFiles: [/base\.css/]`. The underlying implementation is changed and `transform` and `exclude` options are no longer supported. Use `postcss-prefix-selector` directly if you've advanced use cases.
BREAKING CHANGE: `useLocalNav` and `useSidebar` are removed in favor of `useLayout`. To migrate, just do find and replace. Sidebar controls are no longer exported, but I didn't find any usage on GitHub. If there is demand, we can export respective composables later. `DefaultTheme.DocSidebar` and `DefaultTheme.DocLocalNav` types are also removed.
---------
Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Co-authored-by: userquin <userquin@gmail.com>
Divyansh Singh
chencu
Bjorn Lu
Rayan Salhab
TowyTowy
T
lilianakatrina684-a11y
Joaquín Sánchez
Sergio
Dylan Tientcheu
Alex
Yuxuan Zhang