Support folder hierarchies and nested files in URLs without flattening them

[nthiery]

trafficstars

When building a web site, nested file names are flattened and replaced with slugs:

https://mystmd.org/guide/table-of-contents#nesting-of-files-in-urls

While I can see the value for the end-user (simple urls), there are use cases where this is detrimental, as the nested file name actually carries semantic.

For example, in my course, the name of a document, says /Solutions/Semaine3/foo.html tells that this is a solution for notebook foo of week 3. While Devoirs/Semaine3/foo.html is the original assignment. This also helps the user match the pages on the web with the notebooks that they have dowloaded separately.

Proposal

Provide a configuration option flatten_filename=true/false, with true as default value, to enable or disable flattening of file names.

Provide a configuration option 'transform_filename=true/false, with true` as default value, to enable or disable file name transformation.

When both options are set to false, one recovers JupyterBook's behavior.

[nthiery]

I believe this is my last blocker for migrating my course notes to myst :-)

Next in line: a course starting in January:

https://nicolas.thiery.name/Enseignement/IntroScienceDonnees/

Thanks in advance!

[choldgraf]

Could I signal-boost this one? Is it a particularly complicated one to implement?

I ask because I think fixing this would be quite valuable: I think it is one of the only remaining "hard blockers" for any pre-existing users of Jupyter Book or Sphinx, given that currently, switching to MyST will break everybody's URLs.

[agoose77]

Talking to @choldgraf, another point to consider is the ability to preserve existing links. If we implement a jb1 slug scheme, then we could easily ensure that no links break.

However this is not necessarily a requirement.

[rowanc1]

That is links in the table of contents?

I have talked to @fwkoch and we are going to do some planning on this this week, and ideally get it over the line next week.

[agoose77]

I mean that should a user have some uri to foo/bar.md, we should maybe have a mode for preserving that (which goes beyond supporting folders to ensuring that the entire url for a page is identical).

Maybe it should be a configurable setting.

[choldgraf]

As a few driving examples:

• Jupyter Book's default HTML builder uses .html files, here's what they look like: https://jupyterbook.org/en/stable/publish/gh-pages.html
• Jupyter Book also allows for dirhtml builders, which look like this: https://compass.2i2c.org/people/expectations/

The concerns @agoose77 is voicing are that:

• Folks using the html builder will have any direct links to their docs break, because foo.html will become foo/index.html
• Folks using the dirhtml builder might have direct links to their docs break, if the sluggification conventions change (not sure whether this is true or not, but things like My page.md getting renamed to my_page/ vs. my-page/

And the two potential solutions we discussed being:

1. Add the ability to generate JB-style slugs (either html or dirhtml)
2. Generate re-directs automatically (like foo.html to foo/index.html)

But there might be other solutions to explore too!

[agoose77]

We also might want to do a pass in adding explicit '.html' to our static file urls - right now we leave that to the file server (so python's http server doesn't work)