Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
Tracked by #1270
nthiery opened this issue Oct 13, 2023 · 7 comments
Open
Tracked by #1270
Assignees
Labels
enhancement New feature or request

Comments

@nthiery
Copy link
Contributor

nthiery commented Oct 13, 2023

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 nthiery added the enhancement New feature or request label Oct 13, 2023
@nthiery
Copy link
Contributor Author

nthiery commented Dec 16, 2023

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
Copy link
Collaborator

choldgraf commented May 22, 2024

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
Copy link
Contributor

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
Copy link
Collaborator

rowanc1 commented Sep 24, 2024

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
Copy link
Contributor

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
Copy link
Collaborator

choldgraf commented Sep 24, 2024

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
Copy link
Contributor

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

5 participants