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.

Sign up for GitHub

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

Jump to bottom

relative url start with "../" in nav no longer works #2752

Closed
akinmr opened this issue Jan 25, 2022 · 8 comments · Fixed by #3010
Closed

relative url start with "../" in nav no longer works #2752

akinmr opened this issue Jan 25, 2022 · 8 comments · Fixed by #3010
Milestone
1.5.0

Comments

@akinmr
Copy link

akinmr commented Jan 25, 2022 •
edited by oprypin
Loading

When I tried to make a link to an external resource in nav section of mkdos.yml, using the following example, the actual output HTML omits "../" in the relative URL and I couldn't point to external resources out of mkdocs with relative URL.
https://www.mkdocs.org/user-guide/configuration/#nav

The minimal mkdocs.yml to reproduce the problem is as follows:

site_name: Example
site_url: https://example.com/foo/

nav:
    - Parent: '../'
    - Sibling: '../some/dir/'
    - Home: './'
    - Index: 'index.md'

When I compile it with empty docs/index.md file, the navigation section in site/index.html became as follows:

<!-- Main navigation -->
<ul class="nav navbar-nav">
    <li class="navitem">
        <a href="./" class="nav-link">Parent</a>
    </li>
    <li class="navitem">
        <a href="some/dir/" class="nav-link">Sibling</a>
    </li>
    <li class="navitem">
        <a href="./" class="nav-link">Home</a>
    </li>
    <li class="navitem active">
        <a href="." class="nav-link">Index</a>
    </li>
</ul>

What I expect was that the link of "Parent" should point to "../"(= https://example.com/) and the link of Sibling should point to "../some/dir"(=https://example.com/some/dir/), which are outside of the generated doc.

I remember this way (Sibling case) worked in past, but when I recompiled the document with the latest mkdocs, it started emitting unexpected URL.
@bloer
Copy link

bloer commented Mar 24, 2022

I just encountered the same issue. Surprised such a killer bug has not received any response

@oprypin
Copy link
Contributor

oprypin commented Mar 25, 2022

I confirm that #2296 (released in 1.2) changed this behavior.

The thing is, this usage was never supported and always showed warnings anyway:

WARNING -  A relative path to '../' is included in the 'nav' configuration, which is not found in the documentation files

In MkDocs nav, relative links are always assumed to be links to Markdown documents within the site.

You can use this appoach instead:

site_url: https://example.com/known/absolute/path/

nav:
    - Sibling: '/known/absolute/some/dir/'

I am not sure if this will be revisited.

@akinmr
Copy link
Author

akinmr commented Mar 25, 2022

The reason why I'm using this relative URL approach is that I'm deploying the same document to different path of the server, like /docs/docA/ and /docs_testing/docA/, in order to check the appearance before deploying it to the public, and want to make links to /docs/docB/ and /docs_testing/docB/ with single '../docB/'.
I made this config because I found such '../' way in the example in the official user guide, and it worked before, even though it emits some warnings.
I would be happy if this restriction can be switched off with some configuration in the mkdocs.yml.
At least, the documentation should be updated if '../' is no longer supported.

@oprypin
Copy link
Contributor

oprypin commented Mar 25, 2022

Oh wow, you're right! 😞

mkdocs/docs/user-guide/configuration.md

Lines 195 to 206 in f725e22

However, sometimes the MkDocs site is hosted in a subdirectory of a project's
site and you may want to link to other parts of the same site without including
the full domain. In that case, you may use an appropriate relative URL.
```yaml
site_url: https://example.com/foo/
nav:
- Home: '../'
- 'User Guide': 'user-guide.md'
- 'Bug Tracker': '/bugs/'
```

@akinmr
Copy link
Author

akinmr commented Jun 23, 2022

Is there any fix or workaround planned for this?

@aidanheerdegen
Copy link

I also would like this behaviour restored. My use case is wanting to deploy effectively two linked sites under the same base URL.

I want to do this so that each sub-site can have it's own navigation tabs, and to make a clear distinction between the two sub-sites by styling them with different colours and titles.

I can achieve the sub-sites easily, by having site1_mkdocs.yml and site2_mkdocs.yml, each of which build to a subdirectory (main/site1 and main/site2). The problem comes that I want each sub-site to link back to the other with a relative link, ../site1 and ../site2, and then I get the error and the URL stripped of the relative path.

@aidanheerdegen aidanheerdegen mentioned this issue Sep 12, 2022
Closed
@psifertex
Copy link

Also being bit by the same bug. In my case I want to link in my nav to some sphinx docs that are built and available via a relative URL locally. Absolute paths are not an option and neither are URLs.

@oprypin oprypin added this to the 1.5.0 milestone Oct 17, 2022
@oprypin oprypin mentioned this issue Oct 17, 2022
Merged
@oprypin
Copy link
Contributor

oprypin commented Oct 17, 2022

OK. I intend to fix this - I have linked a pull request, it just doesn't have tests yet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
1.5.0
Development

Successfully merging a pull request may close this issue.

Allow paths traversing above the root - in nav and extra_ mkdocs/mkdocs
5 participants
@psifertex @oprypin @bloer @aidanheerdegen @akinmr