SharePoint
Important
The website can only be hosted on SharePoint Online if you don't use Microsoft Defender for Cloud Apps or any other 3rd party solution which alters your URLs. If MCAS (Microsoft Cloud App Security) is in use, the nav bar can't be loaded because of CORS. In this case, the browser tries to fetch the toc.json from https://yourtenantdomain.sharepoint.com while the webpage is served on https://yourtenantdomain.sharepoint.com.mcas.ms and thus the access is blocked by CORS. If you're a Microsoft Defender for Cloud Apps customer, consider deploying your site to Azure or another web server and only allow users from your tenant to log in.
There is a PowerShell script which does everything that needs to be done for the site to run on SharePoint Online. This article explains what settings are configured by the script.
Note
Make sure that you've installed the necessary prerequisites as explained in this article.
Understand What the Script Does
SharePoint Custom Scripts
By default, custom scripts are disabled in SharePoint Online. The script will enable custom scripts for the selected site only.
New Document Library
The script will create a new Document Library in the specified site. The name of the new Document Library will be the same as the -AppTitle you set when you ran .\Setup\Initialize-AwesomeDocFx.ps1. The website will be uploaded to the root of the new Document Library.
Convert HTML to ASPX
Even when custom scripts (this also mmeans custom websites including CSS and JavaScript) are enabled on SharePoint, only *.aspx files are supported. All *.html files need to be renamed to *.aspx.
Note
More info about this can be found here.
This also means that all references to *.html files in all HTML and JSON files of the built site need to be updated as well. Since this would be a lot of manual work every time the site is updated, I created a PowerShell script for that as well.
Bing Chat describes ASPX like this:
"An ASPX file is an Active Server Page Extended file that is designed for Microsoft’s ASP.NET framework. It is a web page that contains HTML, CSS, JavaScript, and server-side scripts that are processed by a web server before being sent to a user’s web browser."
Upload Files to SharePoint
You will need to log in to SharePoint when you run the script. If you've never used the PnP.PowerShell module before, you might need to register an Azure AD App and grant consent first.
Register-PnPManagementShellAccess
When you run the script for the first time, all website files will be uploaded because there are no files on SharePoint yet.
Every time you update your site and run the script again, the already existing .\Docs\_site directory will be renamed to .\Docs\_site_last_build. The newly built files will be generated in .\Docs\_site again. The script will then comapre the file hashes of each file and only upload new or changed files. When both directories already exist (when the script has ran two or more times already), the .\Docs\_site_last_build directory will be deleted before the current .\Docs\_site directory is renamed to .\Docs\_site_last_build. There will only ever be two versions/directories of your site, the current and the previously built one.
Run the Script
To build your site and upload it to SharePoint, run the script like this.
. .\Build\BuildDocFxForSPO.ps1
Warning
When you use the BuildDocFxForSPO.ps1 script, the original HTML files generated by DocFx are overwritten and the site can't be hosted on any webserver other than SharePoint Online.