-
-
Notifications
You must be signed in to change notification settings - Fork 3.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Feature: internal links to tables and figures and headers #813
Comments
That would be lovely indeed. In academic writing it is quite often necessary, and while automatic numbering of figures and tables is nice, it really should be linked to what is in the text. |
One could use the figure caption as link target, similar to links to captions:
And/or without automatic generation of link text:
See also issue #615 on automatic numbering of figures and tables in HTML output. |
A more consistent format would be
See the current attribute format for headers. |
indeed, that is a more consistent format. About the implementation:
Can anybody (@jgm ?) make an educated guess on how much work either of the solutions will be? |
I agree - this is essential for academic writing. I wish I knew Haskell! The current way around this, in the mailing list discussion, is functional but clumsy. Would this mean using
you would get the latex output:
|
sort of relevant pr: #509 Mailing list discussion: |
I just tried to write something like
I was surprised that did not work. It showed the image without caption, and a raw "{#something}" afterwards. I assumed curly braces were for assigning attributes to anything... :D |
A workaround with numbered example lists is added to #904 For my purposes, this method works well with docx. |
I agree that being able to reference figures is essential to academic writing. The workarounds linked to above aren't really satisfactory, in my opinion
|
Similar syntaxes would be very interesting for equations, too. In fact, why not adopt a completely general syntax? It would be especially nice if it could carry over to LaTeX bits, once you have to bail out and use say \begin{align} and friends. |
I have sympathy for the numbered example list approach, mainly for two reasons: Firstly, what we want are not really links but references, and secondly, the use case for numbered example lists is already close to, e.g., numbered equations. The example from the docs is close to a typical use case for figure references:
This mechanism can already be used for figure references, as CFCF pointed out:
However, there are a few drawbacks:
Thus, a proper referencing scheme would need a bit additional thinking. Especially, PDF and HTML output should work alike, probably by pandoc adding the |
Your workaround works as suggested, but I had to remove the parentheses when referencing the label, otherwise they were rendered in the output. After this modification my example looks like this:
To remove the automatic numbering in LaTex (
After rendering to pdf this produces the following output: |
Just came across this issue as well and ended up here. I'm also really in favor of support for the syntax suggested by @jgm above:
Especially since this is the standard way of dealing with this in PHP Markdown Extra: |
Has there been any developments on this? It also seems to me that @jgm suggestiong
is the most consistent internally and with other tools. What would need to happen for this to be implemented? |
I was wanting to add support for this addition to the syntax. When trying to replicate papers using markdown for the scholmd project, this is the feature that stands out as most needed by Pandoc . In short this can be addressed through the general use of A general syntax for labels When the document is rendered, Pandoc would associate a number with each labelled element, based on its type, and its position in the document. This logic would need to be carried out in Pandoc, so that it was available to the range of back-end writers (including HTML). The philosophy would be similar to Pandoc-citeproc, which carries out its own formatting of citations, rather than delegating to writers that support this approach (such as bibtex for latex). An option would to have this behaviour depend on the backend (so that it in latex it inserts Labelled elements may be linked to, with the The syntax A further syntax could be to use square brackets |
@edwardabraham It must be pointed out that the syntax [@lalune] is already used in pandoc for bibliographical citations. |
@kovla @edwardabraham I don't see why |
@kovla The idea was to deliberately overload the @evitaerc I prefer using the Note that this extension is |
@edwardabraham I tried the In fact, no one out of ten or so people have used Unfortunately the internal reference mechanism required heavy modification of the Markdown reader (additional state must be kept during the parsing process) and a custom AST, so I can't conceive of a filter implementation in the near future. |
Personally, the |
+1 for use of There are two approaches to my mind
|
I am pleased to announce the 2.0.0 release of the pandoc-xnos filter suite:
The filters emerged from recommendations made by the community in this thread, and in particular this post by @scaramouche1. |
For the label/ref problem, labelling itself is pretty simple: they're just opaque identifiers, though some document systems (like some LaTeX packages and the existing reference-providing filters) have prefixed labels like Numbering things and rendering references to them, on the other hand, strongly resembles the process of generating citations and bibliographies, and the ways that can be done vary almost as widely. Typing of numbered things, choosing how to insert numbers in titles, reference prefixes, configuring numbering with counters, modifying counters in the text, and automatically generating identifiers can all be supported and configured. So It will be hard to choose exactly how Pandoc will number things and render references, and what configuration will be allowed. It could be as complex as LaTeX, but I'm not sure if that complexity is welcome in Ideally, the intermediate representation would be modified so that in principle a filter could perform numbering and reference rendering like -- Support for labelling more things can be added by adding Attr to more types.
data Inline
= ...
| Ref [Reference] [Inline]
...
-- Might want to record whether or not it's a page reference for
-- paginated formats like TeX.
data Reference = Reference
{ referenceId :: Text
, referencePrefix :: [Inline]
, referenceSuffix :: [Inline]
, referenceMode :: ReferenceMode
, referenceHash :: Int
}
-- The main modifier of a reference at the reference site itself
-- is how to render a prefix, if at all.
data ReferenceMode
= UpperCasePrefix
| LowerCasePrefix -- may not be needed?
| SuppressPrefix
| NormalReference The intent is to support using Slightly off-topic, but I have no idea what the |
If numbers (meaning the full rendered number, like "2.4.1") were stored in the |
We already use With
|
Yes, internal references are enough like citations that I thought the same sort of representation and handling would be good, since I think for the writers that didn't support citations (all of them initially), the fallback would be exactly what the fallback for |
If |
For some internal manuscripts I've put together a Lua filter that handles most cross references. It currently assigns IDs to tables and equations based on attribute blocks at the end of the caption (i.e. It's not meant as serious competition to the excellent pandoc-xnos, but rather as testing ground for new features (i.e. table attributes) and pandoc-xnos compatible implementation for the most basic needs. |
I tried to summarize current out-the-box pandoc LaTeX → docx experience in the question at StackOverflow. With test document and I see many strange things:
Hope you will provide official out-the-box pandoc solution for it without third-party filters and so on. Do we currently have a solution, which I probably missed? |
@N0rbert one thing you're missing is the
There's some low-hanging fruit here:
Of course, that still leaves us without good references to numbered equations (indeed, without numbered equations). |
Yes, we could establish a protocol where filters set a specific metadata value to indicate that they have already handled numbering. Maybe for consistency w/ |
Previously we included the text of the label in square brackets, but this is undesirable in many cases. See discussion in <#813 (comment)>.
- Resolve references to theorem environments. - Remove Span caused by "label" in figure, table, and theorem environments; this had an id that duplicated the environments' id. See #813.
Thank you for quick reply. With |
I'm using |
@wenbopeng let's retest with latest Pandoc 3.1.8 on Debian 12:
With all above code and commands I got the following rendering: So only equations are not numbered - resulting document has |
Thank you very much. I hope to get docx from markdown. I want to insert the field code of the picture/table. The picture problem has been solved so far, but I can't find a way to number the table. first, use ![image name](img.png){#fig:img}
see`<w:fldSimple w:instr="REF ref_fig:img" />`{=openxml}... The above syntax can be converted through lua filter function Str(elem)
local img_key = elem.text:match("%[@fig:(.*)%]")
if img_key then
return pandoc.RawInline('openxml', '<w:fldSimple w:instr="REF ref_fig:'..img_key..'" />')
else
return elem
end
end so, you can use ![image name](img.png){#fig:img}
see [@fig:img] ... But I don't know how to deal with the table when md2docx |
@wenbopeng probably you have to try bookdown - see https://bookdown.org/home/about/ . It has rich functionality and uses Pandoc under the hood. |
thankyou,I use R, but I'm not going to do that. I can already do it fine with pandoc-crossreference. But I want it to be with Field Code and I need to update the cross-reference automatically in MsWord |
It's currently possible to include internal links to sections. I'd like to propose a similar feature for links to figures/images and tables.
It may make sense to provide this feature only if the figure/image or table that is being linked to has a caption. In that case Pandoc can today automatically generate a number for the figure or table and include it in the caption, e.g. "Figure 15".
At the most basic, the text of the link would be provided by the user, as is currently the case for links to sections.
Of course it would be very convenient if the automatically generated number for the figure or table would also be used for the text of the link, e.g. "as can be seen in Figure 15, blah", where "Figure 15" would be the internal link whose text is auto-generated from the figure it points to.
The text was updated successfully, but these errors were encountered: