5

Related to Markdown: Reference to section from another file

I have two markdown files:

├── parent.md
└── content/
    └── child.md

In parent.md:

# Main section
## sub-section

I'd like to make a reference to ##sub-section from child.md. How do I do that? Note that child.md is in a sub-folder.

Note that I am using Jupyter book to process the markdown.

4
  • 2
    What generator do you use? Jul 28, 2022 at 19:42
  • Let me know if you had a chance to implement my answer. Also, there may be a more idiosyncratic way to do this for the processor you are using, so replying to @CyberTailor would be very helpful.
    – pygeek
    Jul 29, 2022 at 21:38
  • 1
    @CyberTailor I am using jupyter book
    – user308827
    Jul 31, 2022 at 3:24
  • @user308827 I have updated with your particular example.
    – Salvatore
    Aug 1, 2022 at 5:50

3 Answers 3

4
+500

Preface

Generally, markdown processors will apply an ID to document headers so that one can create a hyperlink.

Simply doing the following should work for most markdown processors:

[parent sub-section](parent.md#sub-section)

The downside to this approach is that when the header text changes, the ID changes, and therefore breaks the anchor link. Depending on the markdown processor you choose, there may be an idiosyncratic way to hardcode the anchor explicitly into the heading.

Jupyter-book

Since the processor you are using is Jupyter book, you can use section labels to cross-reference sections throughout your project.

Example:

Parent

Markdown input:

(parent:sub-section)=
# sub-section

Jupyterbook build output:

<section id="sub-section">
<span id="parent-sub-section"></span><h2>Sub-section<a class="headerlink" href="#sub-section" title="Permalink to this headline">#</a></h2>
</section>

Child

Markdown input:

[parent sub-section](parent:sub-section)
{ref}`parent:sub-section`

Jupyterbook build output:

<p><a class="reference internal" href="../parent.html#parent-sub-section"><span class="std std-ref">parent sub-section</span></a></p>
<p><a class="reference internal" href="../parent.html#parent-sub-section"><span class="std std-ref">Sub-section</span></a></p>

Note: Depending on the size of your project, it may be worthwhile planning out how you would like to namespace your labels in advance.

References

2
  • thanks @pygeek, can you apply it to my specific example?
    – user308827
    Jul 31, 2022 at 18:02
  • @user308827 I've updated my answer to apply to your specific example with example output. I also have provided the repl.it project that I created to generate the output.
    – pygeek
    Jul 31, 2022 at 19:13
1

providing another thought, since markdown support some html syntax, you can

  1. add an empty link to the target position in child.md file
<a id="sub"></a>
## sub-section
  1. add a href link in parent.md file

I tried on obsidian, if I click the link, the child file will show, but it does not jump to the sub section

<a href="obsidian://open?vault=content&file=content%2Fchild.md#sub">link</a> 

probably change the href to ".content/child.md#sub" in another editor

1

In child.md you can do this:

[link text](../parent.md#sub-section)

Note the use of the prefacing relative path ../ to reference the parent one level higher. Also note that depending on your generator, spaces in your #sub-section name may need to be replaced with dashes when referencing.

You can also use an absolute path. If / is your highest level, this should also work:

[link text](/parent.md#sub-section)  

In Jupyter Book, you can use custom labels:

Place a label right before the section you want to reference:

In parent.md:

# Main section

(sub-section-label)=
## sub-section

Then in child.md, refer to it like so:

[Link text](sub-section-label)

The text between the parentheses just has to match.

1

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.