I think I can give https://github.com/roc-lang/roc/issues/6764 a try.
I'm seeing inconsistent URLs and would like to clarify - should we be including the .html extensions in the URLs or not? It seems that they are there in some places, but not others.
Also, the getting_started/README.md has a lot of overlap with the /install.md. Would it be ok to change the getting_started/ to install/ and install.md to install/index.md and merge it with what is currently getting_started/README.md? Or should those stay separate?
I decided to go ahead and make a pass at this in 6782. If the way I did it isn't what was intended, I'm happy to fix it.
I think the Netlify server will default to index.html for a folder. So where we have an index.md the link doesn't need to have the .html
. If I recall correctly the preference is not to have the .html
so the link looks cleaner.
Also, the getting_started/README.md has a lot of overlap with the /install.md. Would it be ok to change the getting_started/ to install/ and install.md to install/index.md and merge it with what is currently getting_started/README.md? Or should those stay separate?
I interpret Anton's issue statement as moving all of these from e.g. getting_started/linux_x86_64.md
to something like www/content/getting_started/linux_x85_64/index.md
I decided to go ahead and make a pass at this in 6782. If the way I did it isn't what was intended, I'm happy to fix it.
I had a quick look, I think the only thing we need to clarify is if we want to have links without the .html
(by moving them into a subfolder and renaming to index.md
.
Otherwise looks good I think.
Thanks for the feedback.
I haven't used Netlify personally, but from some googling, it looks like they do have a pretty URLs feature that can strip one layer of .html extensions off of URLs. I'm guessing that's not turned on for this site though.
The local development server is loading index.html files when accessing a directory path, but it's not loading other .html files without the extension. I just tested the production website and Netlify is loading https://www.roc-lang.org/plans or https://www.roc-lang.org/plans.html equally well.
Given that, unless we can turn on the Pretty URLs post processing Netlify configuration, I'll remove the .html extensions from the URLs and just deal with the fact that the local dev server won't resolve them. Unless you really want the folder/index.md
structure for each sub-page, I think that will be cleaner.
I do still think that the files that are in install/index.md
and install/getting_started.md
in my PR could be combined, but that can happen later.
I see that Anton has asked about getting /path instead of /path.html support for the dev server.
I've removed the .html extensions from my PR for the relevant URLs. If you try it locally, the links won't load, but if you add the .html to the URL bar path, then they'll load. Netlify should load them without issues.
I do still think that the files that are in
install/index.md
andinstall/getting_started.md
in my PR could be combined, but that can happen later.
I think combining them is a great idea
Last updated: Jul 05 2025 at 12:14 UTC