microsoft / microsoft/hve-core

docs: document custom Mermaid theme override in docusaurus README

Open Beginner friendly
#2,938 0 comments 0 reactions 0 assignees View on GitHub
agent-ready documentation needs-triage
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Component

Documentation

## Bug Description

The push that upgraded Mermaid (commit `e37d8d60`, "fix(docs): preserve Mermaid accessibility and grader lineage", #2927) added a new custom theme component at `docs/docusaurus/src/theme/Mermaid/` (`index.tsx`, `styles.module.css`, and `__tests__/Mermaid.test.tsx`) that serializes render attempts, preserves diagrams during keyboard theme transitions, and surfaces render errors through an alert with deterministic retry focus. `docs/docusaurus/README.md` was not updated to describe this swizzled component, its accessibility behavior, or how it fits into the existing "Accessibility conformance harness" section (static lint, component assertions, behavioral e2e, full-site crawl).

## Expected Behavior

`docs/docusaurus/README.md` should mention the `src/theme/Mermaid` override: what it does (render-attempt serialization, diagram preservation across theme changes, retry-focus error alert), why it exists (accessibility requirements for keyboard/theme transitions and error recovery), and how its Jest coverage (`__tests__/Mermaid.test.tsx`) relates to the documented "Component assertions (`jest-axe`)" layer.

## Steps to Reproduce

1. See commit `e37d8d60` (#2927), which added `docs/docusaurus/src/theme/Mermaid/index.tsx`, `styles.module.css`, and `__tests__/Mermaid.test.tsx`.
2. Open `docs/docusaurus/README.md` and note no section describes this custom theme component.

## Additional Context

* New files: `docs/docusaurus/src/theme/Mermaid/index.tsx`, `docs/docusaurus/src/theme/Mermaid/styles.module.css`, `docs/docusaurus/src/theme/Mermaid/__tests__/Mermaid.test.tsx`
* Documentation to update: `docs/docusaurus/README.md` (Accessibility conformance harness section)

> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/35353803755) · auto · 72 AIC · ⌖ 1.75 AIC · ⊞ 9.5K · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)

Contributor guide

Open the contributing guide

Research direction

Read docs/docusaurus/README.md, especially the Accessibility conformance harness section, alongside docs/docusaurus/src/theme/Mermaid/index.tsx, styles.module.css, and __tests__/Mermaid.test.tsx. Update the README to describe the override’s accessibility behavior and explain how its Jest coverage fits the component assertions layer.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, testing
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.