MRender v4.0.0

Highlights

• Introduced a full visual redesign for the documentation shell and bundled markdown UI.
• Refreshed light and dark themes with a new token system, softer surfaces, and updated spacing.
• Updated code blocks, code groups, tables, badges, alerts, sidebar, search, and theme toggle.
• Aligned homepage and supporting demo pages with the new visual language.

Breaking change summary

This release should be treated as a breaking change for consumers that rely on bundled MRender styles.

Even if your TypeScript integration stays the same, the library now renders a meaningfully different UI:

• different radii, spacing, and surface treatment,
• different navigation proportions,
• different code block and code group presentation,
• different table, badge, and alert styling,
• different light/dark theme balance.

If your product or docs portal depends on the previous look, stay on the previous major until you are ready to adopt the new design.

Who should upgrade

• Teams that want the redesigned docs UI as the new baseline.
• Teams that can revalidate screenshots, visual tests, and brand alignment.
• Teams that treat MRender as an opinionated UI layer, not only as a markdown parser.

Who should delay

• Teams with product surfaces already visually tuned around the previous bundled theme.
• Teams with visual regression baselines or documentation screenshots tied to the old UI.
• Teams that need a no-design-change update path.

Affected areas

• Documentation shell: header, sidebar, responsive navigation, TOC.
• Rendered markdown: headings, links, inline code, blockquotes, tables.
• Code experiences: code blocks, grouped tabs, copy affordance, language labels, preview cards.
• Shared UI primitives: badges, alerts, buttons, search trigger, theme toggle.
• Homepage/demo surfaces that ship with the site package.

Upgrade notes

1. Upgrade to v4.0.0 in a separate branch.
2. Treat the release as a visual migration, not as a routine patch/minor dependency bump.
3. Review any custom CSS overrides that target MRender classes, especially shell and code-related selectors.
4. Revalidate pages that depend on dense navigation, code groups, tables, and dark theme.
5. Regenerate screenshots and visual baselines before rollout.

Migration checklist

1. Record screenshots for a representative set of pages before upgrading.
2. Upgrade the library and rebuild the docs/site.
3. Compare one content-heavy page, one code-heavy page, and one table-heavy page.
4. Check custom overrides for selectors tied to: f-header, f-navigation-panel, .f-code-group, .f-code-view, .f-alert, .f-badge, table.
5. Verify dark theme on the same pages, not only light theme.
6. Update visual snapshots, Percy/Chromatic baselines, or documentation screenshots.
7. Roll out only after product/design review if the consuming app exposes MRender UI directly to end users.

Validation

• Verify the sidebar, header, and TOC on desktop widths.
• Verify responsive navigation on mobile/tablet widths.
• Verify code blocks, copy action, code groups, and preview blocks.
• Verify tables and inline code chips on long content pages.
• Verify alerts, badges, and buttons against your existing brand expectations.
• Verify dark theme contrast on docs pages with dense UI.
• Verify homepage/demo pages if you publish the bundled site shell.

Recommended rollout strategy

• If you own the consuming app: upgrade directly on a branch and review visually.
• If external consumers depend on the library: publish v4 as a major and call out the visual break clearly in release notes.
• If some consumers need the previous appearance: keep v3 available for maintenance fixes until they can plan the redesign.

Common pitfalls

• Treating this as “non-breaking” because the Angular API still compiles.
• Validating only markdown parsing while skipping visual review.
• Forgetting custom CSS that depends on previous spacing, width, or border radius values.
• Checking only the homepage and missing dense docs pages with navigation, tables, and code blocks.

Short decision rule

If your consumers see MRender’s bundled UI, then in practice the design is part of the public contract. This release changes that contract and should be adopted like any other major migration.