use .md for snapshots with highlighting · ideas

Hello everyone, long time no see!
I looked at the snapshot files for the zig compiler and it occurred to me, they could be syntax highlighted nicely in editors and in github if we use markdown files. The format would be this (very little change from the current syntax):

# SECTION-HERE
~~~language-id-here-for-syntax-highlight
content
~~~

Here is a screenshot of my Zed with if-then-else.txt reformatted:
if-then-else-md.png
And here is one with VSCode. It doesn't pick up roc syntax, but the markdown headers pop out nicely:
image.png

Talked with Luke, and said that I'd implement it, if you like it. Would be a good way for me to get back into contributing.

Romain Lepert (Jun 14 2025 at 11:04):

i think the convention for markdown codeblocks is to use backticks ` instead of tilde ~

{"foo": 1}

Anton (Jun 14 2025 at 11:51):

Norbert Hajagos (Jun 14 2025 at 12:22):

Yes, that is true. The dsl txt we've been using has ~~~SECTION-NAME as the separator, so I thought it would be more familiar. We could use backticks just as easily. From the markdown spec's perspective, they are interchangeable.
I choose them, because they are easier to spot than the backticks in source code, because they look like section separators, and I think ~ -s will occure less in roc source code than backticks. You can put doc-comments in a roc file which have markdown format i, so searching for "<tripple-backticks-here>roc" has the chance of finding a doc-comment that has some example in them, whereas ppl (as you've noted) don't use ~ for that. Zulip, Github, VSCode, Zed, Obsidian support both all the same (these are the apps I've got that work with md).
There was also a discussion of allowing arbitrary identifiers with backticks, similar to zig's @"my ident" syntax.
These are my rationale, but I don't think there is a wrong answer here.

Norbert Hajagos (Jun 20 2025 at 09:03):

Just a heads up, I've implemented this, and will create a pr on sunday. The syntax so far is the one I wrote, with the addition of sections being separated with a newline.

Luke Boswell (Jun 22 2025 at 23:35):

I had another idea while looking at this... what if instead of "PlainText" for rendering problem reports we modified that to "Markdown" renderer.

Then we would have pretty formatted reports in markdown contexts like our snapshots. We would still have TTY for the terminal, LSP for editors, and HTML for hypertext.

Anthony Bullard (Jun 22 2025 at 23:39):

Luke Boswell (Jun 23 2025 at 01:02):

META

description=Hello world with a block
type=file

SOURCE

# Hello world!

# Multiline comments?
app [main!] { pf: platform "../basic-cli/platform.roc" }

import pf.Stdout

main! = |_| {
    world = "World"
    # Hello
    Stdout.line!("Hello, world!")
}

PROBLEMS

UNDEFINED VARIABLE
Nothing is named line! in this scope.
Is there an import or exposing missing up-top?

Anthony Bullard (Jun 23 2025 at 01:16):

Luke Boswell (Jun 23 2025 at 01:26):

err... I may have gone the extra caffeine :coffee: :coffee: approach :sweat_smile:

Luke Boswell (Jun 23 2025 at 01:27):

I told Jared I'd help merge his type checking Problems PR... and It's super cool seeing these nicely formatted problem reports with Types now

Luke Boswell (Jun 23 2025 at 01:28):