how to change the syntax for inline references?

[chaojiwudifeitianyuren]

Description

How to Customize Cross-reference Syntax in Quarto

Problem Description

When rendering qmd files to docx using Quarto, the default cross-reference syntax displays figure and table numbers as:

Figure 1
Figure 2
...
Table 1
Table 2
...

This default format may not meet specific documentation requirements, especially in academic or technical writing where hierarchical numbering is often preferred.

Desired Output

I would like to customize the numbering format for figures and tables to follow different hierarchical structures. For example:

Option 1: Chapter-based Numbering

Figure 1-1
Figure 1-2
...
Table 1-1
Table 1-2
...

Option 2: Section and Subsection-based Numbering

Figure 1-1-1
Figure 1-1-2
...
Table 1-1-1
Table 1-1-2
...

Current Challenges

After reviewing the Quarto documentation, I found that:

1. The default cross-reference implementation seems to be hardcoded
2. The documentation doesn't provide detailed information about how to customize cross-reference syntax

Is there a way to customize the cross-reference syntax in Quarto to achieve these hierarchical numbering formats? This would be particularly useful for:

• Academic papers requiring specific formatting standards
• Technical documentation with complex hierarchical structures

[chaojiwudifeitianyuren]

Questions

1. Is there a built-in way to achieve this customization?
2. If not, what would be the recommended approach to implement this feature?

Any guidance or suggestions would be greatly appreciated!

[mcanouil]

Have you looked at the documentation and other threads dealing with exactly this question?

• https://quarto.org/docs/authoring/cross-reference-options.html (edit: look at the last section)
• https://quarto.org/docs/reference/metadata/crossref.html
• https://quarto.org/docs/authoring/cross-references-custom.html

Looking at the documentation and other threads before asking a question can save a lot of time to many people, including yourself.

[mcanouil]

If the built-in methods do not match your needs for the formats you are using (not clear what those are):

• use LUA filter
• post-process your output
• etc.

[chaojiwudifeitianyuren]

Dear developers, I'm a Quarto beginner. First, I want to thank you for your work - Quarto has made writing papers and reports much more convenient, and now I can hardly work without it.

These days, I've been trying to solve cross-referencing numbering issues. The parameters in the English documentation don't fully meet my needs, and this problem remains unresolved. I'll report the basic process.

Since this was my first time asking questions on GitHub, I may have missed some basic information, please excuse me. Here's the supplementary information:

• System: Windows 11
• Quarto: 1.6.42

My goal is to achieve the following cross-reference numbering format in docx:

<CaptureNumber>-<SectionNumber>-<ItemNumber>

I want this numbering format for both initial declarations and subsequent references. Here's my test text:

@tbl-test1

@eq-test1

@eq-test2


# chapter1	

## section1


::: {#tbl-test1 }
|          | VLEO  | LEO |
| -------- | ------------ | -------- |
| height | <300km/450km | <1000km  |

TestTable
:::


# chapter2

## section1

$$
E=mc^2
$${#eq-test1}


$$
F=G\frac{m_1m_2}{r^2}
$${#eq-test2}

After reading your comments, I reviewed this webpage again:
https://quarto.org/docs/reference/metadata/crossref.html

I found a parameter that could partially meet my needs, which I had previously misunderstood and overlooked. So I set my YAML to:

---
crossref:
    chapters: true
---

Now I get the following result:

The numbering format is:

<CaptureNumber>.<ItemNumber>

Now I'm one step closer to my goal. I can accept not having section numbers, but I want the delimiter between chapter numbers and item numbers to be "-" instead of ".".

After trying title-delim and appendix-delim parameter, I confirmed they cannot achieve my goal.

[chaojiwudifeitianyuren]

so I render .native doc：

Pandoc
  Meta
    { unMeta =
        fromList
          [ ( "crossref"
            , MetaMap (fromList [ ( "chapters" , MetaBool True ) ])
            )
          ]
    }
  [ Para
      [ Link
          ( "" , [ "quarto-xref" ] , [] )
          [ Str "Table" , Str "\160" , Str "1.1" ]
          ( "#tbl-test1" , "" )
      ]
  , Para
      [ Link
          ( "" , [ "quarto-xref" ] , [] )
          [ Str "Equation" , Str "\160" , Str "2.1" ]
          ( "#eq-test1" , "" )
      ]
  , Para
      [ Link
          ( "" , [ "quarto-xref" ] , [] )
          [ Str "Equation" , Str "\160" , Str "2.2" ]
          ( "#eq-test2" , "" )
      ]
  , Para
      [ Link
          ( "" , [ "quarto-xref" ] , [] )
          [ Str "Figure" , Str "\160" , Str "2.1" ]
          ( "#fig-test" , "" )
      ]
  , Header 1 ( "chapter1" , [] , [] ) [ Str "chapter1" ]
  , Header 2 ( "section1" , [] , [] ) [ Str "section1" ]
  , Table
      ( "" , [] , [] )
      (Caption Nothing [])
      [ ( AlignDefault , ColWidthDefault )
      , ( AlignDefault , ColWidthDefault )
      , ( AlignDefault , ColWidthDefault )
      ]
      (TableHead
         ( "" , [] , [] )
         [ Row
             ( "" , [] , [] )
             [ Cell
                 ( "" , [] , [] )
                 AlignDefault
                 (RowSpan 1)
                 (ColSpan 1)
                 []
             , Cell
                 ( "" , [] , [] )
                 AlignDefault
                 (RowSpan 1)
                 (ColSpan 1)
                 [ Plain [ Str "VLEO" ] ]
             , Cell
                 ( "" , [] , [] )
                 AlignDefault
                 (RowSpan 1)
                 (ColSpan 1)
                 [ Plain [ Str "LEO" ] ]
             ]
         ])
      [ TableBody
          ( "" , [] , [] )
          (RowHeadColumns 0)
          []
          [ Row
              ( "" , [] , [] )
              [ Cell
                  ( "" , [] , [] )
                  AlignDefault
                  (RowSpan 1)
                  (ColSpan 1)
                  [ Plain [ Str "height" ] ]
              , Cell
                  ( "" , [] , [] )
                  AlignDefault
                  (RowSpan 1)
                  (ColSpan 1)
                  [ Plain [ Str "<300km/450km" ] ]
              , Cell
                  ( "" , [] , [] )
                  AlignDefault
                  (RowSpan 1)
                  (ColSpan 1)
                  [ Plain [ Str "<1000km" ] ]
              ]
          ]
      ]
      (TableFoot ( "" , [] , [] ) [])
  , Header 1 ( "chapter2" , [] , [] ) [ Str "chapter2" ]
  , Header 2 ( "section1-1" , [] , [] ) [ Str "section1" ]
  , Para
      [ Span
          ( "eq-test1" , [] , [] )
          [ Math DisplayMath "\nE=mc^2\n \\qquad(2.1)" ]
      ]
  , Para
      [ Span
          ( "eq-test2" , [] , [] )
          [ Math DisplayMath "\nF=G\\frac{m_1m_2}{r^2}\n \\qquad(2.2)"
          ]
      ]
  , Plain
      [ Image
          ( "" , [] , [] )
          []
          ( "./assets/%E8%A1%A8-%E5%85%B3%E4%BA%8E%E7%94%B5%E7%A6%BB%E5%B1%82%E5%81%87%E6%83%B3%E8%96%84%E5%A3%B3%E7%9A%84%E9%AB%98%E5%BA%A6/image.png"
          , ""
          )
      ]
  ]

After examining the native intermediate file, I found:

• Quarto cross-reference numbers are stored in the Link class
• This Link class contains an identifier called "quarto-xref"
• This Link class contains a string that stores the cross-reference number

If I could modify this string, I could achieve my goal. Before that, I needed to test how it's read. So I wrote a Lua script to read the Link class and modify the intermediate file to meet my requirements.

local inner_delim = "-"

function Para(el)
    print("Para function called") 
    print("el:", el)
    return nil
end

function Link(el)
    -- Print basic information about the link element
    print("Link function called")
    print("\n--- Link Information ---")
    print("Is cross-reference:", el.classes[1] == "quarto-xref")
    print("content:", el.content)

    return nil
end

However, something strange happened - the Link class wasn't being read. When I checked the Lua output, I found that the Link function wasn't being called, although the Para function was. So I examined the Para content:

Para function called
el:     Para [Cite [Citation {citationId = "tbl-test1", citationPrefix = [], citationSuffix = [], citationMode = AuthorInText, citationNoteNum = 1, citationHash = 0}] [Str "@tbl-test1"]]
Para function called
el:     Para [Cite [Citation {citationId = "eq-test1", citationPrefix = [], citationSuffix = [], citationMode = AuthorInText, citationNoteNum = 2, citationHash = 0}] [Str "@eq-test1"]]
Para function called
el:     Para [Cite [Citation {citationId = "eq-test2", citationPrefix = [], citationSuffix = [], citationMode = AuthorInText, citationNoteNum = 3, citationHash = 0}] [Str "@eq-test2"]]
Para function called
el:     Para [Cite [Citation {citationId = "fig-test", citationPrefix = [], citationSuffix = [], citationMode = AuthorInText, citationNoteNum = 4, citationHash = 0}] [Str "@fig-test"]]
Para function called
el:     Para [Math DisplayMath "\nE=mc^2\n",Str "{#eq-test1}"]
Para function called
el:     Para [Math DisplayMath "\nF=G\\frac{m_1m_2}{r^2}\n",Str "{#eq-test2}"]

I discovered that there was no Link class within the Para class because they had all been converted to Cite class, and the content didn't contain reference numbers. I'm not sure how to proceed from here.

[mcanouil]

You are really in deep waters here.
Cross-reference is a custom Quarto thing that uses special nodes (i.e., FloatRefTarget).

• See FloatRefTarget
• See More precise targeting of AST processing phases

[chaojiwudifeitianyuren]

---
crossref:
    chapters: true

format: 
    native: 
        toc: false
    docx: 
        filters: 

            # - at: pre-ast
            - at: pre-render
              path: "./number-delim.lua"
        toc: false
---

the problem is resolved,just now i have saw there was ref.lua in quarto source code,now i get a way to preprocess the file.now i get the correct ans

Link function called

--- Link Information ---
Is cross-reference:     true
content:        [Str "Table",Str "\160",Str "1.1"]
Link function called

--- Link Information ---
Is cross-reference:     true
content:        [Str "Equation",Str "\160",Str "2.1"]
Link function called

--- Link Information ---
Is cross-reference:     true
content:        [Str "Equation",Str "\160",Str "2.2"]

highly appriciate!

[chaojiwudifeitianyuren]

local inner_delim = "-"

-- This code executes in the pre-render phase and can handle Link and Span elements
-- Its purpose is to change number delimiters in:
-- 1. Cross-references
-- 2. Equation numbers


-- function Para(el)
--     print("Para called")
--     print("el:", el)

--     return nil
-- end

function Link(el)
    -- Only process links of cross-reference type
    if el.classes[1] == "quarto-xref" then
        -- Iterate through all elements in the link content
        for i, item in ipairs(el.content) do
            -- If the element is a string type and contains "."
            if item.text and item.text:find("%.") then
                -- Replace "." with the specified delimiter
                el.content[i].text = item.text:gsub("%.", inner_delim)
                -- print("Processed content:", el.content[i].text)
            end
        end
        return el
    end
    return nil
end

finally i can change delim between [ChapterNumber] and [ItemNumber] as i need