Documentation for publishing Quarto to OneDrive/SharePoint, GitLab, and GitHub

[ArthurAndrews]

Description

I have been sharing Quarto documents and dashboards within my company using OneDrive/SharePoint and GitLab. It's a convenient way to share results securely and with some degree of automation. I recommend adding instructions to the Quarto documentation to share these capabilities with other users.

I can spell out the steps in a brief way. Please let me know if this isn't enough detail.

Publishing to OneDrive / SharePoint

Within the Microsoft ecosystem, a user can right click a folder or a file and "share." This will send a OneDrive link to file or folder to the recipients and grant them to the read/write permissions. This is integrated somewhat with SharePoint in that sharing a folder through this OneDrive mechanism will send them a link to a SharePoint folder. This is a great way to share files within the company with the user authentication / security that's simply built in.

Unfortunately, .html files won't be directly browsable through this method. Clicking an .html will instead download it. Luckily, there is a documented hack where simply renaming the file from .html to .aspx will create a browsable page. By renaming rendered Quarto files to .aspx, one can create a sharable and browsable link for specific recipients. I don't remember exactly when or how I learned this, but perhaps it was from this SO question:

https://stackoverflow.com/questions/49316205/how-can-i-create-a-self-contained-html-report-with-rmarkdown/59250591#59250591

This method can be extended to actually create a whole set of .aspx reports / dashboards that are linked together with relative hyperlinks to create a whole Quarto "website" in a lightweight way without git or web servers.

Perhaps this can be automated with quarto_render("file.qmd", "file.aspx"). I haven't tried it! I'd defer to the Quarto developers exactly how they suggest a user can accomplish this.

GitLab Pages

Both GitLab and GitHub have a Pages feature where a project can publish .html or simply host .html in the public/ folder. This is a more formal way to host content.

Publish .html: in this way, the project code actually renders the .html with CI/CD upon a pull request etc.
Host .html: or, the user can simply commit and push .html in the public folder.

Either way, this is another great way to share Quarto content. This is surely well-known to the Quarto developers, but some documentation or resources would be welcome.

There is a decent template for this sort of documentation here for Posit Connect. The context is different, but much of the code would be identical.

https://solutions.posit.co/operations/deploy-methods/ci-cd/gitlab-ci-cd/

Another possible step is for the Quarto developers to actually publish an official Quarto Docker image including R, Py, Quarto, and commonly-used html widgets like plotly, reactable, leaflet, etc. Perhaps this Dockerfile would be based on the excellent rocker project images with a few additional installations. Because the rocker images are Ubuntu based and Ubuntu simply comes with Python installed, these images are already a great template for anything involving R + Py.

This Docker image would jump start the integration of Quarto reporting with GitLab and GitHub for users.

Many thanks to the Quarto devs! It's an amazing tool and I happily use it every day.

[jimjam-slam]

The Quarto docs do have a Publishing section that includes fairly detailed instructions for GitHub Pages. There's also a section for other services. I hope those help!

Interested to learn that Quarto pages can run on SharePoint this way! I don't know too much about SharePoint 😊

[riziles]

I agree with @allefeld and @ArthurAndrews . I do this all the time and it works great. Been trying to convince everybody in my company to stop using Word!

[riziles]

It's even better with Sverto thanks to @jimjam-slam !

[Amglnbtr]

Sharepoint is no longer allowing custom scripts starting from 2024 H1 here. Opening uploaded .aspx file is now downloading instead of rendering, there appear to be temporary solution that involve MS 365 admin running shell script periodically, for general folks Sharepoint is no longer a viable publishing option, obviously my research is not exhaustive.

[jkkishore85]

I tried using aspx, but it didn't work for me. Instead, the following configuration in _quarto.yml worked fine:
`project:
type: website

format:
html:
self-contained: true`

I also wrote a tutorial about this on my website: https://jkkishore85.github.io/tutorials/2024-07-17-quartotutorial-sharepoint-01/

[mcanouil]

@jkkishore85 Don't use self-contained use embed-resources.
The former has been superseded a long time again by Pandoc and Quarto.

Additionally, using this option on a Book or Website can lead to unexpected behaviour and can break some components that are shared across the pages.

embed-resources is supposed to be used for single file documents.

[jarbet]

@ArthurAndrews I'm curious if your onedrive/sharepoint method still works, i.e. saving an .html report as .aspx and then right click > share and colleagues can click the share link to browse the rendered report? @Amglnbtr suggested that this appoach no longer works.. I will test this out later this week but curious if you have any updates.

[Steinthal]

It doesn't work any longer. Microsoft changed the behavior , and now files are only downloaded.

[ArthurAndrews]

@ArthurAndrews I'm curious if your onedrive/sharepoint method still works, i.e. saving an .html report as .aspx and then right click > share and colleagues can click the share link to browse the rendered report? @Amglnbtr suggested that this appoach no longer works.. I will test this out later this week but curious if you have any updates.

No, it doesn’t work. There is another option, although it is less convenient. You can share the folder containing the html file via OneDrive. Then, show your users how to sync that folder to Windows explorer. Via Explorer, they can visit the static web page. You can update the html and linked images and js files, and they will have access to the new updated version. They can bookmark it in their browser.

[mcanouil]

This method won't work for everything, for example, the table of content collapse/section highlight features require a webserver (http protocol), not file explorer (file protocol). Several other JavaScript-based features have the same requirement.

[jarbet]

Got it, thanks all. I will pursue other options for publishing but it would be great if it was possible to publish to SharePoint since a lot of companies use Microsoft's 365 platform.