All of these “parameters” are already present in Scrivener 3. What are you asking for that doesn’t already exist?
2 Likes
Scrivener’s compiler does do part of the processing (transferring semantic structure of the project), but if we assume you are referring to the “final visual product”, then yes.
Binder is amazing yes (plus the power of styles, which are BOTH abstract and visual scaffolding for words, unique among writing tools). But the compiler is doing way more than simply lining up docs. In my mind the compiler[1] is the biggest single feature that allows me to write in a semantic structure that can be parsed out to a huge range of visual outputs.
- I keep the Quarto/Pandoc metadata outside the “Draft” folder but then attach it as front-matter. Front/back-matter are useful adjuncts for structure (ScrivQ does amazing things here to generate Quarto YAML from binder items)…
- Custom metadata (stored not in the Binder but the Inspector) can also drive compiler features, so technically this is also sent to Quarto/Pandoc. For example you can use metadata to store quarto
#idor.classspecifiers that transform the Quarto layout. - More minor, but I keep all my figures in the Binder and these are exported, these are not technically text but the binder can manage multiple figures brilliantly… for example I make my figures in Adobe Illustrator that are stored in the binder, then export PNGs or SVGs that are kept as children to the AI, and these are then linked into the draft docs and exported.
- I’m sure you could use notes / annotations etc. for content if you wanted, but at least i don’t.
Yep, this is why I love Scrivener. Note that Scrivener’s compiler does more than the “starting point”, it generates an almost fully formed complex document that only requires some minor post-processing (which Scrivener can also orchestrate). My post-processor makes any changes, then runs Quarto/Pandoc directly, so a single keypress in Scrivener orchestrates a full workflow to final visual product without further ado…
If I could dictate what I wanted in Scrivener 4 for Academic users:
- Bundle Pandoc, thus allowing citeproc (the bibliography engine built-in to Pandoc), to generate Bibliographies in any Scrivener compiler output.
- Use the user’s shell session (the .zshrc / .bashrc settings) for post-processing. This stops bootstrapping scripts like mine from being needed.
- Have “export files” in the compiler, so we can store accessory files like CSL or templates in the binder and then selectively export them to the current compile folder at compile time automatically. This enables Scrivener to automagically set up a destination folder with required files. Different compile formats could export different templates etc.
- Better tables, Pandoc now supports more complex table features and Scrivener should be able to drive them.
- More nuance in how text is transformed. An example being the suggestion from @amberV about {properties} placement.
- Possibly have replacements that could be toggled to work before and after the markup is generated. This would be a single
︎ to toggle this in the GUI.
I’ll leave it there…
[1] the compiler + the binder are synergistic more precisely, it is hard to really just say one feature alone is the main workhorse…
3 Likes
Scrivener 3 is amazing! But there are some friction points for academic/technical writing, which often uses Markdown and LaTeX and gets processed via Quarto or Pandoc. My hope in this thread is to distill it down into a clear DAG so we can develop a robust way of using these tools together. In some cases, no changes will be needed in Scrivener, but maybe we figure out a better way of using Scrivener. In other cases, we may pinpoint a difficult challenge for which adding a feature in Scrivener 4 would be the best (or only) solution. The goal is to be able to describe this very specifically to the Scrivener developers, ideally to make adding such a thing feasible. We are trying to go beyond simply saying “please add better Markdown support,” which doesn’t really help. Especially with the New Simpler App being developed (and likely having some code back ported into Big Scrivener), this type of brainstorming may end up being helpful.
That’s fine. I understand. But the post I was responding to simply describes existing Scrivener 3 capabilities.
1 Like
I worry about keeping metadata that is meant to be sent to Quarto/Pandoc hidden in the nooks and crannies of the Scrivener interface. My thought is that if something is meant to go to Quarto/Pandoc, then it should be in the Binder text documents somehow.
My thought is that Scrivener’s other tools would be used to help the writer within Scrivener, during the writing process itself. For example, notes to self, summaries, bookmarks, status labels, etc. It is analogous to storing reference material in the Binder, but this would not get included in the export.
Storing Quarto/Pandoc-specific metadata in various parts of Scrivener’s interface may risk incompatibility in the future (if, for example, Scrivener 4’s interface changes), or may just be harder for the writer to keep track of.
Certainly, there are pros and cons to each approach though.
Yes, this seems like a powerful workflow that keeps everything within the Scrivener file bundle, rather than managing a folder of external assets.
When you link to a specific file format (child object), how do you accomplish that in Scrivener?
And what happens behind the scenes during Compilation and Processing?
If you want to, you can certainly put it there.
Scrivener is unlikely to ever produce Markdown output exclusively, so it’s likely to continue to give users the flexibility to put their metadata wherever is most convenient for them.
1 Like
Yes, all your suggestions are golden. I think the Shell is a big one.
The Inspector isn’t a nook or cranny, it is a core part of the UI that is not going anywhere as much as i can predict these things… I could embed the metadata in the text itself, and Scrivener is great in that there are several ways to do things. But custom metadata really makes the workflow smoother, it is document specific yet stays out of your way during writing.
I drag a figure into the editor. I have Scrivener set up so that it links not embeds the image.
Therefore I can edit the image in the binder and any place it was linked also updates. The slight wrinkle here is that the binder stores the files, and so you have to use Scrivener to edit them externally and save back to the same files:
“Replace Media file…” is also useful here. I use mouse gestures using BeterTouchTool so I gesture over a binder image and “Replace Media file…” runs on that item (you could bind a keypress for that, but i like gestures)…
2 Likes
Thanks. But when Scrivener compiles to Markdown, does that internal link become the standard Markdown that Pandoc/Quarto expects, , with the image being stored within the compilation folder as test_figure.png?
I’m wondering about the intermediary steps between .scriv > .md (.qmd) > Pandoc/Quarto processing.
And how would Scrivener manage parameters attached to the link such as size or placement – for example, what would you do in Scrivener to have it output the Markdown {fig-align="left" width=4in} or adding a cross-ref like {#test-fig}? (I believe these are the nuances that you and AmberV were talking about earlier in the thread, and perhaps what your Ruby script helps to take care of.)
Yes 
. Technically, Scrivener converts linked or embedded images to markdown reference links:
![A Caption comes from a paragraph styled with the caption style that follows an image in the editor][ImageID]
…
[ImageID]: image.png {width=720 height=391}
Markdown captions are generated from the caption style, and width and height properties can be generated using a resize dialog from the context menu for the image in the editor. The image is exported with the name specified in the binder, you don’t need to worry about any of this, it is all handled automagically by Scrivener: drag-n-drop an image, write a caption and Scrivener handles the naming and markup.
From above you see there are no real intermediaries for basic function.
One problem I’ve faced however is that Scrivener’s width and height can conflict with layout in some formats (Typst for example which cannot use unitless values). In these cases I run a regex that removes the dimension attributes in my post-processor, e.g. scrivomatic/quarto-run.rb at master · iandol/scrivomatic · GitHub
This is exactly the problem with pandoc-crossref and Quarto cross-references: they use the #id attribute but how do you get the label into the reference link. The label will be somewhere close to the image markup, I prefer to write my labels inside the caption for example, but Scrivener will put attributes at the end of the document:
![#fig-test ⇦ I put my label in the caption, but pandoc-crossref or quarto need it in the {attributes} all the way at the bottom of my document ↓][ImageID]
…
[ImageID]: image.png {ID SHOULD BE HERE width=720 height=391}
My script takes that markdown and rewrites it to put the label in the right place, thus cross-refs now work fine. The same mechanism that I use for crossref labels can be used for any other attributes.
As a worked example: If you make use of section types, metadata and replacements, then attributes can be stored in the inspector. My Quarto sample project demonstrates how this works. Here is a document which will become a Quarto figure with custom attributes in the output .qmd, note the Inspector values:
I use a temporary marker in the caption ««AB»», the compiler replaces this label with the values you enter in the inspector:
…becoming this raw markup from Scrivener:
![{#fig-withattributes .myclass fig-align="right" width=3cm height=2cm} This figure uses custom metadata values to identify the class, ID, width and height. The ««AB»» tag at the start of the caption is replaced with the correct Scrivener placeholders by the compiler; see global replacements for the details…][Elephant3-1]
…
[Elephant3-1]: Elephant3.jpg
This will of course fail in Pandoc or Quarto as the attributes shouldn’t be inside the caption; because Scrivener uses ref links they need to be moved out of the caption and to the bottom of the doc, so my post-processor script rewrites the markdown to:
![ This figure uses custom metadata values to identify the class, ID, width and height. The ««AB»» tag at the start of the caption is replaced with the correct Scrivener placeholders by the compiler; see global replacements for the details…][Elephant3-1]
…
[Elephant3-1]: Elephant3.jpg {#fig-withattributes .myclass fig-align="right" width=3cm height=2cm}
When Scrivener 3 was in beta, we never specifically envisaged Quarto would come along years later and need attributes injected. Honestly, the fact we have a flexible UI to control arbitrary attributes for any piece of content is a testament to how well designed Scrivener’s compiler architecture is. Better control of attribute placement could be improved in Scr4 (what @AmberV and i were discussing, using inline links would make the regex simpler, or some smarter heuristics as suggested by @AmberV would negate the need for post-processing), but this is still a great workflow in Scr3.
1 Like
Thanks for your kind and thorough response. It was very clear, and I understand now.
Your sample project actually demonstrates three alternative writing workflows:
- writing Markdown/LaTeX directly in the editor
- using Styles to simplify markup, injecting customized metadata as the parameters where needed
- using Section Styles to essentially wrap that document in a
divblock; perhaps most important to allow for nesting of a Style within a Section Style block.
You’re right that the fact that any of this is possible is testament to the forward-thinking ingenuity of KB and the Scrivener development team, beta testers, et al.
2 Likes