Stream: contributing

Topic: getting started guides


view this post on Zulip Jeffrey Mudge (May 30 2024 at 00:03):

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?

view this post on Zulip Jeffrey Mudge (May 30 2024 at 01:50):

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.

view this post on Zulip Luke Boswell (May 30 2024 at 03:34):

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.

view this post on Zulip Luke Boswell (May 30 2024 at 03:38):

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

view this post on Zulip Luke Boswell (May 30 2024 at 03:41):

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.

view this post on Zulip Jeffrey Mudge (May 30 2024 at 13:47):

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.

view this post on Zulip Jeffrey Mudge (May 31 2024 at 00:58):

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.

view this post on Zulip Luke Boswell (May 31 2024 at 01:02):

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 think combining them is a great idea


Last updated: Jul 05 2025 at 12:14 UTC