Initial prototype of interactive tutorials - #677
Conversation
Inspired by ScalaTutorials, this is a largely vibe-coded prototype of how we might do something similar on the TL website. This is very intentionally *not* surfaced to the rest of the site yet: since it is just a prototype, I'd like us to be able to iterate on it before we declare it good enough to open up to the public. A small constraint: due to a quirk of how Scastie works, if you are working in this locally, do *not* try to navigate to it using `localhost`. Go explicitly to http://127.0.0.1:8000/tutorials/ This prototype demonstrates the idea of having multiple "tracks" of tutorial -- I'm pretty sure that, if we go down this road, we'll want to do that. But the actual content here is entirely machine-written, and should be considered entirely throwaway: I just wanted enough content to be able to show off what I was thinking. This initial commit is purely vibe-coded, with the following prompt: > Under the folder ~/IdeaProjects/typelevel, you will find two repos: > * typelevel.github.com -- the website for Typelevel. This is what we will be editing. > * scalatutorials.github.io -- the website for ScalaTutorials. This is what we will be learning from. > ScalaTutorials has a great feature that I'd like to try to add to Typelevel: interactive tutorials. These pages have two major panes: > * The left-hand pane is tutorial text, describing a topic. > * The right-hand pane is a styled Scastie window. The user types Scala code into it, presses the Scastie "Run" button, and if there is output, it opens a pane below that showing the output. > Our goal is to prototype similar functionality for the Typelevel website. Specifically: > * These tutorials should show up under the /tutorials path on the Typelevel website. > * The layout should be broadly similar to that on ScalaTutorials. > * The behavior should be the same as ScalaTutorials, with a live embedded Scastie on the right-hand side. > * The frame styling should match the Laika styling of the Typelevel website. > * The new tutorials section should *not* be visibly linked from the rest of the site -- this is just a prototype, and we don't want to leak it to the public until it's ready to be useful. Initially, folks will have to manually navigate to /tutorials to use it. > * Please change the *existing* code and files of the Typelevel website as little as possible. It's likely to take a while for this prototype to be ready to merge, and I want to minimize merge conflicts. (But don't go to excessive lengths to avoid minimizing files: in particular, don't copy large blocks if sharing would work better.) > * Adding *new* files is fine, preferably mainly in a /tutorials subdirectory. > * The initial page of the new tutorials should just be a welcome index, listing and linking tutorial "tracks". > * Each "track" should have its own subdirectory, with the actual data files. > * To begin with, please create two prototype "tracks": > * * One should be named "cats". Initially, just create two simple pages, one showing an example of Functor, the other an example of Monoid. > * * The other should be named "cats-effect". This should have two simple pages, one showing the high-level concept of IO, the second describing unsafeRun. > * Do *not* put significant effort into these prototype pages: they should be short, simple proof-of-concepts, to show that the functionality basically works. The actual content will be thrown away and replaced by human-written pages, so keep it simple. > * Similar to the way ScalaTutorials works, the bottom of the left-hand pane should have a "previous" button linking to the previous session, an "up" button going up to the list of tracks, and a "next" button linking to the next lesson. > * Similar to ScalaTutorials, the right-hand pane should have a button that opens the current code (as edited by the user, if applicable) in Scastie proper. > Feel free to run the Typelevel repo locally, if that seems useful. Note that this parent directory has a mise.toml file intended to facilitate that: I've set things up to be able to say `mr website` to run the site from this repo. > Do not bother editing the ScalaTutorials repo -- we won't be changing that. Don't try to run that unless you think it is necessary: if so, stop and let's talk about how to do so, since that will take some configuration. > Do *not* commit anything yourself. When I think we're at an appropriate checkpoint, I will branch the Typelevel repo and begin to commit.
|
Cool. For the TL site, maybe getting them inline on the page would be even better for some brief runnable samples. The whole tutorial format might be better for the actual project sites. |
|
How did AI know so much about Laika all of a sudden? I tried to get it to help me before and it kept giving out wrong information. |
In my experience, if you point them at a repository full of sample code, it manages to follow the patterns reasonably well. |
|
Yeah -- Opus, especially, is increasingly good at just following my lead. That's the only reason I'm using it at work: it's doing nicely at following my particular TL-centric style (with my own idiosyncracies) and building code that looks broadly similar. |
Possibly, but one problem at a time IMO. I'm not sure how well the embedded-Scastie affordances will work from a UX POV in such a small space (has anyone pioneered that yet?), and I'd prefer we not make the best the enemy of the good.
Agreed, but I'm not sure the difference matters all that much in practical terms, now that the projects are increasingly served from the typelevel.org domain. That is, if Cats is located at typelevel.org/cats, and its tutorial is at typelevel.org/tutorials/cats, that's not a surprise from the user POV. And I deliberately broke it down to one-directory-per-track, specifically so that it's easy for us to keep it all straight in the data. It's arguably a little easier organizationally for these to belong to the individual project repos. But techically, I suspect it would be more of a pain in the ass, especially since the projects aren't necessarily unified in how they're serving their documentation: replicating this code in each project's site feels like a lose. My suspicion is that it would make sense for this to be served individually from project sites if and only if we built this functionality into Laika. That's a somewhat plausible idea (arguably even a great one once Scala can compile in-browser), but again, I'd probably argue that it's best as a later step unless someone is really motivated to spearhead it. All that said, if we do go this route, I'd recommend we throw the doors open and say that all Organization projects (and maybe Affiliate projects, although that's not as obvious) are allowed and encouraged to contribute tracks for their projects, and all we need to do is accept PRs. It's the sort of thing that I'd say the TSC should facilitate, but not necessarily do all the content. |
|
Ahh, alright, this plan makes sense. |
While we don't share any code, the design was directly inspired by them, and they're an appropriate first step for folks who are new to the language.
Let's call out that this is just vibe-coded, and there is no investment in these example pages.
| ] | ||
| } | ||
|
|
||
| These tutorials were inspired by [scalatutorials](https://scalatutorials.com), which teaches |
There was a problem hiding this comment.
If you really want to recommend them, there is also that new learning resources page, which only has one link under tutorials and courses right now!
There was a problem hiding this comment.
Oh, good point -- would be totally appropriate to have there IMO. (Although probably in a separate PR, since it's not really related to this prototype.)
Matches what I originally told it to do, but that wound up strictly inaccurate, and the way it wound up is probably better.
To unblock the build.
3 participants
Inspired by ScalaTutorials, this is a largely vibe-coded prototype of how we might do something similar on the TL website.
This is very intentionally not surfaced to the rest of the site yet: since it is just a prototype, I'd like us to be able to iterate on it before we declare it good enough to open up to the public.
A small constraint: due to a quirk of how Scastie works, if you are working in this locally, do not try to navigate to it using
localhost. Go explicitly to http://127.0.0.1:8000/tutorials/This prototype demonstrates the idea of having multiple "tracks" of tutorial -- I'm pretty sure that, if we go down this road, we'll want to do that. But the actual content here is entirely machine-written, and should be considered entirely throwaway: I just wanted enough content to be able to show off what I was thinking.
None of this should be considered a statement that we are necessarily going to do this. But I figured it was worth throwing something together to show that it's possible, and we can then discuss whether we want it, and begin to iterate on the details if so.
As it says, this first draft is almost 100% vibe-coded. See the first commit for the full prompt.