Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Cross referencing vs sphinx #314

AntoineD started this conversation in General
Oct 23, 2025 · 1 comments · 5 replies
Discussion options

Hello,

the project I work for is in the process of converting its documentation from sphinx to mkdocs.
We make use of the very convenient reference target specification and resolution of sphinx.

We have tried this plugin but it is not on par with sphinx's related powerful simplicity and features.

We are considering sponsoring mkdocstring to get access to relative and scoped cross-referencing features, but we wonder how it compares to sphinx features.

Would it be possible to have clarifications on these?

You must be logged in to vote

Replies: 1 comment 5 replies

Comment options

The ~ prefix is not supported, but scoped cross-references make it superfluous in most cases. Relative cross-refs (with a . prefix seem to resolve the same way as in Sphinx. One thing I noticed could be improved is that [..render][] will display a link with ..render as title instead of render (dots not stripped). One can always re-specify the title anyway: [render][..render].

If you show me how you use Sphinx cross-refs I can show you equivalent in mkdocstrings/autorefs 🙂

You must be logged in to vote
5 replies
Comment options

Basically with sphinx, wherever an entity is located, using .entity will be resolved when there is no ambiguity. This reference can be used in docstrings and anywhere in the docs.
Ambiguities can be resolved by adding context .Context.entity, like .Class.method for instance. We never need to figure out where the target is relatively to where the reference is created.

Comment options

This is not possible with mkdocstrings. But you'll be able to see for yourself in the next days: I'm about to release every private feature to the public 🙂

Comment options

That's too bad 😞 , but how impossible is it?

Comment options

Oh it's definitely doable. You could open a feature request but I can't guarantee I'll be working on it since my priorities have shifted towards Zensical rather than MkDocs 🙂

Comment options

OK so there is hope, I'll try to do it myself.

Congrats for this new promising project!
I'll keep an eye on it...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
2 participants

AltStyle によって変換されたページ (->オリジナル) /