Epic: Crossref Overhaul

[allenmanning]

ASAP

• chapter number and name doesn't show when hovering over cross-ref #8848
• Customizable categories for Float and Block crossreferences
  • Multiple Figure Numbering Environments #1655
  • Numbered and cross-referencable Remarks #3323
  • [Feature Request] Add more theorem types from amsthm (e.g. axiom, assumption, ...) #3979
• Add crossreferences to
  • floats (Tables, Figures, Listings, etc)
  • blocks
    • Callouts
    • Theorem environments
    • Proof environments
• Allow fine-grained control over crossref label formatting
  • A few suggestions for cross referencing and text layout #1095
  • General support for references to the name of a Section/Chapter/etc. rather than its number. #1196
  • Custom Section Numbering Not Functioning #1771
  • FR: customization options for cross references in book project #2356
  • Option for parentheses around equation numbers reference in addition to eq-prefix #2439
  • FR: Uniform Cross-Reference Styling #3440
  • Section crossref in pdf format need number-sections: true #4364
  • Feature request: Ability to show the title of the cross-referenced chapter/section instead of just its number #4532
  • Further customisation of cross-ref labels #5481
  • Cross-referencing unnumbered appendix slide in Revealjs presentation #5621
  • Crossref support for _tags_ #5652
  • Improve treatment of compound crossreferences
    • Use "and" before last reference in group cross references #1706
    • Use dash (-) with group cross references #1707
• Glossary support
  • Feature request: Glossary #1697
• Page number format control for page regions where collations (list of *) are put
  • Book PDF section numbering format #1889
• Crossref collations (list of figures, tables, equations, etc) in non-PDF formats
  • list of tables, list of figures and list of abbreviations in quarto book  #2138
• Equation numbering, multiple refs in a single block, tags
  • referencing equations inside $$ \begin{align} environment #2275
  • enhancement: add MathJax equation numbering for math environments in html #4136
• Short caption support for all Float crossrefs
  • Support -scap in Float crossrefs consistently across formats and input options #3498
  • Support short caption in formats other than latex #4776
• Niceties
  • Emit better error message in the presence of incorrect -labels specs #4938
• Crossref, TOC, knit_child interactions
  • TOC ignoring subsections from child document #3178
• Book parts should be referenceable
  • Cross-reference and link to book parts #2571
  • Support cross reference to book part #3234
• Add crossreferences to
  • inlines (Equations, arbitrary spans, anchors from headings, etc)

Later

• Subcaption issues with and without labels with KableExtra #4517
• fig-* support: layout interaction, non-crossreferenced images
  • #| out/fig-width: ignored when specifying #| layout-nrow/col: #2251
  • out-width is ignored if fig-width is also set in _quarto.yml #3370
• Referenced LaTeX table placed in {.column-margin} causes render error #8772

Uncategorized

• -cap-location control for all Float crossreferences as well as subfloats and non-crossreferenceable figures (such as Pandoc.Figure)
  • handle tbl-cap-location in cells #1829
  • Table caption located at bottom when you have subtables in docx format #1990
  • fig-cap-location:top does place the caption above the figure #2154
  • lst-cap-location #2196
  • Add possibility to change the table, figure captions (docx) #2221
  • Table number does not appear when using a single table inside a div element. #3931
  • crossref: subcaption location control #7456
  • crossrefs: margin everything #7455
  • fig cap location not changing in revealjs #8938
• Allow computational cell code to be decorated (with filename, etc)
  • Code filename not correctly placed when used on computational chunk #2683
• Crossref filter and citeproc interaction
  • Crossrefs: combined internal and external references don't work #1186
• autoref style cross-referencing for PDF engine #2443
• Cross-referencing list items #4045

Outstanding Tasks

• Are we testing Epub crossrefs right now?
  • run output through epubcheck
• Check the crossref label
• Check the issues that refer to this
• Consistency of CSS class names: "fig" vs "figure", etc.

Wontfix

• We don't know enough DocX to make it work in all our usecases (subfloats, custom crossrefs, etc):
  • Native Numbering for Cross-Refs in DOCX #2464
  • Cross-referencing to give native figure numbering in DOCX #2335
• Allow Different Types of Cross Reference-able Outputs from a Single Code Chunk #1229

Needs project overhaul (so will be worked on after that epic)

• Crossref over multiple files #2900
• Quarto Book: reference chunk data in another file #431

[cscheid]

I'm starting to check off issues that are resolved on the branch feature/float-crossref. For quarto users reading this, please don't take the checked-off boxes in here to mean that this work is ready to use. (feature/float-crossref is specifically not in a usable state right now.)

[mcanouil]

(edited by cscheid to move issue to main comment)

[mcanouil]

(edited by cscheid to move issue to main comment)

[bryanhanson]

I don't see it explicitly here, so for completeness make videos cross-referable, discussed here.

From my perspective, the format that would be consistent would be @vid-my-video or something similar.

[cscheid]

@bryanhanson You will implement the category yourself. It's under "Customizable categories for Float and Block crossreferences"

[bryanhanson]

@cscheid sorry I don't understand. Do you want me to add it there? I can't edit that task list. Or are you saying when completed I'll be able to define the particular type of cross-ref myself? Or something else?

[mcanouil]

@bryanhanson to rephrase:

• @cscheid is working on redesigning the whole cross-reference feature to work on possibly everything by allowing the user to define its own "structure".
• @cscheid only showed what's the future of Quarto holds, you can't use that example yourself now (it's going to be documented in the documentation when ready).
• this issue is to track that work. @cscheid mentioned it because if you want to know when the above feature will be usable in 1.4 pre-release, then you can "watch" this issue, i.e., closing this issue (or part of it) will tell you it's in the pre-release.
• currently what you want to do is not possible and the only thing you can do is to wait until the work is "ready".

[cscheid]

@bryanhanson As of the latest commit on main, what you're suggesting is possible. We still have to write (a lot of) documentation for the features, but see https://github.com/quarto-dev/quarto-cli/blob/main/tests/docs/crossrefs/v1.4/custom-categories/diagrams.qmd for a minimal example.

[cscheid]

Done in v1.4

• ensure format options work across formats (or document where they can't)
  • [Bug] some crossref options do not work for pdf format  #215
• control numbering and formatting of anchor crossrefs
  • support creating special counter scopes for crossrefs #644
  • ToC does not play well when sections are numbered #1145
  • Feature request: Some way to reset number counter for tables and figures. #5614
• Caption format control for float crossrefs
  • enable captions to have a heading and text part #645
• Bookdown text references: in-body captions that can be "included" via references
  • Feature request: Bookdown-style text references #1959
• Crossreferenceable callouts
  • unexpected behavior in callouts using #xxx- label as header #2241
  • crossref overhaul: callouts #4863
• Float crossrefs, subfloats, captions and lack thereof
  • Float crossrefs with unlabeled subfloats #2492
  • Crossrefs: support uncaptioned floats #2551
  • error if no table caption included #3603
  • Weird fig-cap placement with fig-subcap with pdf output #3711
• Crossrefs in the content of computational outputs like tables
  • Citations in tables do not render correctly outside of raw markdown and kable #3340
• Be careful about redefining block crossref environments in Beamer and amsmath generally
  • Beamer and theorems #3650
• Be careful about introducing nested LaTeX floats
  • labeled Mermaid & Graphviz diagrams generate nested figure environments in LaTeX #3736
• allow arbitrary content as the payload of float crossrefs (e.g. if a third-party library tells us that something is a table, we go along with it) Allow listing captions/labels on executable code blocks and computational tables
  • DT::datatable cross-referencing and captions  #1084
  • Captions & crossrefs not rendering in Quarto with Flextable #1556
  • lst-label and lst-cap do not produce listing caption and reference #1580
  • Citations in gt table captions not resolved #2297
  • use "#| label: eq-xxx" to add label to equation generated in code chunks (e.g. sympy)  #3397
  • missing reference for gt table in word document #3600
  • missing reference for flextable table in word document #3601
  • Code cells with #| output: asis ignore #| tbl-cap and #| label:  #3770
  • Crossref type override #4168
  • Table API overhaul: computational subtables? #4171
  • stargazer html CrossRef #4637
  • Filenames of executable blocks should be treated the same as as non-executable #5101
  • How to set ''crossref-resolve-refs' to false in quarto markdown. #5161
  • wrong language & crossref output when format:docx #5383
• References to computationally-generated sub-tables/sub-figures #1494
• Cross reference textual output of code evaluation #3181
• Flexible cross referencing: allow figures to be labelled as tables #3914
• Custom cross reference schemes #4343

[bcdavasconcelos]

Not sure whether/where to post this: The Typst output doesn't have any defined Amsthm cross-reference environments in version 1.4.537. (This causes rendering to fail). Hope this helps.

[mcanouil]

It does not really without a reproducible example.

Could you open a new issue with a reproducible example?
Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? Thanks.

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)
```

![A placeholder image](https://placehold.co/600x400.png)

The end.
````

[bcdavasconcelos]

My pleasure, @mcanouil. See #8167.

[cscheid]

See #10020

[acxz]

@cscheid I noticed from the OP that certain docx cross reference features are slated as won't fix.

Would it be possible to revisit this? Specifically creating lof and lot in docx similar to toc? (I realize this may need to be a pandoc issue instead see: jgm/pandoc#8245)
See: #2464 for more conversation regarding this. Let me know if I should create a specific issue to track this or if the discussion is enough, considering it is already being tracked in the OP.

[cscheid]

Would it be possible to revisit this?

Not at the near future, sorry.

[olivroy]

FWIW, the lot / lof , issue has been fixed in pandoc jgm/pandoc#10029 and will be present in pandoc 3.5. So, it may be possible for Quarto to implement