File list and order for quarto publish confluence

[ghost]

Description

We are using Quarto extensively for rendering multi-file documents as both pdf and html and we'd like to publish them to our Confluence site. I am using Quarto 1.3.450 on a Mac.

In a normal quarto render, the list and order of files is in _quarto.yml in the book.chapters tag. I can't get the obvious thing to work in a quarto publish confluence command.

If I try a quarto create project and specify confluence as the type, I get a _quarto.yml file that doesn't have a file list. The Publishing Projects section of the Quarto Confluence page talks about the directory hierarchy and then shows what the hierarchy looks like after publishing to Confluence.

I originally assumed that it was just publishing the files, at any level, in alphabetical order, but the directory hierarchy has project-roadmap.qmd and team-members.qmd in the hierarchy, but the published output shows them in the opposite order.

So the question is, for quarto publish confluence, where does the file list come from, and how is the order in the published output determined.

[dragonstyle]

I believe that currently the pages are sorted within folders in order of their title metadata (not the file name) - there isn't a way to explicitly control order right now. This matches my limited testing (though I didn't dig back into the code to discover whether we're specifying this while publishing or whether Confluence is doing this itself) - does that match what you're seeing?

[ghost]

Assuming that you mean the title meta data in each .qmd file, I don't think that's what being used for publishing order. As an example, I did a quarto create project and specified confluence as the type. That gave me the prototype files. I then copied project-roadmap.qmd to team-members.qmd and change the title tag in the latter file to "Team Members". The default title tag in project-roadmap.qmd is "Project Roadmap" and when I did the publish, the progress bar shows that team-members.qmd is processed before project-roadmap.qmd, which is the same behaivor shown the the Quarto Confluence page.

[dragonstyle]

I'm actually address the order in which the links appear in the navigation of the published site (which does appear to be title based). But you're right, that definitely does not control the actual order in which we render or publish the files. I would be surprised if the order in which the files are published is what determines the structure of the tree in confluence...

[ghost]

As far as I can tell, the "Rendering for publish:" output on the quarto publish confluence is exactly the order in which Confluence provides the navigation list. See my longer response, down below.

[mcanouil]

This was discussed several times:

• Specify preferred document order to render #7298
• Control order of rendering #6944

[dragonstyle]

This isn't quite the same thing, as it also has to do with the way that the files appear the sidebar navigation of the Confluence site (e.g. analagous to our website sidebar but currently with no real way to control it). It may be that we need to provide control outside of render order...

[mcanouil]

So confluence is really independent of how website/books work.
I thought they shared some structure.

(About sidebar ordering for reference: #7660)

[ghost]

For clarity, the render builds that we do use the book.chapters key in _quarto.yml to specify the file list and the order, and that all works correctly. But if I try to put anything into the _quarto.yml file other than what comes in with the quarto create project, the publish fails because it doesn't like the type: confluence or the book tag.

I can do scripts to hid things, so what I really need to know is how to specify the file list and the order, and how to get the format: confluence-html metadata in. I've got all of that in a profile, so I think it's just --profile confluence if I know how to do the file list.

[ghost]

Oh, and one other data point. I can successfully do a render with the html target, which uses the book.chapter list and the resulting side bar is in the right order.

[cderv]

Our doc is indeed not really clear on this point...
https://quarto.org/docs/publishing/confluence.html#collection-of-documents

then arrange your .qmd or .ipynb documents into whatever hierarchy you want to use for publishing

Not clear how... this will be ordered, of if order can be controlled.

Though not sure what confluence allows really as default, as it seems sorting and reordering is a confluence feature in interface, and spaces can have different configuration

[ghost]

Sure. This is the sidebar after the publish. 2024-01-09 is my test parent page URL.

But now that I look at it, note that the order in the Reports directory is reversed from the rendering for publish list. What can I use on the quarto command line to dump out the order in which files are sent to Confluence?

[ghost]

Is there a --verbose setting that I can give to the quarto publish confluence that logs what it's doing in detail, including the order in which the files are being sent to Confluence?

[dragonstyle]

You can get a lot (a lot) of publishing diagnostics using --log-level debug which may provide something helpful here...

[ghost]

I'll look at this when I get a chance, but I decided to give up on the file order and tell people that they have to drag the links around on the Confluence navigation pane. We already have the multi-file directory hierarchy in place for the render version, so I've moved back to trying to publish an actual project spec.

In doing that, I've found a couple of other unexpected glitches in the publishing flow:

• I can't put the project: confluence in a profile. It has to be in _quarto.yml (which kind of breaks a common metadata organization for render to pdf/html and publish to confluence).
• The cross file cross references don't seem to work in the publishing.

Should close this one and file a new issue for each of those?

And, by the way, thanks for the help.

[dragonstyle]

Totally understand! We'd appreciate it a lot if you could open issues for those two problems that you've run into (the more specifically you can provide a small / simple reproducible case, the more likely we'll be able to pinpoint the issue)- thank you!

[ghost]

Closing after better understanding what can be done with Quarto publishing to Confluence. Will open new discussions for the two specific problems that I found.