Cross reference to any text in bookdown

[dkStevensNZed]

My question is about cross referencing in R Markdown/bookdown using bookdown::tufte_book2 rendering. The tufte_book2 engine only allows 2 levels of sections, which is fine, but I want to cross reference a '3rd level' marker of my own designation strictly for cross referencing purposes. One is allowed label 1st and 2nd level section headers but I don't understand how to cross reference just a random bit of text, say a bold label for a 3rd level heading and then refer to it later. Just so it's clear

Chapter 1 {#chapter1}

Section 1.1 {#section11}

3rd level subhead {#subheadtext}

The # and ## section headings allow the cross reference but the 3rd level doesn't. Any ideas?

[cderv]

What markdown syntax do you use ?

The cross reference feature 2.6 Cross-references | bookdown: Authoring Books and Technical Documents with R Markdown work on headers. What syntax did you use for "the 3rd level " ?

Can you share a full Rmd example ?

[dkStevensNZed]

I use the syntax from above. With the tufte_book2 pdf engine it's clearly stated that they allow 2 levels of headings - no problem there with cross referencing. My question is how to cross reference when it's not a heading/subheading.

3rd level subhead {#subheadtext}

The explanation in the responder's 2.6 Cross ... refers to section heads and as I say, that works fine. I'm wanting to cross reference a subheading of my creation, not one that's numbered under the 'official' 2 heading levels allowed by tufte_book2. I'll try to put together an example but my application is a 10 chapter book with a number of affiliated files (r sources, .png files, etc.) Stand by for the example.

Here's an example

---
title: "Test tufte_book2"
author: "David K Stevens"
date: "`r Sys.time()`"
site: bookdown::bookdown_site
output:
  bookdown::tufte_book2:
    toc: true
    keep_tex: true    
    number_sections: yes
header-includes: 
documentclass: book
github-repo: rstudio/bookdown-demo
description: "Test"
---

# Chapter 1 {#chapter1}  

## Section 1.1 {#section11}

MySection {#mysection}  

\vspace{10pt}
**Attempt to reference:**


Reference to Chapter 1: Chapter  \@ref(chapter1)

Reference to Section 1.1: Section  \@ref(section11)

Attempted reference to MySection:  Subsection \@ref(mysection)

With the resulting pdf file

_main.pdf (50.6 KB)

[cderv]

@dkStevensNZed

MySection {#mysection}

The referencing mechanism using markdown syntax will only work for headings. You can't use that feature on regular text and paragraph.

Your output is PDF only ? you could probably use \label{} directly ?

MySection\label{mysection}

[dkStevensNZed]

Thanks cderv. It's good to hear from an authority in these matters. I tried the \label{...} approach and it worked fine for the pdf version. Since you mentioned pdf, I'm actually hoping to provide both a .pdf and .html version of this work. I've been looking through the bookdown document and don't see an equivalent labeling syntax for .html. What am I missing?

[cderv]

@dkStevensNZed

I've been looking through the bookdown document and don't see an equivalent labeling syntax for .html. What am I missing?

As I said, the cross referencing feature using a markdown syntax only works for Headers. This is a feature from Pandoc for internal links https://pandoc.org/MANUAL.html#internal-links

However, I remember this syntax which pandoc's Spans

[MySection]{#mysection} 

You can then reference using markdown link

Subsection [My section](#mysection)

The syntax \@ref is only for LaTeX so you could not use that for HTML. This is working in bookdown only for headings, as a built in feature. So you can't have auto resolution of numbered section.

Anyway, there is no built syntax for referencing as I think you want.

The other solution would need to mix formats. You need to use specific output format features for that:

• \label in PDF
• id attributes in HTML that you could put on div or on span to make a link too using links.

I don't think there is any built way to do that, but there could be using a Lua filters maybe to have a common syntax for both.

Otherwise, you can make a R wrapper function for writing both syntax depending on the output rendered. See about multi format output and example about coloring word to see how that can be used.

You can also write raw code in your Markdown document, and pandoc should skip the raw code depending on the output format. Pandoc's raw inline and raw blocks are helpful for that.

[dkStevensNZed]

Thank you cderv. This is very helpful. I'm wondering if the best thing to do is just avoid those internal links but I'll give your suggestions a try. I've been down this rabbit hole for awhile and it's good to get some fresh air. Regards.