Have a pre-render script that isn't running

[dweng0]

Description

The problem

Pre-render lua script is not running.
Hey guys, here's my problem, i have a very basic lua script that at the moment is just a "hello world" that is supposed to create an output.txt file and inject "hello world". However, when i run quarto render template.qmd it doesn't run
however if i run quarto run _extensions/qreact/find-react-components.lua it works as expected. Is there some condition where pre render doesn't always execute its scripts?
EDIT: I forgot to add, it is defined in the extension yml under pre-render here

What I am trying to achieve

I'm looking at the feasibility of creating an extention that injects React components using a custom extension. You can find it here

It essentially follows the process defined in the documentation to create a custom format

The idea being that

A pre-render script is used to look for a React shortcode, in the md/qmd, replacing the shortcode to be just a div with a unique id for injecting the react component later. Then creating a list of components to "render" with their corresponding div ids, and saving the list to a tmp file,

A include-header script that inject the correct React dependencies (react.min ect)

and another include-header that reads through the tmp file we created earlier, finding the user's components and essentially dumping them in a header script. then for each one, injecting div id to the ReactDOM.render call. EG:

ReactDOM.render(
  React.createElement(MyComponent),
  document.getElementById('correspondingcomponentid')
);

[mcanouil]

Why are you using a pre-render script?

Take a look at the following extensions which inject HTML/CSS when encountering a shortcode using Lua filter.

• https://github.com/mcanouil/quarto-iconify
• https://github.com/mcanouil/quarto-preview-colour
• https://github.com/quarto-ext/fontawesome

I suggest you go through Quarto documentation on creating extensions, see https://quarto.org/docs/extensions/filters.html and https://quarto.org/docs/extensions/shortcodes.html.

[dweng0]

I have found the answer, but would like to give context in case people are having the same issue as me.

So in order to achieve what I wanted, I created an extension following the documentation:

quarto create extension format:html

this sets up the project for you. then in my _extension.yml, i had some scripts, one was a hello world that just generated a .txt file and printed hello world. But the yml file looked like this:

title: Qreact
author: Jay Martin
version: 0.0.1
quarto-required: ">=1.3.0"
contributes:
  project:
    project:
      type: website
      pre-render:
        - find-react-components.lua
    format: react-html <-- make a note of this
  formats:
    html:
      include-in-header:
      - react-scripts.html
      

Where the pre-render is a simple lua script that creates the file i mentioned above.

But whenever i ran quarto render template.qmd to test it. It just wasn't working. this was really baffling me, as quarto run /path/to/script/ would work!

Anyway, long story short, it turns out that because the project is an extension and not a "proper" project, it's not running those pre-render scripts.

Although the above statement is not quite true, because the include-in-header script would run perfectly fine.

The fix, was to run quarto create-project in the root, which generates a _quarto.yml file and then add the following, such that it matches the format of the extension:

project:
  type: "qreact"

Notes for the Quarto team

Improved documentation

This quirk should be mentioned in the documentation (if it is mentioned, it should really be around the "creating an extension" section.), If you're wondering what it should say. It should simply be. Your extension will only work when hooked up to a project not when you run quarto render/preview on template.qmd. Although, this is not quite true, because include-in-header stuff did work...

Improved debugging

Perhaps when quarto render/runs, some flag for debugging would help, whereby while it is compiling it says what its doing. For example "extension.yml found".... "looking in pre-render list".... "scripts found: find-react-components.lua". Stuff to make debugginq quarto render/preview scripts easier.

[mcanouil]

Pre-render and post-render scripts are a project level features (this is why the page title is "Project Scripts", see https://quarto.org/docs/projects/scripts.html), thus the requirement to be in such setup.
Here your extension is defining two things: a project template and an html format template which are not tied together in the extension, so you have to use your extension to setup the project (thus have access to pre-render) then use the extension to have the html format, which requires the project in which it is used to be the one from the extension.
This setup is not really straightforward if I may.
I don't see (I might be missing something) why you need to have a pre-render and not a filter which can be easily integrated without your html format.
I really think the issue is the structure of your extension, not a documentation issue.

Regarding debugging, did you look at https://quarto.org/docs/troubleshooting/index.html#advanced?

[dweng0]

Hey @mcanouil

The reasoning for making use of the pre-render scripts is/was to allow for importing of "stuff" to enrich the react components, for example if i wanted to use a third prty to handle graphql, I would import it and then use it. Traditionally a bundler would worry about importing and making the code available. Bundlers typically run before runtime and so I made the assumption that this might need to be the case here.

I have created a very basic extension that can run react components and make use of React's built in reactivity (useEffects, useState ect). But I invisage there being problems trying to "import" stuff because "import" is not something that runs natively in a browser, so the imported stuff would need to be bundled with the components before or "Just in Time" for the browser

I am open to suggestions if there is something I may have overlooked

[mcanouil]

Thanks for the explanation.

Likely what you did is a good way to go, but contrary to other extensions, in your case your users (and yourself) need to first use the extension to create a project, then use the extension to create a document based on the format.
And you have to do that in that order, for your complete workflow to work as intended.