ScrivQ | A template to control Quarto, export multiple files, manage bibliography and easily create cross-references

Thanks! The duplicate format option is perfect. That’s how my I have a my ScrivPandoc setup set up :grin:

1 Like

Bernardo, does the ScrivTrio template includes the editable templates included wit the previous version of ScrivQ?

Paolo

Paolo @ptram, if you download the latest one, it does include them.

1 Like

As usual, I’m a bit slow with these things. But how do you ask ScrivQ to split the project at a particular hierarchy level, to let Quarto create multiple pages?

EDIT: Probably found. It’s not the hierarchy level, but a deliberate choice through the Section + Break Before section format.

Paolo

Please allow me another question: does ScrivQ expect the original Scrivener documents to be written in markdown, or one can use rich text instead.

For example, rich text paragraphs separated by a carriage return, with no added blank line, are rendered as if there was no paragraph end.

This, unless I check the “Convert rich text to markdown” option in the Compile dialog. Should this be checked, if the original Scrivener docs are in rich text?

Paolo

I admit I’m totally lost. I think that ScrivQ is totally ignored, and Scrivener just compiles to a single HTML file or generates a PDF file with its internal features.

I’ve tried by checking some of the options in the ScrivQ front matter (for example, changing pagesize in the PDF group), but nothing changes.

I’ve also tried by assigning different section types (Section - break before) to the section where I wanted a new page, but nothing changed. Still, I got a unique HTML page.

Is there something else to do, after having created a new project from the ScrivQ template, and having populated the Manuscript section of some documents?

Paolo

Scrivener hanged when trying to compile, and now it always hangs when trying to compile even the simplest document.

If I restart the Mac, the default compile formats work fine on other documents, but the one that I created based on the ScrivQ template continues to hang even with the default formats.

I assigned the default Section format to all the documents in the project. No item in the Files folder is checked for inclusion in compile.

Maybe there is some dirty cache? Where could I see to find it?

EDIT: I’ve created a new project, starting from the Generic non-fiction template. I imported the styles from the ScrivQ-based project, and then dragged the manuscript into the new project.

The compile commands are working fine. So, I guess there is something I scrambled in the ScrivQ template in my project. But everything is unchecked, so I can’t guess what it is. Maybe there is a way to reset a template?

EDIT 2: I’ve created a new, empty project from the ScrivQ template, and after having imported the styles I’ve dragged there the old manuscript. This should serve as a template reset. Alas, still any attempt of compiling hangs Scrivener.

EDIT 3: After letting compiling rung for some long minutes, this time it could end. Subsequent attempts to compile to web were very fast, but resulted in the following error:

--> Running Command: quarto render "/Users/paolot/Documents/Programmazione/Markdown/out files/Pa5X v1.2.0 User Manual English in Markdown.qmd"
e[91mERROR: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key (_extensions/bcdavasconcelos/citetools/_extension.yml, 20:7)
20: e[34mformat:e[91m
         ~~e[39m
waiting for the process to end

No file was created, apart for the intermediate .qmd and .yml files, plus an _extensions folder. Trying to render them with Visual Studio Code reported the same error.

Paolo

Hi Paolo,

  • you’ll see that the project uses Styles everywhere, so it does use rich text;
  • links have to be written in markdown style for them to appear in the compiled document [text](link);
  • DO NOT check the Convert rich text to markdown option as this would cause many errors.
  • Documents of the Section Type Standalone File will become a new file.

Page breaks are for PDF and DOCX outputs. This has nothing to do with ScrivQ. If you create a Quarto document and render it to HTML, you’ll see that page breaks have no effect.

Are you picking the desired format in the Compile panel?

  • Bear in mind that, you MUST compile to Multimarkdown, but the output will be of the chosen kind (PDF, DOCX, HTML, or all of them).
  • The dry-run option will only create the files, but will not run Quarto.

Which ScrivQ are you using? Have you tried the latest one from Github?

Hi Bernardo, thank you for your answer.

The ScrivQ template I’m using is dated 29th or August, so it should be the latest one (the ‘Trio’ version).

When compiling, I choose Markdown > ScrivQ HTML or PDF.

I’ve now tried with the Standalone File section type where I want a document to be a separate HTML file, but it seems I still get a single HTML file. But since I see there are other documents missing, maybe I must experiment a bit more to understand how it works.

I deactivated the Convert rich text to markdown option, but then there is no longer paragraph break. I didn’t end paragraphs with a double carriage return, but went on writing as in an ordinary word processor, with a single carriage return at the end of the paragraph. Is this the wrong way?

Going to bed. I’ll continue trying tomorrow.

Paolo

You could optionally leave an empty line, or use the Body style, just like you would in Microsoft Word.

When you look in Finder, do you see a new file there? The purpose is to turn that document into a new file. That alone means nothing to Quarto unless you also add that path to this file to the project you are rendering.

I use the feature to split the document to generate bibliographies and other support files. But the text itself is just one single file. if you want a project with several files for chapters, that can be done, but it requires some setting up.

Does this help?

I see that the text that I marked with a Body style is indeed considered as a separate paragraph, even without the double carriage return.

The text marked with a Safety Head and a Safety Body style is not (even if these styles have been added to the compile format). Is the Body style explicitly interpreted by the script as a paragraph, while other styles are not?

Yes, there is a single HTML file, together with other files (Quarto.log, a .qmd file, the _quarto.yml file, and the _extensions and [project_name_files folders).

What I was hoping was that ScrivQ could split the project into separate .md files. These are needed for Quarto to create a website made of separate HTML pages, and not a single HTML page.

Did I understand wrongly, when I believed this could be possible with ScrivQ?

Paolo

I decided to start from a clean project. I create a new one from the ScrivQ template, and delete all the content from the Manuscript section.

I then created two simple documents, to which I assigned the “Standalone File” section type.

Alas, compiling to ScrivQ HTML didn’t split them into separate HTML pages that could be used in a Quarte website. This is the Compile dialog:

These are the generated files:

image

This is the result in a web browser:

The .qmd file contains this code:

<!-- begin_file: "" -->
This is the first one.

<!-- end_file: "" -->


<!-- begin_file: "" -->
And this is the second one.

<!-- end_file: "" -->

Paolo

Paolo, the name of the Standalone file should go in the ID field. You can optionally write the name of the file with the extension, or use the Extension custom metadata field to select an extension (leave it empty if you decide to write it down with the filename).

You can see this clearly in action here:

Bernardo, thank you very much for you help! Do you mind if we continue to discuss here, to offer a guide to others that might meet my same problems? As I say, I’m a bit slow at grabbing these things, but maybe I can be used as a general test for the average user.

I’ve added the ID names to my project’s documents:

However, when compiling as ScrivQ HTML, I continue not to see three separate .qmd files. This is what I get:

image

The HTML file seen in the browser is an empty shell. I don’t see a website, but just that unique HTML file.

What else could I try, having missed to configure it?

Paolo

Could you include a screen capture of the metadata panel of the first-document.qmd?

Also, see Quarto - Book Structure

@ptram, I just noticed that you are trying to nest files. That is not allowed.

If you think about it, how should nested files behave? Should the overarching file also include the inner documents (in which case we would have part of the text duplicated) or leave it out (in which case they would be exported as two, not nested, but contiguous files)? Either solution would involve changes to the script. So, at the moment, you can’t nest them.

Sure, here it is. The other documents have a similar content (with different ID names):

Considering that I’m dealing with very long and articulate projects, nesting is a necessity for me. If I understand correctly how books and websites are structured in Quarto, nesting is allowed by the specs. All considered, the Quarto website itself is made of nested pages.

I also wonder about your sample text/instructions included in the template. Aren’t they nested files?

I understand that how to deal with a structure is not easy. In an ideal world, the script should be able to replicate the Scrivener project’s Binder in the index of the Quarto project.

A method that I would like even more is to be able to mark a document as a Standalone File, and make all the documents included under its level in the same HTML page. This would allow much flexibility, that can become necessary in a very articulate project with slightly different ways of articulating content.

In any case, I’m still doing something wrong. I’ve flattened my project structure in the Binder, deleted all the previously generated files, and now the script generates three separate .qmd files. Yet, the resulting HTML file (not a web site) is only an empty shell. If you like, you can see it in this archive.

Paolo

Bernardo, I don’t know if you have already seen how Ioa has tried to solve the issue of splitting a compiled file by way of manually inserted markers. His script has nothing of the complexity of ScrivQ or Scrivomatiq, but it is a little elegant script that might offer a solution to the above question:

Compiling to LaTeX one file per section

Paolo

Paolo, I believe you are trying to export a Quarto Website (not a Quarto Book, which is not the same thing). Apart from this, two things come to mind right now.

Files can only be nested under folders

This does not mean nesting Standalone File under Standalone File. Right now, you are conflating different things that should not be confused. You can nest sections, elements, metadata, and so on, under Standalone File, that is how it should work.

-- Quarto (yml)
---- Parameter
---- Parameter
-- File (qmd)
---- Section
------ Amsthm Theorem
------ Text
---- Section
------ Text
-- File (qmd)
---- Section
------ Text

Nesting files is illogical, I think,l and this has nothing to do with Quarto specifications. You can only nest files under folders in the system. If you tell the script to create this, then what should it do? It can’t do anything.

-- File
---- File (?!)

Single-page HTML Book vs Website

Even a Quarto book with a single text file requires many many additional files, such as bibliographies, lua filters, yaml configuration files, and so on. ScrivQ currently is perfect for this type of project. I think there is very little to gain from splitting the text itself into several parts (save for a Quarto Website or Blog). Be that as it may, what you are trying to do can be done, that is, exporting a Book/Website made of several files, but only with an overhead as they are more complex in nature. You will have to include in the frontmatter the necessary parameters with the path to the files that make up the Book/Website (required by the Quarto specs).

Could the script try to recreate the binder structure automatically? Probably. I started working on this, but (a.) it is far from trivial, and (b.) I don’t really have a use for this right now. The only gain I could see from this is for making Quarto Websites (which is different from the single-page HTML book).

Hope this helps.

I confirm. I admit I don’t even know what a book published as an HTML page is for. All my university papers have been made with traditional tools, printed and bound.

Yes, but they are allowed by Scrivener. It has a logic, in that a Scrivener project is nested by nature, and not just a container of equal-level sections. A top-level section contains middle-level ones, that can then be split into other lower-level ones. Part, chapter, section. And you can go on, by splitting a section into separate units, like paragraphs or blocks.

However, I now changed the top-level file to a folder. Either marking only this folder as Standalone File, or all the folder and files in it as this type of section, I continue to get an empty HTML file when compiling as HTML.

I suspect we are meaning different things when thinking to split files. I can’t even figure the structure and internal articulation of the above mentioned HTML book. No wonder I continue to try to do something that I can’t achieve.

I’m very curious to see how ScrivQ will evolve, when you can finally also explicitly include the website output format.

Paolo