Luke Boswell (Mar 15 2023 at 07:51): Luke Boswell (Mar 15 2023 at 07:51):I would like to add a feature to static-site-gen to transclude static files into the markdown that is being processed. The primary purpose of this is to possibly create a static site to host the Roc examples. There are benefits to generating a static site for the examples; however the current implementation limits us to putting the code into the markdown file in a code example.
I would like to have code in separate files e.g. myExample.roc and myExample.rs and then use a pattern for the platform to insert the contents of this file at the desired location when processing the file. This would make it possible to use the code's native tooling e.g. for tests or editing etc, and it is also more easily viewed when viewed in the repository online.
The proposed idea is to take a code fence that looks like the following, and when the platform sees this pattern it replaces the code fence internals with the file contents, and then proceeds to syntax highlighting and produce html as before.
# The `'` characters are ticks
'''roc
<<<myExample.roc>>>
'''
This functionality may not fit naturally with a Static Site generator, so we could also fork the platform and add it separately.
Looking for feedback or concerns on this direction.
Anton (Mar 15 2023 at 08:45):We could probably change the <<< and >>>, to < and >. The case where your only code is <filename.ext> seems very rare to trigger accidentally. It's a really nice feature to have in the static site generator, mainly because it allows you to easily run CI on your code, so I'd be in favor of not putting that in a fork.
A nice addition could be to specify line numbers as well <filename.ext:4-12>, this would allow you to show only the relevant parts of the file but have a big header and a bunch of tests in the real file.
Luke Boswell (Mar 15 2023 at 10:14):Here's the PR 5144 for this feature.
From your feedback, I figured why even bother having the leading/trailing characters? So I ended up just going with the assumtion that the code is a relative path and trying to open a file, this seems to work well enough.
Maybe it could be an performance issue if you have many code blocks, and the platform is attempting to open an file for each one? I'm not sure if this is an issue, noting that this is just when processing the files.
Anton (Mar 15 2023 at 10:17):Here's the PR 5144 for this feature.
That was fast :) I'll check it out.
I figured why even bother having the leading/trailing characters?
Yeah, I though about it as well, I think not having them will be fine in practice
Maybe it could be an performance issue if you have many code blocks, and the platform is attempting to open an file for each one?
I think it'll work out
Agus Zubiaga (Mar 15 2023 at 10:51):What about using tags instead?
<insert-code lang=“roc” src=“filename.roc” />
I think they are a nice way to extend markdown, and you’d be able to make the generator fail if the file is not found.
Anton (Mar 15 2023 at 11:02):Would that work with github's markdown viewer?
Agus Zubiaga (Mar 15 2023 at 11:42):Ah, I didn't understand that was a goal. No, it will just skip it.
Anton (Mar 15 2023 at 12:06):Just skipping it does not seem ideal, it is nice that you can see that something is supposed to go there.
Georges Boris (Mar 16 2023 at 03:37):with that in mind, maybe using a link to the file + data fields would be interesting? so it would also be useful on github and we would just replace links with their an inlined version (possibly still keeping a link to the original file)
Luke Boswell (Mar 16 2023 at 05:22):I might not be understanding correctly, but my plan is to do the syntax highlighting in rust platform. I want to include the contents of the file and then process it, potentially do things like roc check etc. I'm not sure if we made it a html inline element we could do that. Maybe we could using js? But then we would also need to copy the static code files across to the www/public folder I think. I like the idea of using an html tag to extend markdown, I hadn't thought of that.
Anton (Mar 17 2023 at 09:23):So I think that Georges is proposing something like this: [filename.roc will be embedded here](path/filename.roc)
I think that could also be integrated easily in the current code, I think we could match on a link here and check if the link text is of the form filename.ext will be embedded here and then replace it with the code similarly to how we do it now.
Luke Boswell (Mar 17 2023 at 11:13):Aha, that makes more sense. :man_facepalming: I like that idea, it's pretty neat. Though I think the way we've implemented it also is pretty nice. I'm interested to hear peoples feedback on the examples repo PR. I think it is clear using the fenced code as it is a code block. The link is a good idea for when we want to do inline stuff. There might be a way we can use that to solve the problem of inline highlighting where there is no easy way to identify the language desired. Maybe we could do something like [`my inline code here`](elm) and that could be a way to specify non-default inline code highlighting.
Anton (Mar 17 2023 at 11:34):I wouldn't try to use the link syntax for inline code because [`my inline code here`](elm)would not link to something real, our CI link checker would also throw an error in this case.
Anton (Mar 17 2023 at 11:40):I think with the [filename.roc will be embedded here](path/filename.roc) we can have nicer error messages because we can be very confident that the user did not accidentally trigger our embedding syntax when they just wanted to show a record access in a code block for example. I'll explain in detail in my review of PR#5144
Last updated: Jul 26 2025 at 12:14 UTC