Convert highlight comments to diff format with + prefix #9540

Copilot · 2026-01-30T20:29:00Z

Tutorial documentation uses // highlight-start, // highlight-end, and // highlight-next-line comments to mark code changes between steps. These comments need to be converted to Expressive Code's native diff format.

Changes

Converted all highlight comments to diff format with + prefix in tutorial documentation files
- Removed // highlight-start / // highlight-end comment blocks
- Removed // highlight-next-line comments
- Changed code blocks to use diff language with lang=<language> to preserve syntax highlighting
- Prefixed added lines with + (git-style diff format)
- Prefixed unchanged lines with space
- Updated 7 tutorial files in getting-started/getting-started-rest/
Uses Expressive Code's native diff rendering with standard git-style + prefix for added lines

Example Conversion

Before:

import "@typespec/http";

using Http;
// highlight-start
@service(#{
  title: "Pet Store",
})
// highlight-end

After:

 import "@typespec/http";
 
 using Http;
+@service(#{
+  title: "Pet Store",
+})

The diff format uses standard git-style syntax with + prefix and green highlighting for added lines, making it immediately clear what was introduced in each tutorial step. The lang=tsp attribute ensures TypeSpec syntax highlighting is preserved while displaying the diff markers.

Files Updated

01-setup-basic-syntax.mdx
02-operations-responses.md
03-handling-errors.md
04-common-parameters.md
05-authentication.md
06-versioning.mdx
07-custom-response-models.md

Original prompt

This section details on the original issue you should resolve

<issue_title>Highlight comments not working</issue_title>
<issue_description>

I believe they were supposed to show what was added in each code block but they seem broken now

https://expressive-code.com/key-features/text-markers/</issue_description>

<agent_instructions>check why those comments in the website docs are not working. They should be highlighting the lines to show what was added between tutorial steps</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Highlight comments not working #9490

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Create custom plugin to handle // highlight-start, // highlight-end, and // highlight-next-line comments - Plugin removes marker comments and applies text markers to highlighted lines - Add plugin to Expressive Code configuration Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

- Remove debug logging - Consolidate into two hooks: preprocessCode and preprocessMetadata - Comments are successfully being removed from rendered code Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

timotheeguerin · 2026-01-30T21:19:17Z

packages/astro-utils/src/expressive-code/plugins/comment-highlights.ts

@copilot lets not make a new plugin, can you find equivalent from expressive-code

I've searched for equivalent functionality in Expressive Code and Starlight, but couldn't find a built-in plugin that supports // highlight-start / // highlight-end comment syntax.

Expressive Code's text-markers plugin only supports:

Meta-based syntax: ```tsp mark={4-6}

Regex-based inline highlighting

Would you like me to:

Convert the documentation to use the standard mark={line-numbers} syntax in code fences?

Or is there a specific Expressive Code plugin/configuration I should be using that I haven't found?

@copilot use mark

Converted all highlight comments to use mark={} syntax. The custom plugin has been removed and all documentation files now use Expressive Code's native text-markers plugin.

Example: // highlight-start comments are now mark={4-7} in the code fence.

Changes in commit 7f31e0a.

- Remove custom comment-highlights plugin - Convert // highlight-start, // highlight-end, and // highlight-next-line comments to mark={} syntax in code fences - Update all tutorial documentation files in getting-started/getting-started-rest - Use Expressive Code's native text-markers plugin with mark={} meta syntax Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-01-30T23:02:27Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh -c ebsite/src/content/docs/docs/emitters/openapi3/reference node de --enable-experimsh gen-extern-signa-c /node_modules/.btspd doc . --enable-experimental --output-dir ../../website/src/content/docs/d--output-dir sh pec/�� lmstxt --output-dir ../../website/src/content/docs/docs/libraries/http/reference node bin/node /library-linter sh . st/node-gyp-bin/tsx ./.scripts/regen-compiler-docs.ts node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

timotheeguerin

@copilot I think it might be clearer if we use the diff syntax and mark those new lines as added. Make sure you keep the language tag too

- Convert all mark={} to ins={} to show highlighted lines as "added" in diff style - Provides clearer visual indication of what was added in each tutorial step - Maintains language tags and all other metadata Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-01-31T16:05:40Z

@copilot I think it might be clearer if we use the diff syntax and mark those new lines as added. Make sure you keep the language tag too

Converted to use ins={} diff syntax to show added lines with green indicators. All language tags are preserved.

Example: ins={4-7} now highlights lines 4-7 as "added" in diff style.

Changes in commit 958fb5d.

timotheeguerin

@copilot no I meant use diff as the code block language(with lang= yo keep the language) and use + to mark the inserted lines

- Change code blocks from language-specific (tsp, yaml) to diff format - Add lang=<language> to preserve syntax highlighting - Prefix added lines with + instead of using ins={} metadata - Prefix unchanged lines with space - Provides standard git-like diff visualization Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-01-31T16:23:06Z

@copilot no I meant use diff as the code block language(with lang= yo keep the language) and use + to mark the inserted lines

Converted to use diff language with lang=tsp and + prefix for added lines. TypeSpec syntax highlighting is preserved.

Example:

 import "@typespec/http";
 
 using Http;
+@service(#{
+  title: "Pet Store",
+})

Changes in commit ae38266.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build node sion�� ebsite/src/content/docs/docs/emitters/openapi3/reference ./tsconfig.build.json _modules/.bin/node -p . && pnpm lish . rsioning/referentspd doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/servers/http-server-csharp/reference --skip-js node p/no�� ite..." --filter "!@typespec/monorepo" run regen-docs sh pec/packages/streams/node_modules/.bin/node signature && tscsh node k/typespec/typestsx ./.scripts/regen-compiler-docs.ts tp/reference (dns block)
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js preview node /ast�� build-samples node /.bin/node build:smoke ocs/libraries/xm/home/REDACTED/work/typespec/typespec/node_modules/.pnpm/@astrojs+star�� /../pagefind@1. sh p-sp�� l --llmstxt --output-dir ../../website/src/conte--llmstxt sh modules/.bin/sh -p . && pnpm lish epo n/sh node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Initial plan

6346e07

Copilot AI assigned Copilot and timotheeguerin Jan 30, 2026

Copilot started work on behalf of timotheeguerin January 30, 2026 20:29 View session

Copilot AI and others added 2 commits January 30, 2026 21:02

Simplify comment-highlights plugin logic

64c48e4

- Remove debug logging - Consolidate into two hooks: preprocessCode and preprocessMetadata - Comments are successfully being removed from rendered code Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix highlight comments not working in documentation~~ Add Expressive Code plugin for comment-based highlight markers Jan 30, 2026

Copilot AI requested a review from timotheeguerin January 30, 2026 21:10

Copilot finished work on behalf of timotheeguerin January 30, 2026 21:10

timotheeguerin reviewed Jan 30, 2026

View reviewed changes

Copilot started work on behalf of timotheeguerin January 30, 2026 21:19 View session

Copilot AI requested a review from timotheeguerin January 30, 2026 21:22

Copilot finished work on behalf of timotheeguerin January 30, 2026 21:22

Copilot started work on behalf of timotheeguerin January 30, 2026 22:49 View session

microsoft-github-policy-service bot added the meta:website TypeSpec.io updates label Jan 30, 2026

Copilot AI changed the title ~~Add Expressive Code plugin for comment-based highlight markers~~ Convert highlight comments to Expressive Code mark syntax Jan 30, 2026

Copilot finished work on behalf of timotheeguerin January 30, 2026 23:02

timotheeguerin reviewed Jan 31, 2026

View reviewed changes

Copilot started work on behalf of timotheeguerin January 31, 2026 16:03 View session

Copilot AI changed the title ~~Convert highlight comments to Expressive Code mark syntax~~ Convert highlight comments to Expressive Code diff syntax Jan 31, 2026

Copilot AI requested a review from timotheeguerin January 31, 2026 16:06

Copilot finished work on behalf of timotheeguerin January 31, 2026 16:06

timotheeguerin reviewed Jan 31, 2026

View reviewed changes

Copilot started work on behalf of timotheeguerin January 31, 2026 16:10 View session

Copilot AI changed the title ~~Convert highlight comments to Expressive Code diff syntax~~ Convert highlight comments to diff format with + prefix Jan 31, 2026

Copilot AI requested a review from timotheeguerin January 31, 2026 16:25

Copilot finished work on behalf of timotheeguerin January 31, 2026 16:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert highlight comments to diff format with + prefix #9540

Convert highlight comments to diff format with + prefix #9540

Copilot AI commented Jan 30, 2026 •

edited

Loading

Uh oh!

timotheeguerin Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

timotheeguerin Jan 30, 2026

Uh oh!

timotheeguerin Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI commented Jan 30, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

timotheeguerin left a comment

Uh oh!

Copilot AI commented Jan 31, 2026

Uh oh!

timotheeguerin left a comment

Uh oh!

Copilot AI commented Jan 31, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Convert highlight comments to diff format with + prefix #9540

Are you sure you want to change the base?

Convert highlight comments to diff format with + prefix #9540

Conversation

Copilot AI commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example Conversion

Files Updated

Comments on the Issue (you are @copilot in this section)

Uh oh!

timotheeguerin Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 30, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

timotheeguerin left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 31, 2026

Uh oh!

timotheeguerin left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 30, 2026 •

edited

Loading

Copilot AI commented Jan 31, 2026 •

edited

Loading