Referring to sub-section in a markdown file in another folder

Question

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.

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 '22 at 21:38

pygeek · Accepted Answer · 2022-07-31T19:28:06.880

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

repl.it parent.md

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>

repl.it jupyterbook build output

Child

Markdown input:

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

repl.it child.md

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>

repl.it jupyterbook build output

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

@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 '22 at 19:13

Salvatore · Answer 2 · 2022-08-01T15:07:05.260

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.

thanks @Viglione, actually my sub-section is named 'sub section'. I tried replacing the space with a dash but your solution did not work. I am using a jupyter book: https://jupyterbook.org/en/stable/start/your-first-book.html — user308827, Jul 31 '22 at 03:26

score 1 · Answer 3 · answered Jul 30 '22 at 00:05

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

add an empty link to the target position in child.md file

<a id="sub"></a>
## sub-section

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