Skip to content

Normalize common fenced-language aliases for highlight.js lazy loading #3723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 4 commits into from
Closed

Normalize common fenced-language aliases for highlight.js lazy loading #3723

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fef8784
Initial plan
Copilot Jul 24, 2026
f1f1af4
Fix code fence language aliases for syntax highlighting
Copilot Jul 24, 2026
6229ed5
Add missing fenced-language aliases for highlight lazy loading
Copilot Jul 24, 2026
b274422
Format hljs alias tests for CI prettier check
Copilot Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/changelog/code-fence-language-aliases.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
type: bug-fix
title: Restore common code fence language aliases for highlighting
products:
- product: docs-builder
target: 0.100.0
areas:
- Rendering
description: |
Restores language alias normalization for highlighted code fences so
aliases such as `ts`, `js`, `py`, and `rb` resolve to their canonical
highlighter languages (`typescript`, `javascript`, `python`, `ruby`).
39 changes: 31 additions & 8 deletions src/Elastic.Documentation.Site/Assets/hljs.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,37 @@ describe('initHighlight', () => {
expect(hljs.listLanguages()).toContain('python')
})

it('resolves aliases to their canonical language', async () => {
const { initHighlight, hljs } = await loadModule()
setCodeBlocks('sh')

await initHighlight()

expect(hljs.listLanguages()).toContain('shell')
})
it.each([
['cmd', 'dos'],
['html', 'xml'],
['sh', 'shell'],
['js', 'javascript'],
['jsx', 'javascript'],
['jsonc', 'json'],
['md', 'markdown'],
['text', 'plaintext'],
['ts', 'typescript'],
['tsx', 'typescript'],
['txt', 'plaintext'],
['py', 'python'],
['rb', 'ruby'],
['yml', 'yaml'],
])(
'resolves alias %s to canonical language %s',
async (alias, canonical) => {
const { initHighlight, hljs } = await loadModule()
setCodeBlocks(alias, canonical)

await initHighlight()

expect(hljs.listLanguages()).toContain(canonical)
const blocks = document.querySelectorAll(
'#markdown-content pre code'
)
expect(blocks[0].getAttribute('data-highlighted')).toBe('yes')
expect(blocks[1].getAttribute('data-highlighted')).toBe('yes')
}
)

it('does not re-highlight a block when invoked concurrently', async () => {
const { initHighlight, hljs } = await loadModule()
Expand Down
13 changes: 13 additions & 0 deletions src/Elastic.Documentation.Site/Assets/hljs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,20 @@ const languageLoaders: Record<string, () => Promise<LanguageFn>> = {
// Alias -> canonical language name. Aliases are registered with hljs once their
// canonical module has loaded so `language-sh` etc. resolve correctly.
const languageAliases: Record<string, string> = {
cmd: 'dos',
html: 'xml',
js: 'javascript',
jsonc: 'json',
jsx: 'javascript',
md: 'markdown',
py: 'python',
rb: 'ruby',
sh: 'shell',
text: 'plaintext',
ts: 'typescript',

@shainaraskas shainaraskas Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot we need more languages here. at least html is also broken

Image

Broken aliases actually used in docs-content / elasticsearch / kibana:

  • js
  • jsx
  • ts
  • tsx
  • text
  • txt
  • py
  • html
  • yml
  • jsonc
  • md
  • cmd

Copilot AI Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in 6229ed5.

Added alias normalization for the requested set: js, jsx, ts, tsx, text, txt, py, html, yml, jsonc, md, cmd (plus existing sh/rb), and expanded hljs.test.ts to verify alias→canonical resolution and highlighted output for each.

@shainaraskas shainaraskas Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wonder if maintaining this separate list will lead to drift / silent bugs in future, but not sure how to fix

tsx: 'typescript',
txt: 'plaintext',
yml: 'yaml',
}

// Caches the registration promise per canonical language so concurrent code blocks
Expand Down