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

Comments

Projects
None yet
4 participants
@danroth27
Member

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Mar 4, 2016

Contributor

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)
Contributor

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

This comment has been minimized.

Show comment
Hide comment
@danroth27

danroth27 Mar 4, 2016

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Mar 4, 2016

Contributor

You can also cross reference in DocFX, like this:

<xref:topic_id#anchor_name>
Contributor

chenkennt commented Mar 4, 2016

You can also cross reference in DocFX, like this:

<xref:topic_id#anchor_name>
@danroth27

This comment has been minimized.

Show comment
Hide comment
@danroth27

danroth27 Mar 4, 2016

Member

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

Member

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Mar 10, 2016

Contributor

Currently doesn't work, need some fix.

Contributor

chenkennt commented Mar 10, 2016

Currently doesn't work, need some fix.

@danroth27

This comment has been minimized.

Show comment
Hide comment
@danroth27
Member

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

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Apr 1, 2016

Collaborator

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

Collaborator

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