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>
base.css is now Tailwind's preflight (pinned to their e48c5e80) wrapped
in the vitepress cascade layer, with the font stacks pointing at the
vitepress variables and the bold weight at 600, followed by a section
with the vitepress-specific overrides. Compared to the old base this
picks up the universal margin/padding/border reset, tab-size: 4, iOS
tap-highlight removal, and the modern form and date-input
normalizations, and drops fossils like the touch-action click-delay
hack and main { display: block }.
BREAKING CHANGE: normalize-level defaults differ from the old reset -
native select and number-input chrome is restored, headings inherit
font size and weight, the hidden attribute is enforced with !important,
and every element starts with zero margin/padding and border-style:
solid. Sites layering custom CSS on the default theme may notice.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The farsi docs now declare their own @font-face pointing at the
version-pinned woff2 from jsdelivr instead of pulling Google Fonts'
stylesheet. The face is range-gated to Google Fonts' arabic subset
ranges plus guillemets and ellipsis and sits before Inter in the
stack, so persian punctuation renders in Vazirmatn while latin keeps
rendering from the locally served Inter.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Inter Core faces (previously Inter4CJK) leave East Asian ambiguous
punctuation and symbols uncovered so that the document's CJK font can
render them, but the next family in the stack was a Latin system font,
which claimed most of those characters before the language-aware system
fallback could pick the right CJK font - and characters it lacked could
land in an unrelated one (like Apple SD Gothic Neo on Chinese pages in
Chrome on macOS). The zh/ja/ko stacks now name the platform defaults
explicitly (PingFang SC / Microsoft YaHei / Noto Sans CJK SC, Hiragino
Sans / Meiryo / Yu Gothic / Noto Sans CJK JP, Apple SD Gothic Neo /
Malgun Gothic / Noto Sans CJK KR), so per-glyph matching lands there
deterministically, and sites can splice a CJK webfont between
'Inter Core' and the system families. Traditional Chinese currently
shares the zh (Hans) rule; the TC variant is documented in the script.
BREAKING CHANGE: the Inter4CJK font family has been renamed to
'Inter Core'. Custom --vp-font-family-base overrides referencing
Inter4CJK must be updated.
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>
Every option and resolved field is now documented, with consistent
descriptions, `@default` values, and `@see` links to the guides.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`buildConcurrency`, `rewrites`, and `sitemap` are no longer marked
experimental, while `useWebFonts` now is.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
scripts/subsetFonts.py now regenerates the woff2 subsets and fonts.css
from the ranges in scripts/fontSubsets.json (pinned Inter release,
byte-reproducible builds):
- a new lazily-loaded `symbols` subset covers every glyph of the full
font that the existing subsets skipped (arrows, math, geometric
shapes, enclosed alphanumerics, keyboard symbols, ...); U+2318 and
U+21A9 live in the latin subset instead as the theme's chrome uses
them
- Inter4CJK faces are generated as the subset ranges minus East Asian
Ambiguous punctuation/symbols so that CJK fonts render those in CJK
documents, and now also apply to Korean
- the base typography variables move into fonts.css next to the faces;
webfont mode no longer declares the Inter4CJK override (there is no
such family on Google Fonts), and the redundant
`font-optical-sizing: auto` is gone
- fix: the `:lang(zh, ja, ko)` selector list syntax is not supported in
Chrome and silently matched nothing inside the forgiving `:where()`,
so the CJK font handling and `line-break: strict` never applied there
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>
Same emoji token type, shortcuts, and set-replacement semantics, with
fresher emoji data and native types (drops `@types/markdown-it-emoji`).
BREAKING CHANGE: The `defs` property of `markdown.emoji` has been renamed to `definitions`.
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>
Drop-in for our usage: identical defaults (min-level semantics,
tabindex, unique slug handling) and the same permalink/getTokensText
signatures, with proper ESM types - removing the type patch we carried
for markdown-it-anchor.
BREAKING CHANGE: `markdown.anchor` options are now typed by
`@mdit/plugin-anchor`. Common options (`level`, `slugify`, `permalink`,
`getTokensText`, `tabIndex`, etc.) are unchanged, but the deprecated
markdown-it-anchor permalink options (`permalinkSymbol`,
`renderPermalink`, ...) are no longer accepted. Permalink builders like
`headerLink` are named exports of `@mdit/plugin-anchor` instead of
properties of the plugin.
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>
BREAKING CHANGE: The `markdown.attrs.disable` option has been removed. Set `markdown.attrs` to `false` instead.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Moves the inline table_open rule into its own plugin file and adds a
`markdown.tableTabIndex` option (default true) to disable it.
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>
The `typesExternal` regex matched the absolute build path against
`/vitepress/`, so repo-root `.d.ts` files (types/*) were only kept
external when the repo was checked out in a directory named "vitepress".
When built elsewhere, `DefaultTheme` got inlined into
`dist/node/index.d.ts`, orphaning the `declare module` augmentations
from `defaultTheme.ts` and breaking node-only options like
`search.options._render` (regressed in v2.0.0-alpha.18).
Compare paths resolved against this config's directory instead,
normalized for separators and drive-letter casing so it also works on
windows.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BREAKING CHANGE: The deprecated `disableDetailedView` option of local search has been removed. Use `detailedView: false` instead.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Also point docs at `themeConfig.lastUpdated.text` instead of the
removed option.
BREAKING CHANGE: The deprecated `themeConfig.lastUpdatedText` option has been removed. Use `themeConfig.lastUpdated.text` instead.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BREAKING CHANGE: The deprecated `themeConfig.outlineTitle` option has been removed. Use `themeConfig.outline.label` instead.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BREAKING CHANGE: The deprecated `markdown.cjkFriendly` option has been removed. Use `markdown.cjkFriendlyEmphasis` instead.
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.
Divyansh Singh
Henrikh Kantuni
Bjorn Lu
btea
冰冻大西瓜
chencu
PizzaConsole