Hello, Long time since I’ve been active in this thread!
I’m in the middle of changing my workflow from Scrivener–>TeX to Scrivener–>Markdown–>TeX/docx/…
I’m working on creating a custom Scrivener template for this, along the lines of what AmberV created for TeX. I’ve set up an Equation template just as AmberV did for TeX, and I’ve been able to get Scrivener to assign a linkID to each equation. Now I want to insert each equation’s linkID number into references to the equation’s written in markdown’s language (i.e. “[@eq:linkID]”).
Here is one way to do it (I think): for each cross-reference, I write "[@eq:<$linkID>]. Then I highlight “<$linkID>” in the editor, and then drag the respective equation from the binder onto the highlighted text. Does that sound like the best way to implement this workflow?
So it looks like you’ve noticed that MultiMarkdown has a few conventions for making cross-referencing easy. So long as you are linking to a heading, figure or table that is, but when it comes to anything else, you kind of have to roll your own solution. Thankfully Scrivener makes that a lot less painful than it would be having to type all of this out by hand.
Here is one way to do it (I think): for each cross-reference, I write "[@eq:<$linkID>]. Then I highlight “<$linkID>” in the editor, and then drag the respective equation from the binder onto the highlighted text. Does that sound like the best way to implement this workflow?
So that’s a way you could do things, yes, but personally I’d prefer a more human-friendly approach if you’re going to go to the effort of having labels in the text itself anyway. This method of using the linkID was useful in the LaTeX template because we were going for a fully automatic mechanism where all of the ref and label syntax is operating behind the scenes so to speak. But if we’re going to be typing out the ref into the text, we might as well use something easier to remember and work with.
The attached shows how I would approach adding easily referenced equations in an MMD workflow:
You can probably ignore most of the setup, I just threw the Article preamble into the LaTeX Options pane for the sole purpose of adding the equation packages without any extra hassle, and a little section type / layout stuff to get a working example that can be typeset out of the box. You no doubt have a setup for this already.
The important parts are of course the Section Layout for the equation, and the yellow highlighted text in the first part of “some section”. Starting with the latter, we are using MMD’s convention for linking to an anchor somewhere else in the document. The #label convention is of course taken from HTML, but it will work with LaTeX output as well. The hash will be removed, and this will become \autoref{eq:equation-label} in the output.
This method of using an empty bracket prefix will trigger a natural language approach to referencing, with the output reading, “Refer to Equation 1”. We can of course also put text into the brackets, like “Proof of this can [be demonstrated](#…) simply.”, and have the output become: “Proof of this can be demonstrated (Equation 1) simply.”
That’s how all LaTeX cross-referencing works in MMD, whether you are using “[Name of Heading]” or “[referring text][Name of Heading]”, etc. A bare reference can be embedded into the sentence as text, and an annotated one will be inserted as a parenthetical.
The next thing of note is the binder title for the equation itself. I’ve gone with an approach of using the reference label itself as the title, because it is readily available and easy to insert as a reference wherever I need with simple drag and drop. Obviously “equation-label” is intended to be generic, this is where the human-friendly element comes in, as you can name your equations in a way that is easier to remember and read around.
But there are of course dozens of ways we could approach this, from moving the formal label into a custom metadata field, to even using Replacements to clean up the look of the label further in the reference.
Moving on to the Section Layout, everything of interest will be found in the Prefix and Suffix tabs. We are using MMD’s convention for inserting a raw LaTeX syntax block. All lines between the triple-backticks will be passed thru directly to the .tex file, including the equation itself from the main text.
So this technique is very useful to keep in mind for any kind of special stuff you want to do that MMD itself does not support. We are essentially adding syntax in a way, if we consider Scrivener conventions to be a form of syntax.
That’s pretty much it! Like I say, it’s just one way of doing this, and a fairly straight-forward approach at that. As with all things, you can balance how much syntax you want to see in the editor with how much complexity there is in the implementation. With this particularly balancing act, we push most of the syntax out of view with the Section Layout, leaving only the raw label something we work with directly.
And of course, there is also a lot to be said for keeping implementation-specific syntax out of your source. With this approach all of our syntax in the editor is pure MMD or generated by the compile format. That means, if we want, we can throw together an ODT file for a colleague to proof and add comments to, without them seeing a bunch of LaTeX code.
Thank you SO MUCH! My workflow requires me to compile to markdown so that I can use pandoc on the command line to call the pandoc-crossref filter. This filter handles all the equation numbering and cross-referencing, and it works perfectly for maintaining numbers and cross-references when compiling to docx (something I could never get working to my satisfaction when I was using your LaTeX template to compile primarily to LaTeX; A word to the wise: if you think you’ll ever need to convert tex–>docx when you have equations to cross-reference, take my advice and work with markdown from the beginning). So I’m not compiling from Scrivener to docx (or pdf or LaTeX) directly.
Still, I love Scrivener and I’ve now got a wonderful Scriv template for writing mostly in rich text, and then compiling to markdown for processing by pandoc. I’m especially grateful to you for walking me through the trick of naming each equation “eq:unique-equation-name”, and then having Scrivener add the suffix “{#<$title>}” to each equation. To complete this workflow, I told my Macbook to create “([-@])” whenever I type “@eq” in Scrivener. Then, when I want to reference an equation, I perform that keyboard trick, and then drag the equation from the binder to the right of that “@” symbol. That gives me (for example) “…equation ([-@eq:RamseyEquation])”, which pandoc+pandoc-crossref knows to render as “…equation (1).”