Basics: 1st package#253
Conversation
✅ Deploy Preview for industrial-experience ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new category configuration and a comprehensive "Voice and tone" style guide under the language basics documentation. The feedback focuses on aligning the new guide with the repository's style guidelines. This includes removing an empty heading with trailing whitespace, rephrasing strict commands to use suggestive language (e.g., "We recommend..."), using sentence case, preferring present simple tense over future tense, and referring to "users" instead of "your users".
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
📝 WalkthroughWalkthroughAdds a new Basics category and language guidance pages, plus a Word-to-Markdown converter and DosAndDonts component for generated documentation. ChangesLanguage basics documentation
Word-to-Markdown conversion tooling
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guidelines/language/basics/voice-and-tone.md`:
- Line 11: The page contains a stray empty H1 that should be removed. In the
markdown content for the voice-and-tone guide, delete the standalone `# ` entry
so the body does not render a blank heading, and rely on the frontmatter title
instead; this change is isolated to the top-level markdown content in the
document.
- Around line 162-164: The related links in the voice-and-tone basics section
still use placeholder anchors, so update the link targets in the markdown to the
real relative paths for the Grammar, Punctuation, and Capitalization guideline
pages. Locate the existing list items in the guidelines document and replace the
dead anchors with the correct document links so navigation works between the
guideline pages.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b7c7153c-d38d-4d4e-8f92-4b937ba0108a
📒 Files selected for processing (2)
docs/guidelines/language/basics/_category_.jsondocs/guidelines/language/basics/voice-and-tone.md
| description: For our UI text, we use natural, conversational language to talk to our users and avoid sounding robotic or funny. | ||
| --- | ||
|
|
||
| # |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the stray empty heading.
Frontmatter already supplies the page title, so # just adds a blank H1 to the page body.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guidelines/language/basics/voice-and-tone.md` at line 11, The page
contains a stray empty H1 that should be removed. In the markdown content for
the voice-and-tone guide, delete the standalone `# ` entry so the body does not
render a blank heading, and rely on the frontmatter title instead; this change
is isolated to the top-level markdown content in the document.
| - [Grammar](#) | ||
| - [Punctuation](#) | ||
| - [Capitalization](#) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace the placeholder related links.
# creates dead anchors here, so these won’t navigate to the other guideline pages. Use the actual relative doc paths instead.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 162-162: No empty links
(MD042, no-empty-links)
[warning] 163-163: No empty links
(MD042, no-empty-links)
[warning] 164-164: No empty links
(MD042, no-empty-links)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guidelines/language/basics/voice-and-tone.md` around lines 162 - 164,
The related links in the voice-and-tone basics section still use placeholder
anchors, so update the link targets in the markdown to the real relative paths
for the Grammar, Punctuation, and Capitalization guideline pages. Locate the
existing list items in the guidelines document and replace the dead anchors with
the correct document links so navigation works between the guideline pages.
Sources: Coding guidelines, Linters/SAST tools
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guidelines/language/basics/inclusive-language.md`:
- Line 12: Remove the stray empty Markdown heading in the document so it does
not render a blank H1 before the content. Edit the inclusive-language guideline
content near the top and delete the lone "#" line, since the frontmatter title
already provides the page heading.
- Around line 66-69: The Markdown table rows for the inclusive-language entries
are split across multiple physical lines, which can break table parsing and
rendering. Update the `black` and `white` rows in the table so each row stays on
a single Markdown line, or use `<br>` within cells if you need line breaks; keep
the table structure consistent around the affected entries.
- Around line 16-20: The placeholder cross-links in the inclusive-language
guidance still point to self-links and need to be replaced before publishing.
Update the referenced links in this section to use the correct relative Markdown
targets, using the existing anchor text for Voice and tone, User management, and
Vocabulary basics so the docs cross-references point to the intended pages
instead of “#”.
In `@docs/guidelines/language/basics/offensive-language.md`:
- Around line 18-22: The cross-references in the offensive-language guidance
still use placeholder hash links and an outdated label, so update the linked
text in this section to point to the actual sibling docs using relative Markdown
links. Fix the references around the entries for Voice and tone, User
management, and Vocabulary basics, and make sure any remaining stale “Voice and
style” wording is replaced with the current page title used elsewhere in the
docs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 18df7a4d-096c-41c2-8c31-4a823c5958c1
📒 Files selected for processing (3)
docs/guidelines/language/basics/inclusive-language.mddocs/guidelines/language/basics/offensive-language.mddocs/guidelines/language/basics/voice-and-tone.md
✅ Files skipped from review due to trivial changes (1)
- docs/guidelines/language/basics/voice-and-tone.md
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guidelines/language/basics/offensive-language.md`:
- Around line 47-48: The table row for the `slave` entry is broken because the
content spans multiple lines and disrupts the 3-column markdown table. Update
the row in the offending table so the `slave` term, its description, and the
replacement suggestions remain in a single valid row structure, using the
existing table content and keeping the row formatting consistent with the other
entries in this guidelines document.
- Line 43: The guidance in the `master (master / slave)` row reads awkwardly
because the “May be acceptable...” fragment is missing a subject; update that
sentence in the table entry to be a complete, grammatical sentence while keeping
the same meaning. Use the existing row content in `offensive-language.md` as the
reference point and rephrase the explanatory text so it clearly states when the
term may be acceptable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 490f2c4a-e73a-46d7-8113-d84829414b0d
📒 Files selected for processing (3)
docs/guidelines/language/basics/inclusive-language.mddocs/guidelines/language/basics/offensive-language.mddocs/guidelines/language/basics/voice-and-tone.md
✅ Files skipped from review due to trivial changes (2)
- docs/guidelines/language/basics/inclusive-language.md
- docs/guidelines/language/basics/voice-and-tone.md
| | backlog grooming | Associated with manipulative behavior. Scrum associations no longer use the term. | - backlog refinement | | ||
| | hang | Evokes imagery of execution by hanging, which can be disturbing for users. Often used in contexts involving system processes or application states. | - freeze<br/>- stall<br/>- stop responding<br/>- become unresponsive | | ||
| | kill | Evokes violence and death which can sound aggressive in professional contexts. Used historically for terminating processes and operations. | - stop<br/>- close<br/>- quit<br/>- end | | ||
| | master (master / slave) | Reinforces associations with slavery and dominance. May be acceptable when it describes expertise, original versions, or authoritative sources such as "master key" or "master copy”. | - source / replica<br/>- primary / remote<br/>- leader / follower<br/>- main branch<br/>- host<br/>- original<br/>- manager | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Tighten this sentence fragment.
May be acceptable... is missing the subject, which makes the row read awkwardly. Rephrase it as a full sentence so the guidance is clearer.
✏️ Suggested fix
-| master (master / slave) | Reinforces associations with slavery and dominance. May be acceptable when it describes expertise, original versions, or authoritative sources such as "master key" or "master copy”. | - source / replica<br/>- primary / remote<br/>- leader / follower<br/>- main branch<br/>- host<br/>- original<br/>- manager |
+| master (master / slave) | Reinforces associations with slavery and dominance. It may be acceptable when it describes expertise, original versions, or authoritative sources such as "master key" or "master copy". | - source / replica<br/>- primary / remote<br/>- leader / follower<br/>- main branch<br/>- host<br/>- original<br/>- manager |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | master (master / slave) | Reinforces associations with slavery and dominance. May be acceptable when it describes expertise, original versions, or authoritative sources such as "master key" or "master copy”. | - source / replica<br/>- primary / remote<br/>- leader / follower<br/>- main branch<br/>- host<br/>- original<br/>- manager | | |
| | master (master / slave) | Reinforces associations with slavery and dominance. It may be acceptable when it describes expertise, original versions, or authoritative sources such as "master key" or "master copy". | - source / replica<br/>- primary / remote<br/>- leader / follower<br/>- main branch<br/>- host<br/>- original<br/>- manager | |
🧰 Tools
🪛 LanguageTool
[style] ~43-~43: To form a complete sentence, be sure to include a subject.
Context: ...ssociations with slavery and dominance. May be acceptable when it describes experti...
(MISSING_IT_THERE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guidelines/language/basics/offensive-language.md` at line 43, The
guidance in the `master (master / slave)` row reads awkwardly because the “May
be acceptable...” fragment is missing a subject; update that sentence in the
table entry to be a complete, grammatical sentence while keeping the same
meaning. Use the existing row content in `offensive-language.md` as the
reference point and rephrase the explanatory text so it clearly states when the
term may be acceptable.
Source: Linters/SAST tools
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
scripts/README-word-to-markdown.md (1)
160-168: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove duplicate heading and misplaced installation content.
Lines 160–168 repeat the "Post-Conversion Tips" heading and contain installation instructions that already appear at lines 19–21. This appears to be an editing error. Remove this duplicate section, or replace the heading with the intended content (e.g., "Troubleshooting" if that was the goal).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/README-word-to-markdown.md` around lines 160 - 168, Remove the duplicated “Post-Conversion Tips” section from the README-word-to-markdown content and fix the misplaced install snippet so it no longer repeats the heading or duplicates the package installation instructions. Keep the existing installation guidance only in its original location, and if this block was meant to introduce a different topic, update the heading and body accordingly using the nearby README section structure as a guide.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guidelines/language/basics/grammar.md`:
- Line 11: The markdown in the Grammar doc contains an empty top-level heading
that renders a blank h1. Remove the stray heading or replace it with meaningful
text, and keep the frontmatter title as the page title; check the top of the
file around the existing heading markup to ensure there is no standalone “#”
left behind.
- Around line 261-265: The list entry for Localization contains an empty anchor
that does not resolve to real content, so update the reference in the markdown
list to point to the correct Localization page or remove the Localization item
entirely until that page exists. Use the surrounding list in the grammar guide
to locate and adjust the existing Localization entry alongside the other
messaging and license links.
In `@scripts/word-to-markdown.ts`:
- Around line 12-14: The prerequisite text in the script header includes an
unnecessary sharp dependency even though scripts/word-to-markdown.ts does not
use sharp. Update the requirements/usage documentation in the relevant comment
blocks and any related setup text to only list the packages actually imported by
the script, keeping the references aligned with the existing word-to-markdown
conversion flow.
- Around line 216-233: The replacement in word-to-markdown.ts around the
markdown.replace handler for the Do/Don’t section drops the visible labels from
the output. Update this transformation so the dos-and-donts wrapper generated
from the heading matching regex still includes explicit “Do” and “Don’t” labels
inside the respective dos and donts blocks, or otherwise preserves the original
heading text, while keeping the existing structure in the replacement callback.
- Around line 302-310: Remove the unsupported description fields from the
parseArgs option descriptors in word-to-markdown.ts. The options object used by
parseArgs should only include valid properties like type, short, multiple, and
default, so update the output and help entries in the parseArgs configuration to
eliminate description while keeping the existing behavior in the surrounding
argument parsing logic.
- Around line 107-129: The Word-to-Markdown flow is still relying on Mammoth’s
default base64 image handling, so the manual `media/` replacement in the
`convertToHtml` block never fixes `<img>` sources. Update the
`mammoth.convertToHtml` call in `word-to-markdown.ts` to use a custom
`convertImage` handler via `mammoth.images.imgElement`, write each extracted
image to the `./images` output directory, and return the relative `src` path for
the generated file. Keep the image-writing logic near the existing
`imageMap`/HTML conversion code, and remove or adjust the later `html.replace`
pass so it no longer assumes `media/...` references.
In `@src/components/DosAndDonts/DosAndDonts.tsx`:
- Around line 8-31: The DosAndDonts, Dos, and Donts components are using an
invalid markdown prop on div elements, which triggers React/TypeScript DOM
attribute errors. Update the JSX in DosAndDonts.tsx to use data-markdown instead
of markdown on each wrapper div, keeping the existing component structure and
props unchanged.
---
Nitpick comments:
In `@scripts/README-word-to-markdown.md`:
- Around line 160-168: Remove the duplicated “Post-Conversion Tips” section from
the README-word-to-markdown content and fix the misplaced install snippet so it
no longer repeats the heading or duplicates the package installation
instructions. Keep the existing installation guidance only in its original
location, and if this block was meant to introduce a different topic, update the
heading and body accordingly using the nearby README section structure as a
guide.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 32c0a648-abfd-4c83-b121-9c1b86de25bf
📒 Files selected for processing (9)
docs/guidelines/language/basics/grammar.mddocs/guidelines/language/basics/inclusive-language.mddocs/guidelines/language/basics/offensive-language.mdscripts/README-word-to-markdown.mdscripts/word-to-markdown.tssrc/components/DosAndDonts/DosAndDonts.scsssrc/components/DosAndDonts/DosAndDonts.tsxsrc/components/DosAndDonts/README.mdsrc/components/DosAndDonts/index.ts
✅ Files skipped from review due to trivial changes (2)
- docs/guidelines/language/basics/offensive-language.md
- docs/guidelines/language/basics/inclusive-language.md
| no_single_tab: true | ||
| description: Explore the most important grammar points in UX writing for industrial applications. | ||
| --- | ||
| # |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove or fill the empty heading.
The # on Line 11 renders as an empty <h1> element. Since the frontmatter already defines title: Grammar, this appears to be unintentional and will produce a blank heading on the page.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guidelines/language/basics/grammar.md` at line 11, The markdown in the
Grammar doc contains an empty top-level heading that renders a blank h1. Remove
the stray heading or replace it with meaningful text, and keep the frontmatter
title as the page title; check the top of the file around the existing heading
markup to ensure there is no standalone “#” left behind.
| - [Toast messages](../messaging/toast-messages.mdx) | ||
| - [Error messages](../messaging/error-messages.mdx) | ||
| - [Warning messages](../messaging/warning-messages.mdx) | ||
| - [License management](../menu-functions-and-ui-labels/license-management.md) | ||
| - [Localization](#) No newline at end of file |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix or remove the empty Localization link.
The [Localization](#) link on Line 265 points to a non-existent anchor. Either link it to the actual Localization page or remove the entry until that content is available.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 265-265: No empty links
(MD042, no-empty-links)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guidelines/language/basics/grammar.md` around lines 261 - 265, The list
entry for Localization contains an empty anchor that does not resolve to real
content, so update the reference in the markdown list to point to the correct
Localization page or remove the Localization item entirely until that page
exists. Use the surrounding list in the grammar guide to locate and adjust the
existing Localization entry alongside the other messaging and license links.
| * Requirements: | ||
| * npm install mammoth turndown sharp | ||
| */ |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Stop telling users to install sharp.
This script never imports or uses sharp, so the prerequisite text adds an unnecessary native dependency to the happy path.
Also applies to: 30-33, 331-333
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/word-to-markdown.ts` around lines 12 - 14, The prerequisite text in
the script header includes an unnecessary sharp dependency even though
scripts/word-to-markdown.ts does not use sharp. Update the requirements/usage
documentation in the relevant comment blocks and any related setup text to only
list the packages actually imported by the script, keeping the references
aligned with the existing word-to-markdown conversion flow.
| // Convert Word document to HTML | ||
| console.log('\n⚙️ Converting .docx to HTML...'); | ||
| const result = await mammoth.convertToHtml({ | ||
| path: input, | ||
| styleMap: [ | ||
| 'p[style-name="Heading 1"] => h1', | ||
| 'p[style-name="Heading 2"] => h2', | ||
| 'p[style-name="Heading 3"] => h3', | ||
| 'p[style-name="Heading 4"] => h4', | ||
| 'b => strong', | ||
| 'i => em', | ||
| ], | ||
| }); | ||
|
|
||
| let html = result.value; | ||
|
|
||
| // Replace image references | ||
| if (imageMap.size > 0) { | ||
| imageMap.forEach((mdPath, docxPath) => { | ||
| const fileName = path.basename(docxPath); | ||
| const regex = new RegExp(`media/${fileName.replace(/[.*+?^${}()|\\[\]\\\\]/g, '\\$&')}`, 'g'); | ||
| html = html.replace(regex, mdPath); | ||
| }); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
🧩 Analysis chain
🌐 Web query:
In mammoth.js, what does convertToHtml() do with images by default, and how should convertImage be used to save images as files instead of emitting data URIs?
💡 Result:
In mammoth.js, the convertToHtml function converts images into elements by default, where the image data is embedded directly into the src attribute as a base64-encoded data URI [1][2][3]. To save images as separate files instead of emitting data URIs, you must override the default behavior by providing a custom image converter to the convertImage option [1][2]. You can create a custom converter using mammoth.images.imgElement(func), where the function reads the image data and returns the desired attributes for the
element, such as a file path for the src [1][4][3]. Example approach: You can use a custom function to write the image buffer to the file system using Node.js fs modules and return the corresponding file path as the src [5][6]. const fs = require('fs'); const path = require('path'); let imageCounter = 1; const imgDir = './output/images'; const options = { convertImage: mammoth.images.imgElement(function(image) { return image.read("base64").then(function(imageBuffer) { const imgName =
image${imageCounter++}.png; // Simplify type handling as needed const imgPath = path.join(imgDir, imgName); fs.writeFileSync(imgPath, imageBuffer, 'base64'); return { src: imgPath }; }); }) }; mammoth.convertToHtml({ path: "input.docx" }, options).then(result => { fs.writeFileSync('output.html', result.value); }); Note that while the library's command-line interface (CLI) supports an --output-dir option to automatically handle saving images to separate files, the Node.js API requires this manual implementation [1][5].
Citations:
- 1: https://github.com/mwilliamson/mammoth.js/blob/master/README.md
- 2: https://github.com/mwilliamson/mammoth.js/
- 3: https://www.npmjs.com/package/mammoth
- 4: https://github.com/mwilliamson/mammoth.js/tree/refs/heads/master
- 5: Save Images via Node API (easily) mwilliamson/mammoth.js#237
- 6: Cannot get imageConvert to work mwilliamson/mammoth.js#41
Wire convertImage to save extracted images and update <img> sources.
convertToHtml() defaults to embedding images as base64 data URIs. Without configuring the convertImage option, the extracted image files are never linked, and the subsequent manual string replacement of media/ paths fails to process the base64 strings, breaking the image extraction flow.
Use mammoth.images.imgElement to read image buffers, write them to the ./images directory manually, and return the corresponding relative file path as src.
const imageMap = new Map<string, string>();
let imageIndex = 0;
// 1. Define custom image conversion
const convertImageOptions = {
convertImage: mammoth.images.imgElement((image) => {
return image.read("base64").then((imageBuffer) => {
const ext = image.contentType.split("/")[1] || "png";
const fileName = `image_${++imageIndex}.${ext}`;
const imagePath = path.join(outputDir, "images", fileName);
fs.mkdirSync(path.dirname(imagePath), { recursive: true });
fs.writeFileSync(imagePath, Buffer.from(imageBuffer, "base64"));
imageMap.set(`media/${fileName}`, `./images/${fileName}`);
return { src: `./images/${fileName}` };
});
}),
};
// 2. Pass options to convertToHtml
const result = await mammoth.convertToHtml({ path: input }, {
styleMap: [...],
convertImage: convertImageOptions.convertImage,
});
// 3. Remove the manual string replacement logic as the `src` attributes are now correct🧰 Tools
🪛 ast-grep (0.44.0)
[warning] 126-126: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(media/${fileName.replace(/[.*+?^${}()|\\[\]\\\\]/g, '\\$&')}, 'g')
Note: [CWE-1333] Inefficient Regular Expression Complexity
(regexp-from-variable)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/word-to-markdown.ts` around lines 107 - 129, The Word-to-Markdown
flow is still relying on Mammoth’s default base64 image handling, so the manual
`media/` replacement in the `convertToHtml` block never fixes `<img>` sources.
Update the `mammoth.convertToHtml` call in `word-to-markdown.ts` to use a custom
`convertImage` handler via `mammoth.images.imgElement`, write each extracted
image to the `./images` output directory, and return the relative `src` path for
the generated file. Keep the image-writing logic near the existing
`imageMap`/HTML conversion code, and remove or adjust the later `html.replace`
pass so it no longer assumes `media/...` references.
| formatted = markdown.replace( | ||
| /^(#{1,6})\s+(?:Dos?|Do's?)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)(?=(#{1,6})\s+(?:Don'?ts?|Don't))\3\s+(?:Don'?ts?|Don't)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)/gm, | ||
| (match, heading1, dosList, heading2, dontsList) => { | ||
| // Preserve the heading levels and create dos/don'ts structure | ||
| const level = heading1; | ||
|
|
||
| return `<div className="dos-and-donts" markdown="true"> | ||
| <div className="dos" markdown="true"> | ||
|
|
||
| ${dosList.trim()} | ||
|
|
||
| </div> | ||
| <div className="donts" markdown="true"> | ||
|
|
||
| ${dontsList.trim()} | ||
|
|
||
| </div> | ||
| </div>`; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Preserve the Do/Don't labels in the generated output.
This replacement removes the source headings and leaves two unlabeled boxes, so readers have to infer meaning from color/icon alone. Keep visible labels inside each column or preserve the original headings.
Suggested fix
return `<div className="dos-and-donts" markdown="true">
<div className="dos" markdown="true">
+<h4>Do</h4>
${dosList.trim()}
</div>
<div className="donts" markdown="true">
+<h4>Don't</h4>
${dontsList.trim()}
</div>
</div>`;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| formatted = markdown.replace( | |
| /^(#{1,6})\s+(?:Dos?|Do's?)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)(?=(#{1,6})\s+(?:Don'?ts?|Don't))\3\s+(?:Don'?ts?|Don't)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)/gm, | |
| (match, heading1, dosList, heading2, dontsList) => { | |
| // Preserve the heading levels and create dos/don'ts structure | |
| const level = heading1; | |
| return `<div className="dos-and-donts" markdown="true"> | |
| <div className="dos" markdown="true"> | |
| ${dosList.trim()} | |
| </div> | |
| <div className="donts" markdown="true"> | |
| ${dontsList.trim()} | |
| </div> | |
| </div>`; | |
| formatted = markdown.replace( | |
| /^(#{1,6})\s+(?:Dos?|Do's?)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)(?=(#{1,6})\s+(?:Don'?ts?|Don't))\3\s+(?:Don'?ts?|Don't)\s*\n((?:(?:^-.*(?:\n|$))+(?:\n)?)+)/gm, | |
| (match, heading1, dosList, heading2, dontsList) => { | |
| // Preserve the heading levels and create dos/don'ts structure | |
| const level = heading1; | |
| return `<div className="dos-and-donts" markdown="true"> | |
| <div className="dos" markdown="true"> | |
| <h4>Do</h4> | |
| ${dosList.trim()} | |
| </div> | |
| <div className="donts" markdown="true"> | |
| <h4>Don't</h4> | |
| ${dontsList.trim()} | |
| </div> | |
| </div>`; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/word-to-markdown.ts` around lines 216 - 233, The replacement in
word-to-markdown.ts around the markdown.replace handler for the Do/Don’t section
drops the visible labels from the output. Update this transformation so the
dos-and-donts wrapper generated from the heading matching regex still includes
explicit “Do” and “Don’t” labels inside the respective dos and donts blocks, or
otherwise preserves the original heading text, while keeping the existing
structure in the replacement callback.
| output: { | ||
| type: 'string', | ||
| short: 'o', | ||
| description: 'Output directory (default: ./markdown-output)', | ||
| }, | ||
| help: { | ||
| type: 'boolean', | ||
| short: 'h', | ||
| description: 'Show help message', |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
🧩 Analysis chain
🌐 Web query:
In Node.js util.parseArgs, are descriptionfields supported inside option definitions, or are only properties liketype, short, multiple, and default allowed?
💡 Result:
In Node.js util.parseArgs, the description field is not a supported property for option definitions [1][2]. The official documentation specifies that only the following properties are supported within the options configuration object: type, multiple, short, and default [1][3]. While some third-party libraries or custom wrappers may implement a description field to generate help or usage text [4][5], util.parseArgs itself does not recognize, use, or document it [1][2]. The design of util.parseArgs remains focused on providing a low-level, stable primitive for argument parsing [6][1]. Consequently, any description fields included in your configuration will be ignored by the standard library function, though they may persist in your configuration object for use by other tools [6].
Citations:
- 1: https://nodejs.org/api/util.html
- 2: https://nodejs.org/api/util.md
- 3: https://github.com/nodejs/node/blob/main/doc/api/util.md
- 4: Add support to print help/usage of util.parseArgs nodejs/node#56184
- 5: https://docs.machbase.com/neo/jsh/modules/util/parseargs/
- 6: Committing not to ever use a
descriptionfield / maybe reserving some other fields for future use pkgjs/parseargs#86
Remove unsupported description fields from parseArgs() options.
Node.js util.parseArgs does not support the description property in option descriptors. Only type, short, multiple, and default are valid. Including description creates type mismatches in TypeScript and unused data at runtime.
Code snippet
output: {
type: 'string',
short: 'o',
description: 'Output directory (default: ./markdown-output)',
},
help: {
type: 'boolean',
short: 'h',
description: 'Show help message',🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/word-to-markdown.ts` around lines 302 - 310, Remove the unsupported
description fields from the parseArgs option descriptors in word-to-markdown.ts.
The options object used by parseArgs should only include valid properties like
type, short, multiple, and default, so update the output and help entries in the
parseArgs configuration to eliminate description while keeping the existing
behavior in the surrounding argument parsing logic.
| export const DosAndDonts: React.FC<DosAndDontsProps> = ({ children }) => ( | ||
| <div className="dos-and-donts" markdown="true"> | ||
| {children} | ||
| </div> | ||
| ); | ||
|
|
||
| interface DosProps { | ||
| children: React.ReactNode; | ||
| } | ||
|
|
||
| export const Dos: React.FC<DosProps> = ({ children }) => ( | ||
| <div className="dos" markdown="true"> | ||
| {children} | ||
| </div> | ||
| ); | ||
|
|
||
| interface DontsProps { | ||
| children: React.ReactNode; | ||
| } | ||
|
|
||
| export const Donts: React.FC<DontsProps> = ({ children }) => ( | ||
| <div className="donts" markdown="true"> | ||
| {children} | ||
| </div> |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
🧩 Analysis chain
🌐 Web query:
In React 18 with TypeScript, are arbitrary DOM attributes like markdownallowed on a native
, or should custom attributes use the data-* prefix?
💡 Result:
In React 18 with TypeScript, you should use the data-* prefix for custom attributes on native DOM elements like <div> to maintain standard compliance and type safety [1][2]. While React 16+ technically allows passing arbitrary, non-standard attributes to DOM elements at runtime [3][1][4], TypeScript will flag these as errors because they are not defined in the standard library's HTMLAttributes interface [5][6]. Key points regarding this practice: 1. Recommended Approach: Use data-* (e.g., data-markdown="true"). The data-* attributes are standard HTML5 features specifically designed for storing custom data on elements [2]. TypeScript recognizes these patterns as valid attributes [6]. 2. TypeScript Limitations: If you attempt to use a custom attribute like markdown="true" without the data- prefix, TypeScript will trigger a "Property 'markdown' does not exist" error [6]. This is because the TypeScript compiler relies on a predefined list of valid HTML attributes for intrinsic elements [5][6]. 3. Escape Hatches (Not Recommended): While you could use module augmentation to add arbitrary attributes to the React.HTMLAttributes interface or use @ts-ignore, these approaches are generally discouraged as they bypass the type safety that TypeScript provides [7][5][4]. 4. Accessing Data: When using data-* attributes, you can easily access the values in your code via the standard DOM dataset API (e.g., event.currentTarget.dataset.markdown) [2][8]. In summary, for custom metadata, use data-markdown instead of markdown to satisfy both browser standards and TypeScript's type checking [6][1][2].
Citations:
- 1: https://legacy.reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html
- 2: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/data-*
- 3: https://legacy.reactjs.org/docs/dom-elements.html
- 4: https://stackoverflow.com/questions/31273093/how-to-add-custom-html-attributes-in-jsx
- 5: https://github.com/typescript-cheatsheets/react/blob/main/docs/advanced/types-react-ap.md
- 6: https://stackoverflow.com/questions/67673754/why-kebab-case-non-standard-attributes-are-allowed-while-others-arent-and-how
- 7: [@types/react] Extending IntrinsicElements with arbitrary attributes DefinitelyTyped/DefinitelyTyped#48838
- 8: https://stackoverflow.com/questions/20377837/how-to-access-custom-attributes-from-event-object-in-react
Replace invalid markdown prop with data-markdown
The markdown attribute is not a valid React DOM property for div. TypeScript will flag this as an error because it is not part of the standard HTMLAttributes interface. While React may pass unknown attributes to the DOM at runtime, standard compliance and type safety require using the data-* prefix for custom attributes. Update the code to use data-markdown="true" to resolve the type error.
Current code
export const DosAndDonts: React.FC<DosAndDontsProps> = ({ children }) => (
<div className="dos-and-donts" markdown="true">
{children}
</div>
);
export const Dos: React.FC<DosProps> = ({ children }) => (
<div className="dos" markdown="true">
{children}
</div>
);
export const Donts: React.FC<DontsProps> = ({ children }) => (
<div className="donts" markdown="true">
{children}
</div>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/components/DosAndDonts/DosAndDonts.tsx` around lines 8 - 31, The
DosAndDonts, Dos, and Donts components are using an invalid markdown prop on div
elements, which triggers React/TypeScript DOM attribute errors. Update the JSX
in DosAndDonts.tsx to use data-markdown instead of markdown on each wrapper div,
keeping the existing component structure and props unchanged.
1 participant
💡 What is the current behavior?
Currently we have one page with all basic UX writing rules.
🆕 What is the new behavior?
👨💻 Help & support
Please help us to publish these pages in iX UX Writing guidelines.
Summary by CodeRabbit