Open nthiery opened 11 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!
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.
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.
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.
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.
As a few driving examples:
.html
files, here's what they look like: https://jupyterbook.org/en/stable/publish/gh-pages.html
dirhtml
builders, which look like this: https://compass.2i2c.org/people/expectations/
The concerns @agoose77 is voicing are that:
html
builder will have any direct links to their docs break, because foo.html
will become foo/index.html
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:
html
or dirhtml
)foo.html
to foo/index.html
)But there might be other solutions to explore too!
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)
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. WhileDevoirs/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
, withtrue
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.