Code annotations for NetLogo not working as expected (by me)

[alan-isaac]

Description

Is it possible to get code annotations in Logo based languages such as NetLogo? (The comment character is a semicolon.)

[mcanouil]

There are roughly 50 languages at the moment. For all the others, code annotation uses # <x>.

[alan-isaac]

1. Is there a list of the languages? Are any in the Logo family, so that the comment character is a semicolon? If so, I could use one of these.
2. I tried ending lines with ;# <x>. In the HTML, the comment past the semicolon is just stripped (and of course the semicolon remains). The code is not wrapped for annotation. The immediately subsequent list does become a definition list, but does not display correctly. (And singe the code lines were not wrapped, a proper display would not help.)

[mcanouil]

Would you mind sharing a reproducible example?

Also note that you might have two issues:

• code annotations
• code highlighting (by Pandoc Skylighting which might not know at all about your language)

[mcanouil]

Independently of the code highlighting support:

• https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/filters/modules/constants.lua#L76-L134

[alan-isaac]

1. I'm only worried about the annotations for now.
2. I see that no Logo variant is currently supported, nor other languages that use a semicolon for commenting.
3. Work calls me, but I'll try to come back soon with a more tested example. In the meantime, the following works fine.

```python
def test() # <1> 
  return 0        # <2>
end
```
1. head
2. body

But the following (based on how I understood your suggestion) does not work:

```netlogo
to-report test ;# <1> 
  report 0        ;# <2>
end
```
1. head
2. body

Even the following fails:

```
to-report test # <1> 
  report 0     # <2>
end
```
1. head
2. body

[mcanouil]

The syntax is comment <X> but by default comment is # for unknown languages.
Quarto and Pandoc do not know "netlogo", so ";" means nothing. It's a regular character.

The "correct" syntax is the first one. The second one work the same as the first one, you get extra ";" because those are not read as particular comment (see above).

Code annotations requires a code block with a language, your third example does not have one.

Because "netlogo" is completely unknown, it does not matter what "language" you set, for example, with the code below you'll get the same output.

---
format: html
---

```whatever
to-report test      # <1> 
  report 0          # <2>
end
```

1. head
2. body

Supported languages for code highlighting: quarto pandoc --list-highlight-languages or (pandoc --list-highlight-languages)

[mcanouil]

FYI, for a related issues with code-annotations and Typst, I've made a Lua filter to workaround the issue and use the proper comment symbol.
You could adapt it to your needs.

• _quarto.yml or document YAML front matter:

filters:
  - path: typst-annotations.lua
    at: pre-quarto

• typst-annotations.lua

--[[
# MIT License
#
# Copyright (c) 2026 Mickaël Canouil
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
]]

--- Convert annotation markers in Typst code blocks.
--- Replaces `// <N>` patterns with `# <N>` at end of lines.
--- This allows using Quarto's code annotation feature with Typst's comment syntax.
--- @param el pandoc.CodeBlock The code block element to process.
--- @return pandoc.CodeBlock The modified code block element.
function CodeBlock(el)
  if el.classes:includes("typst") then
    el.text = el.text:gsub("// (<[0-9]+>)%s*$", "# %1")
    el.text = el.text:gsub("// (<[0-9]+>)%s*\n", "# %1\n")
  end
  return el
end

[mcanouil]

A more general approach:

• _quarto.yml or document YAML front matter:

filters:
  - path: typst-annotations.lua
    at: pre-quarto
code-annotations-mappings:
  netlogo: ";"
  typst: "//"

• code-annotations.lua

--[[
# MIT License
#
# Copyright (c) 2026 Mickaël Canouil
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
]]

--- Default mapping of language classes to their real comment symbols.
--- Users write annotations with the real syntax; filter converts to Quarto's `#`.
--- @type table<string, string>
local DEFAULT_MAPPINGS = {
  typst = "//",
}

--- Configured mappings from document metadata.
--- @type table<string, string>
local configured_mappings = {}

--- Escape special Lua pattern characters in a string.
--- @param str string The string to escape.
--- @return string The escaped string safe for use in gsub patterns.
local function escape_pattern(str)
  local escaped = str:gsub("([%(%)%.%%%+%-%*%?%[%]%^%$])", "%%%1")
  return escaped
end

--- Merge default and user-configured mappings.
--- @param meta pandoc.Meta Document metadata.
--- @return pandoc.Meta The unmodified metadata.
function Meta(meta)
  for lang, symbol in pairs(DEFAULT_MAPPINGS) do
    configured_mappings[lang] = symbol
  end
  if meta["code-annotations-mappings"] then
    for lang, symbol in pairs(meta["code-annotations-mappings"]) do
      configured_mappings[pandoc.utils.stringify(lang)] = pandoc.utils.stringify(symbol)
    end
  end
  return meta
end

--- Convert annotation markers in code blocks.
--- Replaces real comment syntax with `# <N>` so Quarto recognises annotations.
--- @param el pandoc.CodeBlock The code block element to process.
--- @return pandoc.CodeBlock The modified code block element.
function CodeBlock(el)
  for lang, symbol in pairs(configured_mappings) do
    if el.classes:includes(lang) then
      local pattern = escape_pattern(symbol)
      el.text = el.text:gsub(pattern .. " (<[0-9]+>)%s*$", "# %1")
      el.text = el.text:gsub(pattern .. " (<[0-9]+>)%s*\n", "# %1\n")
      break
    end
  end
  return el
end

return {
  { Meta = Meta },
  { CodeBlock = CodeBlock },
}