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 😊

[mcanouil]

SharePoint can display HTML pages, but those are quite limited in terms of JavaScript in it.
From experience, it's better to download the file rather than previewing inside SharePoint.
(SharePoint is basically OneDrive with few more features).

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.
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.

This is a terrible idea. "aspx" (ASP.NET) are not regular HTML files.
This is similar to asking Quarto to turn docx into zip to access the xml/xhtml files, etc. in it.
Very unlikely to happen.
Side note: Quarto is a command line interface which is not binded to R. quarto::quarto_render is an R function calling Quarto CLI.
If you want really to change the extension, set the output file with the targeted extension (again, that is a terrible idea to do that by default).

Regarding Docker images, what you are asking is not really doable. What about Julia? Other languages, etc. This means a very big image which basically is the opposite of what a Docker image should be.
This being said, Quarto builds Docker images focused on Quarto which you can use to build your own:

• https://github.com/orgs/quarto-dev/packages?repo_name=quarto-cli
  You can also use Docker images from the Rocker project: https://rocker-project.org/
  And you can use Devcontainer where you add features: https://containers.dev/features

[allefeld]

ASPX files are HTML files which contain additional instructions for server-side processing by ASP.NET. Therefore a pure HTML file is a special case of an ASPX file, one where the amount of server-side processing is 0.

Even if ideally pure HTML files should have the extension .html instead of .aspx, the fact is that the only way to properly serve an HTML file uploaded to OneDrive is to give it the extension .aspx. I have tested this, and it works even with external resources (*_files folder generated by Quarto), several linked files including Quarto website projects, and JS-based interactive elements.

By contrast, if an HTML file is uploaded to OneDrive with the extension .html, viewing it wraps the actual page in some superfluous extra decorations, and styles, links (including internal), and interactivity are broken.

Obviously OneDrive is not the ideal way to share Quarto-generated content, but for the many people like myself who are locked into an institutional MS-everything culture, it is a reasonable way to share internally in an access-controlled way.

I therefore second @ArthurAndrews's request to include the information summarized above about sharing via OneDrive in the Quarto documentation. It took me quite a bit of googling to figure this out – no need for that effort to be duplicated.

[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 !