Skip to content

HTML pages (beta)

SharePoint can render an .html file in the Site Pages library as a page. With the html page mode, Doctor publishes every markdown file as one of those: a complete HTML document with its own design, instead of a modern page with Markdown web parts.

{
"pageMode": "html"
}

Or for a single run: doctor publish --pageMode html.

Every page goes through the same markdown pipeline as a Markdown web part, so a page reads the same in either mode:

  • the markdown syntax, including the extended syntax
  • highlighted code blocks, in the markdown.theme you configured
  • the shortcodes: callouts, icons, the table of contents, Mermaid diagrams and your own shortcodes. In this mode they do not need markdown.allowHtml, as the page is HTML anyway.
  • the partials, including the automatic header and footer
  • links between your pages, which point at the .html pages
  • the page title and description, which become the page’s title, its description column and the banner at the top of the page
  • page metadata, written to the columns of the Site Pages library
  • draft, which leaves the page unpublished
  • homepage: true, which makes the HTML page the site’s homepage
  • navigation, change detection and removeDeleted, which work as they do for modern pages

SharePoint shows an HTML page in a sandbox. Inline styles, scripts and SVG work, but the page cannot load anything from elsewhere: no stylesheets or scripts from a URL, no fetch calls, and images only when they are inside the page. SharePoint documents these rules on your tenant at https://<tenant>.sharepoint.com/_html. Doctor therefore puts everything a page needs inside the page itself:

Content In an HTML page
Images in your sources Embedded in the page. Nothing is uploaded to the asset library.
Images from other sites Downloaded while publishing and embedded. If the download fails, the image stays a link, and Doctor warns that it will not show. When the image changes at the same address, its pages are published again on the next run.
Images on your own SharePoint Read with the access Doctor publishes with, and embedded.
Mermaid diagrams Drawn while publishing, with the Mermaid version Doctor ships, and placed in the page as SVG. Diagram types that need a browser to draw, like C4Context and block-beta, cannot be drawn this way, and stay on the page as their source; Doctor warns about them.
Styles One stylesheet in the page.

When a page still contains something the sandbox blocks, Doctor warns about it during the publish. That can come from a custom shortcode, a partial or a custom template, for example an external <script src>.

SharePoint only opens a link in an HTML page when it goes to your own tenant’s SharePoint (its sites and OneDrive) or one of a few Microsoft addresses. A link to any other website, such as GitHub or your company’s public site, does nothing when it is clicked. Doctor lists those links for every page during the publish, so you can decide how to deal with them; links to your other pages and anchors within a page work.

Embedded images make a page bigger: a page is about as large as its images together. Keep large screenshots compressed.

Every page gets a clean default design: a banner with the page title and description, and a content column with styled code blocks, tables, quotes and callouts.

The column is 1200px wide, so reference tables and code have room. Running text stays at 800px, a line length that reads comfortably. A table is as wide as its content, up to the column, and its text wraps. Long words in a table, such as option names, paths and addresses, wrap at their dots and slashes. Only a table that still does not fit, with many columns, scrolls sideways.

A table of contents with position="right" sits beside the column when the window is at least 1400px wide. The column then gives up the room the table of contents needs.

The banner follows the page’s header front matter:

  • header.image shows the image behind the title, with header.altText as its description
  • header.layout: NoImage or ColorBlock keeps the plain banner
  • header.textAlignment: Center centres the title
  • header.type: None leaves the banner out

To restyle the pages, point html.styles to a CSS file. It is added after the default styles, so it wins. The design is built on CSS custom properties, so a few lines are often enough to rebrand it:

{
"pageMode": "html",
"html": {
"styles": "./theme/brand.css"
}
}
:root {
--doctor-accent: #6b2c91; /* links, the banner and the info callout */
--doctor-accent-strong: #3d1a54; /* the dark end of the banner gradient */
--doctor-font: Georgia, serif;
--doctor-width: 1400px; /* the content column: tables, code and diagrams */
--doctor-prose-width: 900px; /* running text, or none for the whole column */
}

The other properties are --doctor-text, --doctor-muted, --doctor-border, --doctor-surface, --doctor-background, --doctor-radius and --doctor-mono.

For full control over the page, point html.template to an HTML file of your own:

{
"pageMode": "html",
"html": {
"template": "./theme/layout.html"
}
}

The template is filled in with these placeholders:

Placeholder Contains
{{ title }} The page title
{{ description }} The page description, or nothing
{{ lang }} The page language: the language of the site, such as nl-nl
{{ styles }} The default styles, followed by your html.styles
{{ header }} The banner, as described above
{{ content }} The rendered markdown. Required: a template without it fails the publish.
<!DOCTYPE html>
<html lang="{{ lang }}">
<head>
<meta charset="utf-8" />
<title>{{ title }}</title>
<style>{{ styles }}</style>
</head>
<body>
{{ header }}
<main class="doctor-page">
<article class="doctor-content">{{ content }}</article>
</main>
</body>
</html>

Keep the doctor-page and doctor-content classes on the wrappers to keep the default styles for the content. Changing the template or the styles file publishes every page again.

As every page is a complete HTML file, you can look at your site without opening SharePoint. Publish with --outputFolder, and Doctor writes every page to that folder as it publishes it:

Terminal window
doctor publish --pageMode html --outputFolder ./preview

Open any .html file from the folder in your browser. Links between pages point to the pages on SharePoint.

In the html page mode, page URLs end in .html instead of .aspx. A slug in your front matter that ends in .aspx is turned into the .html page with the same name, so you do not have to change your sources.

The modern pages of the old mode are not changed. Doctor publishes the HTML pages next to them, and the modern pages count as deleted pages. To recycle them in the same run, use --removeDeleted --confirm. Switching modes publishes every page again, as the page mode is part of the publish settings.

  • Web part shortcodes. An HTML page holds no web parts, so a page that uses a web part shortcode fails with an error.
  • Multilingual sites. SharePoint creates translations from modern pages only. A publish with multilingual.enableTranslations and the html page mode stops before it changes anything.
  • Page templates, layout and comments. These are modern page features. They do nothing for an HTML page.

Known issue: moving between HTML pages in the site navigation

Section titled “Known issue: moving between HTML pages in the site navigation”

In the current SharePoint preview, the site navigation does not load an HTML page when you come from another HTML page: the address changes, but the previous page stays on screen. Reloading the browser shows the right page. This is a bug in SharePoint’s HTML page viewer, not in the navigation Doctor creates — the menu items point straight at the pages. Links inside your pages, such as a navigation partial, are not affected.

Visitors