CODEWITHSUNDEEP
emacsorg-mode
Sam Ritchie
Sam Ritchie

Reputation: 11038

How can I reference a section by number in org-mode export?

I'm working in org-mode and trying to generate a link to reference a section by its number, not its title.

* Section One
:PROPERTIES:
:CUSTOM_ID: sec:one
:END:

* Section Two
#+label: sec:two

I can reference Section One with  [[#sec:one]] and [[#sec:one][Section One]],
but I can't get the actual section number (1) to resolve.

I want to see

As you can see in Section 1

By writing something like

As you can see in Section [[sec:one]],

Any ideas?

Upvotes: 20

Views: 13099

Answers (4)

hell_ical_vortex
hell_ical_vortex

Reputation: 359

TL;DR:
Use package org-ref.
Use internal links to label sections like <<sec:section-name>>
Use name for images, tables and source-codes, like #+name: fig:my-fig
Use command M-x org-ref-insert-ref-link to insert an internal link

Details

If you use Org-Ref (usage link here) which I highly recommend for technical writing, and also for good referencing practices, there's a user-friendly interface to manage internal references (internal links).

Use the internal links format <<link-name>>, and #+name: another-nameformat to create labels, and use key-sequenceM-x org-ref-insert-ref-linkto insert a link using acompleting-read` interface, which depending upon your setting may be augmented by Icicles, Ido, Helm, Company and so forth.

For example, in the following case:

* Section with labels
<<sec:sec-w-labels>>

[...] My story here [...]

#+name: fig:my-screenshot
file:my-screenshot.png

* Section with links
I can refer to the section with labels (see \S <I>)
containing an explanatory figure here (see Fig. <I>)

When my cursor is at either of the positions marked <I>, using a command M-x org-ref-insert-ref-link, which I have bound to C-c C-x ), the emacs shows me a list of completion candidates of all the internal links, which in this case are namely, sec:sec-w-labels and fig:my-screenshot.

Upon completion, the section should look like this, having ref: links:

* Section with links
I can refer to the section with labels (see \S
ref:sec:sec-w-labels) containing an explanatory figure
here (see Fig. ref:fig:my-screenshot)

To install, insert the following into your Emacs init-file and restart. Or to just try, insert the following into your *Scratch* buffer and do C-M-x.

;; Org Ref
(use-package org-ref
  :ensure t
  :after ob-http
  :hook (org-mode . ref-link-keymap)
  :config

  (defun ref-link-keymap ()
      (define-key org-mode-map (kbd "C-c C-x )")
        #'org-ref-insert-ref-link)))

Limitation

The ref: links export as just another link with same text and href values using all exporters. So in case of HTML export the link is presented something like:

<a href="sec:bfm">sec:bfm</a>

In case of Latex, the compiler translates this internal link to section numbers.

Upvotes: 1

Cl&#233;ment
Cl&#233;ment

Reputation: 12937

You can refer to sections by name:

* Section One

* Section Two

* Links
  This is a number link: [[Section One]]
  This is a textual link: [[Section One][Some text for the link]]

Here's the LaTeX output:

\section{Section One}
\label{sec:orgheadline1}

\section{Section Two}
\label{sec:orgheadline2}

\section{Links}
\label{sec:orgheadline3}
This is a number link: \ref{sec:orgheadline1}
This is a textual link: \hyperref[sec:orgheadline1]{Some text for the link}

Upvotes: 8

York
York

Reputation: 2096

Tom Regner's approach works, however, you don't have to use dedicated target, you can still use custom_id link, but without a description. Like this:

* Section One
:PROPERTIES:
:CUSTOM_ID: sec:one
:END:

* Section Two
You can reference Section One with [[#sec:one]] but NOT
[[#sec:one][Section One]], i.e., the link without description
will get you the actual section number (1).

Upvotes: 11

user594138
user594138

Reputation:

I use dedicated targets for this:

* Section One
  <<sec:one>>

* Section Two
  <<sec:two>>

I can reference Section One with  [[sec:one]] and [[sec:one][Section One]],
but I can get the actual section number (1) to resolve.

This works as expected; see the orgmode documentation on internal links for reference.

Upvotes: 34

Related Questions