🎯 Render static HTML pages to expected server path

[stefanv]

Servers typically translate foo/bar to foo/bar/index.html. If we put the pages there, then the server finds them, and we don't need to jump through any further hoops to get them rendered.

[choldgraf]

Lol if it's as easy as this I will be pleasantly surprised. Also, is this the kind of thing that would break anything? If so we might want a feature flag for it (eg trailingslash, similar to docusaurus) and in a few releases switch the defaults

[stefanv]

I was worried it would break paths to JS bundles, but because we currently don't support relative paths, it doesn't.

[choldgraf]

Here's my suggested path forward:

• Put this behind a feature flag and add docs like 'if you want to run on RTD, turn this flag on'
• If it's non controversial then the flag can be "on" by default.
• if there is worry this would break something, make of "off" by default and then check back in after a few months to see if opinions have changed.

To me, this feels like it better aligns the HTML links behavior with other state of the art documentation generators, and would make it more likely to work across a number of hosting providers..so I'm for it!

[bsipocz]

Opting in sounds great to me, this is currently the blocker for a few repos of mine that are otherwise ready to be switched to JB2.

[agoose77]

@stefanv this looks fine! We should check that any steps that rewrite the HTML still find the file.

If that's the case, I'd also feature flag and merge this given that it unblocks quite a lot of useful testing.

We don't have a standard FF system, so I'd suggest a MYST_ prefixed environment variable. @rowanc1 can take a look (I'm deliberately afk this week), but I think it's also important that these kind of things are safe to just ship.

Let's include this (with FF) in a release this weekend?

[choldgraf]

So I think this could be something like this?

Suggested change

	path: path.join(proj.slug ?? '', `${pageSlug}/index.html`),
	// I'm not sure how to get options but I imagined it being under `site.options.trailingSlash` similar to docusaurus.
	const trailingSlash = site.options?.trailingSlash === true;
	const filePath = trailingSlash
	? path.join(proj.slug ?? '', pageSlug, 'index.html')
	: path.join(proj.slug ?? '', `${pageSlug}.html`);

[choldgraf]

@agoose77 why not have this feature flag at the level of site.options? That's what I was suggesting here:

#2178 (review)

It feels similar to the folders: true behavior as well.

[agoose77]

We could do! We don't have a mechanism yet. I think we should distinguish between options and feature flags, as the latter is 'unstable'.

To add - this probably should be a site option eventually, even if it is default on - it's more that we can ship right now imo if we don't expose any configuration changes.

[choldgraf]

Ah got it -if our goal is just unblock experimentation here then I'm happy with whatever is simplest and doesn't change anything for existing users. If like a MYST_ prefix thing is the easiest thing, I'd say let's go with that and we treat this as an experimental feature flag.

[changeset-bot]

🦋 Changeset detected

Latest commit: 585c91d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
myst-cli	Minor
mystmd	Minor
myst-migrate	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[choldgraf]

I pushed a little bit of docs to this to explain the behavior. I think this is pretty much ready to try-out no? If this unblocks users being able to use ReadTheDocs, that would be very helpful...

[rowanc1]

Nice - tested locally as well, all looks good. There shouldn't be any impact on github pages, and then it opens up against RTD, which is awesome.