Watching for knitr's child doc in Quarto Website and re-render when detecting changes

[GitHunter0]

Since the beginning (months ago), I'm having serious troubles in making Quarto render new/updated .qmd files for my Quarto websites.

For example, I change the content of a page (saved as .qmd) but Quarto does not detect it and keeps rendering the old version.

Sometimes Quarto does update the content as expected but it is unreliable, many times it does not work.

The only way I found to force Quarto to render the updated files was to delete the folders .quarto and _site.

However, it means I have to re-render everything every time...

Any help in finding a solution to this will be much appreciated.

Windows 10 pro
quarto 1.4.114
RStudio 2023.06.0 Build 421
R 4.2.1

[cderv]

Any help in finding a solution to this will be much appreciated.

Can you help us help you by providing a reproducible example ? Can you share your project as a Github repo maybe ?

We don't see this kind of issue with our quarto.org website which is built using latest pre-release so we believe there is no issue per-se in Quarto.

However, there could be something related to how your project is setup or how / where it is render. This is why we need more context, and an example that reproduce what you see.

Otherwise, it is hard to help, and really really difficult to know where to look to even start a debug.

Thank you

[GitHunter0]

For sure @cderv , I will try to build a very simple website that can replicate the issue. I will do it soon. Thanks a lot for the feedback.

[Lextuga007]

I think I may have the same problem but I thought it was related to a GitHub Actions but I have a few Quarto books and a website for the NHS-R Community which only seem to work if I use quarto publish gh-pages from the terminal and set the pages to "Deploy from branch" rather than "GitHub Actions" in GitHub. When I do that the page publishes and also quarto render shows the page locally.

You can see that the html page is in the gh-pages branch but isn't showing on the website side bar https://training.nhsrcommunity.com/.

I'm using:

Quarto CLI version 1.3.433 RStudio 2023.06.0+421 R version 4.3.1 (2023-06-16 ucrt) Windows 10 Pro

[cderv]

if I use quarto publish gh-pages from the terminal and set the pages to "Deploy from branch" rather than "GitHub Actions" in GitHub.

quarto publish gh-pages works with Github Pages deployed from branch, and not the new Custom action feature. To use the latter you would need to quarto render on CI and then use the right Github Action to publish.

How is your Github Pages configured in Github Settings ? it needs to be on Pages https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

I would say this is a config issue as your current gh-pages has no more CNAME https://github.com/nhs-r-community/NHSR-training/tree/gh-pages

To use quarto publish gh-pages and get CNAME, we still need to add a specific item in doc - see for now: https://github.com/quarto-dev/quarto-cli/issues/4941

[Lextuga007]

Thanks for the quick response! I've added the resources: - CNAME to the _quarto.yml and left the GitHub action to render and publish but it's still not showing in the website.

A screenshot of the GitHub Pages configuration:

[cderv]

How is your Github Pages configured in Github Settings ? it needs to be on Pages docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

Please do read the link I shared about configuration: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

You are not configured on the right Source

See also our doc about quarto publish gh-pages https://quarto.org/docs/publishing/github-pages.html#source-branch

[Lextuga007]

I was trying to get GitHub to update from the GitHub Actions rather than rely upon running it from a branch the the command line. It looks like the Quarto Publish action isn't triggering but does work as I got it to work by setting it off manually.

[cderv]

I was trying to get GitHub to update from the GitHub Actions rather than rely upon running it from a branch the the command line.

Not sure to get it correctly, but quarto publish can be run locally from your main branch, or in Github Actions as a command or though quarto-dev/quarto-actions/publish. quarto publish will do the rendering and then committing to gh-pages branch for you - you don't need to switch branch at any point.

It looks like the Quarto Publish action isn't triggering but does work as I got it to work by setting it off manually.

It seems your action is running correctly (https://github.com/nhs-r-community/NHSR-training/actions/runs/5489773021/jobs/10004350936) and site deploys.

I still believe there is no issue with Quarto or Quarto actions so we can keep discussing in https://github.com/nhs-r-community/NHSR-training directly - you can open an issue and ping me.

[Lextuga007]

Yes, I think you are right this isn't a Quarto issue as I thought - thanks for looking into it for me and hopefully this may help others 🙂

[GitHunter0]

Can you help us help you by providing a reproducible example ? Can you share your project as a Github repo maybe ?

I was able to create a Github repo reproducing the issue: https://github.com/GitHunter0/quarto_website_debug

Steps to reproduce the problem: (1) go to quarto folder and open quarto.Rproj in RStudio (2) Open index.qmd file and click on the button Render. It will open http://localhost:5000/index.html website page on the default browser (3) Go to the website and click on Text 1 page, which will direct to http://localhost:5000/tab_texts/text1.html. That page renders the content of the file quarto/texts/_text1.qmd (4) Now make any changes to _text1.qmd (5) You will see that those changes will not appear in the website. So, close Background Jobs tab and rerender by going to index.qmd and clicking in Render button (6) Again the changes will not be rendered. And as previously mentioned, the only way I found to force Quarto Website to display the updated content was to delete the folders .quarto and _site before rerendering it.

@cderv , I appreciate if you help me figure out this puzzle.

[mcanouil]

Files starting with . and _ are ignored by design as described in https://quarto.org/docs/projects/quarto-projects.html#render-targets.

So either, remove the prefix and add explicitly this file to the render targets.

Additionally, your "texts" is technically not even part of your site (no trace in the project yaml file and as include anywhere).

Also, it is preferable to use the include shortcode rather than knitr child argument to include Quarto documents as you loose Quarto features in the child document when running it as a knitr child. See https://quarto.org/docs/authoring/includes.html.

[cderv]

@GitHunter0 thanks for sharing the repo.

Here is my take on this to complete previous answer just above.

• I believe you added _ on your child document specifically for it to be ignored and used as a child document (and not to be rendered directly). That makes sense and I would not change that.

• Your texts folder is only the recipient for your child document so it makes sense for it not being added as part of the website in _quarto.yml

• However, you are using child = option from knitr and this will not currently behave as you expect by the watch feature from Quarto. Let me explain:

  • When you modify _text1.qmd, even if Quarto sees the change in this file, it won't re-rendered tab_text/text1.qmd because it has not changed and Quarto has not made a dependency between both file. This is because you are using child options from knitr and not Quarto specific feature.
  • If you are using include shortcode, then Quarto creates a dependency tree and will know that if included document is modified then the main document should be rendered.

So I would just follow the advice above and use

{{< include /texts/_text1.qmd >}}

inside your tab_texts/text1.qmd instead of knitr chunk

And as previously mentioned, the only way I found to force Quarto Website to display the updated content was to delete the folders .quarto and _site before rerendering it.

About this, by removing everything you are removing the already rendered information about the website, so indeed it will render from scratch everything and your modification will be taken into account.

Overall, the only thing we can do here in Quarto is: Can we make Quarto aware of a knitr's child document and so render the correct document when child change 🤔

I'll look into that...

[cderv]

Looking into how this works in our code base

• We watch out for detected resources like JS libraries or CSS files and in that case we auto reload the website. Not re-render of .qmd
• We watch out for .qmd files and re-render on change
• We watch out for extensions, filters and shortcodes and re-render on change
• We watch for configurations too

In your case, texts/_text1.qmd is considered as a resource (probably because you added it as such in _quarto.yml) so you only get a reload - but no re-render of the main document tab_texts/text1.qmd is expected.

I hope this clarifies the current behavior.

[GitHunter0]

Thanks a lot for the very thoughtful comments @cderv . Also thanks to @mcanouil .

Following both, I replaced the knitr child for the quarto include. I kept the child file name _text1. I was gladly able to solve the issue doing one more thing: adding both tab_texts and texts folders to the project resources. I upgraded the repo with the new version (v.02): https://github.com/GitHunter0/quarto_website_debug

I also tried that solution in my original website and it worked. However, for some reason the hooks for reloading the website are not working and I have to force the update via F5 in the browser (but it's a lesser issue and I also wasn't able to replicate it in a MWE).

As the workaround is currently sufficiently working, feel free to close the issue.

Lastly, as a side potential issue, Quarto is trying to run a cell even enclosed by <!-- --> comment delimiter. For instance, this is throwing the error No such file or directory:

<!--
```{r, child=if (TRUE) c('../texts/name_of_a_file_that_does_not_exist.qmd')}

-->

To avoid that, I had to add `#` like this:

[cderv]

Glad it works now !

adding both tab_texts and texts folders to the project resources.

I am surprised by that... 🤔 But maybe I am missing an internal thing.

Lastly, as a side potential issue, Quarto is trying to run a cell even enclosed by comment delimiter. For instance, this is throwing the error No such file or directory:

This is not a Quarto issue. It is a knitr limitation. Code chunk parsing happens on a line by line basis, and is not HTML context aware. This means HTML comment means nothing from knitr perspective.

To ignore some content you have two solutions

• Use chunk option (eval = FALSE and echo: FALSE)
• Or use the comment engine (https://yihui.org/en/2022/01/knitr-news/#the-new-engines-comment-verbatim-and-embed)

[danieltomasz]

@cderv will this be valid for quarto preview? I put include in my book project in index.md

# Preface {.unnumbered}

This is a Quarto book.

To learn more about Quarto books visit <https://quarto.org/docs/books>.

I put my stuff here to see if quarto rerender.

{{< include _foreword.qmd >}}

And I put have

# Foreword

I would like to thank the developers of

I start quarto preview

My change to the included file

# Foreword

I would like to thank the developers of Quarto. 

isn't reflected until I change aything in the index.qmd Is there any way to watch for changes in the included files? ( i create earlier a separate bug issuehttps://github.com/quarto-dev/quarto-cli/issues/6413 )

Edited:

Adding into _quarto.yml foreword as resource

resources: 
  - _foreword.qmd

is helping with html preview, but not pdf :(