Now that the language seems pretty stable, it might be time to organize a docathon to update all the docs? Perhaps a few volunteers can prepare a list of docs to update/write and provide some general instructions, then anyone can contribute over a weekend or a week?
Is the langref link to the website broken? the langref is complete, but the website says it is heavily WIP and there is a lot missing i.e
![]()
![]()
Other than the Tutorial which Richard has said he wants to write ... what other docs need updating?
Yeah, it's this sentence "This is heavily WIP!" that made me think we need to complete/update the docs before 0.1.0. If the langref is already done, great! :grinning_face_with_smiling_eyes:
I ran into a number of outdated statements here and there, such as saying that an if must always have an else, even though this is no longer true since we have return now.
The playground is also outdated, I'm not sure why (I thought we had fixed that).
The examples page feels disorganized. It should perhaps be organized by categories, and/or examples should perhaps have tags about their main concepts or main API.
Things feel a bit disjointed: perhaps the langref and standard lib docs should point to examples, and vice versa.
Also, several things are not covered by examples, if I'm not mistaken:
for, while, and var versus foldwhere constraintsMoreover, having some examples of common packages and platforms would be good, such as unicode (in more depth), path, roc-ray, etc. Alternatively we could just point to these packages, but right now we have examples for basic-cli, basic-webserver, http, roc-ascii, roc-parser, and roc-random, so I think it would make sense. The platform and package examples should each be in their own section in the examples page.
Perhaps a "Tips and tricks" or "Best practices" page would be useful, and a docathon would help figure out what to recommend. For example I like to use Try(Foo, _) during dev and be more specific only at the end, switching to Try(Foo, [A, B, C]).
There's certainly more to do. Completing this To-Do list is what I suggested for step 1. Perhaps there's not enough work to justify step 2, but in many projects I've worked on, the docs weren't get enough love, and I've found that a short focused effort is a good solution to solve that.
Richard Feldman said:
The focus from there would be fixing bugs without regressing other things, which I'd like to do by getting a corpus of projects that work on RC1, and having CI tell us when we have broken them in a nightly release.
The broader examples might tie in nicely with the new requirement we have for testing things outside the repository -- the failing examples would tell us when we have broken things downstream, but also not block PRs.
I've been setting up my CI workflows so I can know when a nightly breaks something (either I need to patch the platform and make a new release, or report a bug back upstream).
I'm happy to submit a few new examples. Btw, several examples are in the examples repo but not online (e.g., custom literals, hello web, webapps with Elm, sorting strings, multiline-comments)
The website and CI supporting that definitely need some love :smile:
The benefits of a docathon go beyond simply improving the docs: it can be a fun community-building activity, an opportunity to discover & discuss other issues, and a way to get people to care more about docs if they've contributed to them.
Apparently the reason why the website is still using an old playground and is missing several examples is that the latest Cloudflare production build failed. I'm not sure who has the Cloudflare logins, but they are needed to access the Cloudflare logs to determine what the problem is.
ChatGPT suggests that a likely build blocker is builtin documentation generation: main still uses the old command, while PR #157 switches to the required roc docs --builtins.
I am looking at the cloudflare build failure, the website is out of date because of the large amount of breaking Roc changes, things that break after updating and other random issues.
it might be time to organize a docathon to update all the docs?
Richard mentioned (I'm paraphrasing) in the last meetup that he's opinionated about the docs, so we want to make sure that we're not just filling out the docs in a distributed effort.
The website has been successfully updated :tada:
Sounds good, thanks @Anton.
As I mentioned previously, I would like to contribute too, but I don't write Roc (yet) so feel free to tag me as a reviewer. Might even be helpful to have a perspective from someone who is not in the weeds as much. I'll also see id I can push my previous feedback as PRs
I've submitted PR #163 to organize the Examples page into sections and give each example a little description:
![]()
I also submitted PR #310 with 26 new examples covering more Roc language features, packages, and platforms:
Types and functions
Box.where constraints and reusable aliases.map and map!.Collections and iteration
for, while, var, and fold.for!, and custom file-reading streams.Error handling
? inside expect.Parsing and encoding
Organizing and publishing code
roc docs.Packages
Platforms
I put them all in one PR for convenience, but if you want me to break it into smaller chunks, please let me know.
Aurélien Geron said:
I put them all in one PR for convenience, but if you want me to break it into smaller chunks, please let me know.
Yes please :sweat_smile: I'd love to be able to get quick reviews done between other things.
Thanks for making all of them :heart:
No problem @Anton , I just submitted 26 PRs (#316 to #341), and closed the big one (#310). It's more digestible now. :sweat_smile:
Anybody has time to look at this one or is the mini-tutorial going to be replaced? https://github.com/roc-lang/roc/pull/11729
Yes, we indeed plan to replace it before 0.1
There are 15 new code examples on the website, check them out!
Thanks to @Anton who reviewed them all, and to @Luke Boswell for reviewing the PR to update the website.
Love your work polishing all these examples and sharing that with the community. I am sure many people will find this helpful to follow Roc 0.1 and all the changes in our new compiler.
Currently browsing through those examples. Very nice so far.
Found a minor bug: the link on the https://www.roc-lang.org/examples/RecursiveTypes/README page towards the nested types example is broken (i.e. there is an ".md" at the url end) and also the other direction the link on the nested to the recursive types page.
Thanks Hardy, I'll fix these.
I was just looking at our syntax highlighting on the website... I feel like we could replace it with the tree-sitter wasm module and that would give us more fidelity and better highlighting. I'm not sure about the trade-off and haven't looked into it. Or perhaps we could use roc-parser now that has Roc syntax. Just leaving the thought here, I might look at this and explore the options later.
I'd rather not do that
I already ported our real tokenizer to JS and simplified the code to get it to a small asset size
I think if we switched to tree-sitter we would end up with a bigger asset, that ran slower (bc wasm is async so there would be a flash of unstyled content) and with actually less fidelity than what we have now :smile:
Alg, I just though the current highlighting could be better (as compared to tree-sitter etc) but I didn't look into it.
We could just improve the JS I guess, it's probably not hard
Do you remember which repository has all that?
found it
I forgot I already did a heap of work on our zig compiler semantic tokens -- so I can just re-use that in a differential harness to help improve the JS.
That uses type checked CIR as the authority.
cool, sounds good!
Didn't take long at all.. this is the home page after the first pass
![]()
Very nice! The dark purple might be a little bit hard to read.
yeah I'm also not a fan of the yellow, if we can avoid it
I feel like purple, teal, gray, and black/white (depending on light mode vs dark mode) are uncontroversial since those are part of the color scheme, and if we really need another one, I'd go with some shade of blue that looks nice with the purple and teal
I'll iterate on it a little after lunch. I'm also adding a script that checks WCAG AA for our colors, I think we already did that and I'm not proposing we change them.
Also do we have plans to lift the tutorial back into the website from a markdown document? Even if it's just in its current form?
FYI, I'm planning to work on these improvements to the docs in the next few days:
If you have any suggestions, please let me know!
PR #179 moves the tutorial to the website.
I was thinking about giving the Install pages some love... but I'm not sure
Yes, it probably needs just a little bit of text, but I like how straight-to-the-point it currently is, so we don't want a wall of text either. The "Build Roc from Source" page could also be lifted into the website.
I dont mind this pallet
![]()
Beautiful! The dark purple is still a bit too dark for me, but I could live with it.
![]()
The right curly bracket should be purple too.
haha already got that one :sweat_smile:
I've found a bunch of others too, doing another round of cleanup
I've been doing some research to find good categories for "semantic roles"
![]()
I've done these points:
It looks like this:
![]()
Any suggestions before I submit the PR?
Looking good. I'd nitpick some alignment things, like the search bar
Ah good point. I wanted to avoid using vertical space (especially for mobile devices), but the search bar will just scroll to the top when the user scrolls down, so that's not a problem. I'll lower it to the level of the "Docs Home" text in the panel.
Screencast from 2026-10-29 14-28-18.webm
Very nice.
There are a few colored letters here and there (you probably noticed already):
![]()
I think thats just the recording being goofy
Here's the site preview from the PR https://semantic-highlighting-roc.cc02oj5kr.workers.dev/
Just submitted PR #181 to add some content to the Docs landing page and keep the same header as the rest of the site. I believe I fixed the alignment issues; it now looks like this:
![]()
And on a phone:
![]()
Aurélien Geron said:
Just submitted PR #181 to add some content to the Docs landing page and keep the same header as the rest of the site. I believe I fixed the alignment issues; it now looks like this:
And on a phone:
The search and hamburger don't quite line up with the content gutters. Minior nitpick though :wink:
Oh good point, thanks, I only checked the alignment on the Desktop.
Fixed:
![]()
#contributing > markdown may be relevant here.
Aurélien Geron said:
Just submitted PR #181 to add some content to the Docs landing page and keep the same header as the rest of the site. I believe I fixed the alignment issues; it now looks like this:
And on a phone:
I feel like this is a very minor nitpick, and it's miles better than what came before, but I haven't seen much other use of rounded corners in the rest of the roc site, and imo it jars a bit here. E.g. navigation borders, search box, Examples/FAQ section underlines, code snippets in docs. I'm not the biggest sharp-corners fan, but I did feel like it was a bit of the website's charm.
(Thank you for working on this!!!)
Yes, no rounded corners please, I think I once made a CI check for that. The logo is very sharp and geometric, so rounded corners don't really fit with that. Thanks for working on this though :heart:
Sounds good, I'll tweak that. :+1:
Here's the new look without rounded corners:
![]()
I like it :)
One minor thing I would change is "join the community". It asks for immediate commitment, the reader may not feel ready to join the community and have doubts about what that will set in motion. "Take a look at our group chat" is low commitment and super clear about what the link will do. In most places mentioning the group chat we also add "we're friendly!", because that's not always the case for online communities.
Should "take a look at our group chat" point to the Community page or directly to Zulip?
Here's a quick demo of the new search experience I've been building:
I submitted two PRs:
Hope you like it!
Looks great!
@Aurélien Geron, did you change the sorting somehow, or is this issue still relevant?
https://github.com/roc-lang/roc/issues/11522
There's a ranking algorithm now, but it doesn't put type names first, so let me fix that.
Fixed. :+1: I also prioritized matches at the beginning rather than the middle of a result, so Hasher comes before Crypto.BLAKE3.Hasher. Here's an example:
![]()
Thanks.
Is there some preview deployment where it can be tried out?
Not yet, I'll set one up.
Here's another example, showing that function matches come before signature matches:
![]()
If you make a PR cloudflare will make a preview site
This is looking really great. I love all the little details you've put in to make it feel super nice.
Great, I'll make a PR now. It combines three PRs: the Docs generator update, the search update on the website, and the website header update.
https://github.com/roc-lang/www.roc-lang.org/pull/184
@Luke Boswell will Cloudflare automatically generate a preview or do you need to authorize it?
Trying to figure out why the bot triggered on my PR but not yours so far https://github.com/roc-lang/www.roc-lang.org/pull/180#issuecomment-6487202201
I marked your's ready for review to see if that helps
Ah it must be because your PR is from a fork
Here's the new Docs search preview
I think the double border around the category selector buttons is too dense. What about removing the rounded button borders and only adding a vertical separator from the top line to the ones below?
Something like this:
![]()
Good idea, I'll do that now
I forgot the background highlight on the active button.
Yeah, I was thinking the same thing just now. I'll try out some things.
Or maybe no vertical bars, just some small separator like a middle dot? ·
Or keep the lower border and simply add a thicker bottom border, like this?
https://daisyui.com/components/tab/#tabs-border
![]()
The titles are not very distinct visually. Maybe a bold font would help?
![]()
The bottom border disappears when scrolling. I did not notice it when I recommended the above button border changes.
I'm trying center dots, no lines + underline selected + darker snippets (so the titles stand out more).
It looks like this:
![]()
Seems better. The snippet button is a bit strange. Maybe no background?
The "All" category seems good at first, but when I actually try to use it, it's not really useful. Most of the time, there are too many API results, so I would not scroll for the guides, but use the button.
What about removing it, and adding counters to the API and the guides buttons instead?
And maybe a quick button at the end of API results: That's all. Maybe try searching the Guides & examples (15) instead?
Oh you've got a good eye, I didn't even notice the background! :glasses:
I'll remove the background. I much prefer this look, thanks for the suggestions!
Btw, would you prefer a bit more margin between the results and the buttons?
![]()
![]()
The search cancel button is not well visible. Maybe use the same purple? Or add some background?
Btw, would you prefer a bit more margin between the results and the buttons?
Yes, I would recommend that. Maybe if a fade or shadow effect could be added, that would help.
I would recommend symmetric padding at the top of the buttons too.
Hows' this?
![]()
I'm not sure about removing the All button. I've used the search for a while, and what I liked is that pretty often what I'm looking for is right there, without extra clicks. For the API results, they're at the top, so no problem. But when I search for lang ref content, such as "Modules", "Platforms", or "Types", there are barely any API results so the thing I'm looking for is right there. And in the cases it's not (e.g., "JSON"), I just need to click on "Guides & examples", which I would have to do anyway if we removed "All".
Seems good.
What is the thick bar under the snippets button?
Is it indicating that it's enabled/disabled?
Yes
It's off by default so the user will see the underline appear when clicking it
What about using a toggle for it?
https://daisyui.com/components/toggle/#toggle-switch
By the way, is the docs vanilla CSS or is some UI framework used?
Then I could link component examples from that (if any).
It's vanilla CSS and JS
I initially had a "Show snippet" button (which would be roughly as wide as a toggle + label), and it made the button bar too wide on mobile, they ended up on two lines
Maybe a "Snippets" plus a toggle?
It's confusing on mobile, because sometimes there's no visible effect when toggling it.
And there's no label either.
![]()
Maybe utilize the full screen width on mobile? So there's no blank padding at the sides?
Sounds good, I'll give that a try.
And maybe the border could be removed and use the full screen.
Try it on a real mobile, not just the devtools mobile simulator.
When the on-screen keyboard is open during search, it uses up half of the screen.
Trying all of this. I'm also adding snippets in the API section.
My recommendation for mobile:
This would hide all other parts of the page. For example, the top menu unnecessarily takes up space during search.
It looks much better. I've also merged the two API sections into one, there's no good reason to separate them.
Next I'll work on the snippet toggle
Here's what it looks like now on mobile. I also added the toggle:
![]()
Here's the latest search preview.
Looks like this on my phone, with the on-screen keyboard:
Screenshot_20261030_133726_Chrome.jpg
And without the snippets:
Screenshot_20261030_134011_Chrome.jpg
I like this version a lot more.
![]()
When focusing it on mobile, and it switches into full-screen mode, it's empty. I would recommend showing unfiltered results ("" query string), or some top picks.
Latest search preview with suggestions on mobile
It looks like this:
![]()
this is just my opinion ... but it feels strange to have a super wide screen on my monitor, and then these code snippets are scrolling horizontally with so much empty whitespace
![]()
I'm on a 1920x1080 monitor so nothing unusual
This is not related to my recent changes, I don't think. We could perhaps make it a bit wider indeed, but there comes a point where it looks like a wall of text and it's not as pleasant to read, imho.
Its not related to the search
I wonder if we could make a lint or something to warn if our code snippets were longer than 80 characters on a line or something
That might be a bit crude but we could always break them over multiple lines I guess.
Yes, it would be nice if the doc for every function and type started with a short sentence that could be used as a snippet. :+1: Python imposes that, we could reuse the same rules. ChatGPT says:
Keep the first sentence under 72 characters: While general code lines can extend to 79 characters, PEP 8 specifically restricts flowing text blocks like docstrings and comments to a maximum of 72 characters.
Write as an imperative command: The summary should prescribe the function's effect as an action ("Do this", "Return that"). For example, use "Return the absolute value" rather than "Returns the absolute value".
End with a period: The summary line should always end with a period.
Isolate with a blank line: If you are writing a multi-line docstring, that first summary line must be separated from the rest of the deeper explanation by exactly one blank line.
Is this how Python does it?
Yes, these are Python's rules
I wonder if we will want to tailor the "imperative command" a little for Roc's functional approach. I'm really fuzzy on what that would look like, just "Return the absolute value" doesn't quite feel right
By the way, on macOS responsively is great so you can see a wide variety of screen sizes and types at once.
Aurélien Geron said:
Should "take a look at our group chat" point to the Community page or directly to Zulip?
Directly to zulip, the community page has too much text for the casually curious.
Oops, it looks like I forgot this change, the site still says "join our community", sorry. I just submitted PR #186 to fix that.
Is it intentional that the /tutorial page does not mention the |> even once?
Some LLMs think it's been removed in the rewrite or usage is discouraged.
It was removed, and then it came back :sweat_smile:
So not intentional, just not updated
yeah the syntax for it changed to a different symbol in the initial rewrite, then later changed back
Was the method syntax also added in the rewrite? Or did it exist in the old Rust version too?
It was added in the rewrite
I'm now working on updating the langref. I submitted PR #12725 to fill gaps in the outline, give it more structure, clarify what exists todays vs what's planned, remove some obsolete limitations, soften the intro warning, and a few other things.
Here's the list of planned features mentioned in the langref. Now that we're approaching 0.1.0, it would be good to clarify which of these are planned for 0.1.0. @Richard Feldman?
..[])collection[key])continueAll of those will be after 0.1.0
Thanks, Richard. I think there are a couple of references to 0.1.0 in the langref, I'll be explicit about the fact that it will be after 0.1.0, to set expectations. Unless you want me to say "by 1.0.0"?
let's just say after 0.1.0, no need to promise things unnecessarily :smile:
Thanks Richard. PR #12758 updates the langref to make this clear.
The new search is live, try it out!
I like the "Try searching for..." suggestions :)
Last updated: Nov 04 2026 at 18:54 UTC