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

Add support for specifying cross references for a specific section or location in a topic #190

Closed
danroth27 opened this issue Mar 4, 2016 · 7 comments
Assignees
Milestone

Comments

@danroth27
Copy link
Member

@danroth27 danroth27 commented Mar 4, 2016

With the DocFX cross reference support it looks like you can easily define links to different docs in your project, which is great!

We also need to be ability to define cross references to specific places in a doc, like a specific section or a specific label. In Sphinx we use the :ref:label-name`` syntax to define these references:

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

We need something similar in DocFX. It would be great if there was even a shorthand for referencing a specific section heading without having to define an explicit label, which is something Sphinx does not have.

@chenkennt
Copy link
Contributor

@chenkennt chenkennt commented Mar 4, 2016

It's already supported. For a heading, you can reference it using its name:

# This is a heading

[link](#this-is-a-heading)

If you need anchor in other places, use HTML:

<a name="this-is-an-anchor"></a>

[link](#this-is-an-anchor)
@danroth27
Copy link
Member Author

@danroth27 danroth27 commented Mar 4, 2016

Right, but I was specifically referring to cross referencing a location in a separate doc. The :ref: syntax can point to any label in any doc in the set of docs being built.

@chenkennt
Copy link
Contributor

@chenkennt chenkennt commented Mar 4, 2016

You can also cross reference in DocFX, like this:

<xref:topic_id#anchor_name>
@danroth27
Copy link
Member Author

@danroth27 danroth27 commented Mar 4, 2016

Ah, that sounds like just what we need. I'll try it out, but it sounds like you guys can close this issue.

@chenkennt chenkennt closed this Mar 7, 2016
@chenkennt chenkennt reopened this Mar 10, 2016
@chenkennt
Copy link
Contributor

@chenkennt chenkennt commented Mar 10, 2016

Currently doesn't work, need some fix.

@danroth27
Copy link
Member Author

@danroth27 danroth27 commented Mar 10, 2016

@chenkennt chenkennt modified the milestone: v1.7 Mar 14, 2016
@chenkennt chenkennt added this to the v1.7 milestone Mar 17, 2016
superyyrrzz added a commit that referenced this issue Apr 1, 2016
@superyyrrzz
Copy link
Contributor

@superyyrrzz superyyrrzz commented Apr 1, 2016

Hi @danroth27 , <xref:topic_id#anchor_name> is now supported in DocFX prerelease version. You can try it.

@johnneycao johnneycao closed this Apr 5, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.