Custom Path/URL For Pages

[4lch4]

Hey folks!

I posted my question on Twitter initially but @squidfunk recommended I post here instead so here it goes.

I've put together a sample repository that shows exactly what I'm after: https://github.com/4lch4/MkDocs-Sample

Basically, if you use the above sample, how do I make it so the _index.md file located in the /docs/notes directory is accessible at localhost:8000/notes/index instead of the default localhost:8000/notes/_index.

I'd be more than happy to provide more information if needed, just let me know ^_^

[squidfunk]

The most important thing: why would you want to do that? For what I know, no, it's not possible, but if we know what you're trying to achieve, there's probably a different way.

[4lch4]

Mostly because it's a convention I follow where index files start with an underscore to ensure it's at the top of the list, but having it in the URL can be kind of annoying.

[squidfunk]

While there is no off-the-shelf solution I know off, you could write a custom hook (new in MkDocs 1.4) that changes the destination path and URL of the resulting page. We're doing something similar in our blog plugin. Maybe something like (untested):

def on_page_markdown(markdown, *, page, config, files):
    if page.file.name == "_index":
        page.file.name = "index"
        page.file.url = page.file.url.replace("_index", "index")
        page.file.dest_uri = page.file.dest_uri.replace("_index", "index")
        page.file.abs_dest_path = page.file.abs_dest_path.replace("_index", "index")

[4lch4]

Ooo... I'll tinker with this today/this weekend and report back. Thanks a lot, Squidfunk!

[4lch4]

Alrighty, I tried this out but got an error that I've pasted below.

jisodl0 at MACX-382FQ05P in ~/Development/Playground/MkDocs-Sample (main●●) 
$ mkdocs serve
zsh: /Users/jisodl0/Library/Python/3.8/bin/mkdocs: bad interpreter: /Library/Developer/CommandLineTools/usr/bin/python3: no such file or directory
INFO     -  Building documentation...
INFO     -  Cleaning site directory
ERROR    -  Error reading page 'index.md': on_page_markdown() missing 1 required positional argument: 'markdown'
Traceback (most recent call last):
  File "/opt/homebrew/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/homebrew/lib/python3.9/site-packages/click-8.0.3-py3.9.egg/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/click-8.0.3-py3.9.egg/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/opt/homebrew/lib/python3.9/site-packages/click-8.0.3-py3.9.egg/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/homebrew/lib/python3.9/site-packages/click-8.0.3-py3.9.egg/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/homebrew/lib/python3.9/site-packages/click-8.0.3-py3.9.egg/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 83, in serve
    builder(config)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/build.py", line 308, in build
    _populate_page(file.page, config, files, dirty)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/build.py", line 177, in _populate_page
    page.markdown = config.plugins.run_event(
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
TypeError: on_page_markdown() missing 1 required positional argument: 'markdown'

I pushed the changes I made to the sample repo above in case it helps.

Also, am I putting the hooks property in the right location? I added it as a top-level property but the schema is saying this is an invalid use and the hooks property doesn't belong there but I can't find any other location it should go.

EDIT: Here's a screenshot of the error regarding the hooks property:

[squidfunk]

Two things: I had the time to actually run the example and corrected it, it should now work as expected. The other thing is that hooks was not defined in our schema. This is fixed in 2d4fe29.