search

executablebooks / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
172 stars 50 forks source link

Support folder hierarchies and nested files in URLs without flattening them #670

Open nthiery opened 8 months ago

nthiery commented 8 months ago

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, withtrue` as default value, to enable or disable file name transformation.

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

nthiery commented 6 months ago

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 commented 1 month ago

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.