Publishing your notes as a website

EtherPK turns a chosen set of your documents into a website: plain HTML files in a folder on your computer, ready for GitHub Pages, Cloudflare, Netlify or any host that serves files. Nothing is hosted by EtherPK, and nothing is published unless you say so, document by document.

Works in every browser. Publishing straight into a folder needs a Chromium-based desktop browser (Chrome, Edge, Brave, Arc), the same as a Local Mirror. Every browser can download the site as a zip.

Quick start

Settings → Publish → New publication. Name it (Docs), keep the suggested id (docs), pick Documentation or Blog, and choose whether it takes every public document or only those that name it. Create and open writes a page for it and opens the page.
Mark documents public. Right-click a document's tab → Publish… → tick Public and the publication. Do this for each page you want on the site.
Write the navigation. The publication page's outline is the site's menu: - [[Welcome]], - [[Guide]], one bullet per entry, nested bullets for sub-entries.
Publish. Back in Settings → Publish (or Alt+P), Choose folder… then Publish to folder; or Download zip. Open index.html in the folder to see the site.
Put it online. Push the folder to GitHub, run npx wrangler deploy, or drag it onto Netlify: Hosting A Published Site has the steps for each.

From then on it is edit, Alt+Shift+P to publish again, push.

The three things involved

A public document. A document is only ever published if its frontmatter says public: true. Right-click a document's tab and choose Publish… to set it; you never have to type it. A protected document is never published, whatever its frontmatter says.
A publication. A named set of public documents rendered as one site: documentation from some pages, a blog from the journal, a few others. A graph can have several. Each is an ordinary page in your graph whose frontmatter holds its settings and whose outline is the site's navigation. Settings → Publish → New publication writes it for you.
A theme. How the site looks. Two come with EtherPK, etherpk-docs and etherpk-blog; you can copy one into your graph and change anything about it, or point a publication at a theme on the web. See Theming A Published Site.

The publication page

New publication writes a page like this one and opens it. The frontmatter is the settings, the outline is the navigation:

---
title: Docs Site
publication:
  id: docs
  kind: docs
  selection: named
  home: Welcome
  url: https://docs.example.com
---
- [[Welcome]]
- [[Guide]]
  - [[[[Guide]] Advanced]]
- Reference
  - [[Physics]]
- [Source](https://github.com/you/project)

Setting	Meaning
`id`	What documents name in `publications: [docs]`. Lower-case letters, digits and hyphens; fixed once documents use it.
`kind`	`docs` (a sidebar of the outline, a table of contents per page) or `blog` (dated documents newest first, the feed). Decides which themes fit.
`selection`	`named`: only documents that list this id under `publications`. `all-public`: every public document in the graph.
`home`	The document whose content is the front page (`index.html`). Without one the front page lists the published pages. It must itself be public and in the publication.
`url`	The site's address, needed for the sitemap and the feed.
`theme`, `includes`	The look, and the pages that fill its slots. Set from Settings → Publish; see below.

In the outline, a bullet that is a wikilink is a menu entry, a nested bullet a sub-entry, a plain-text bullet with children a group, a heading a group too, and a markdown link an external entry. An entry that names a document not in the publication is left out and the report says so. Without an outline the site lists the pages alphabetically. When the publication holds journal entries a Journal entry is added, pointing at the archive.

The page itself is never published. Because it is a page, the publication travels with the graph: every member of a shared graph sees the same publications, and an export or a Local Mirror carries them.

Choosing what is published

Right-click any document's tab and choose Publish…. Tick Public and the publications the document belongs to; ticking a publication turns Public on as well. A publication that takes every public document shows as ticked and cannot be unticked there.

Unticking Public withdraws the document from every site at once. The dialog says when a document is public but in no publication, and Settings → Publish lists all such documents.

Writing the keys yourself works too:

---
title: Guide
public: true
publications: [docs, blog]
---

A page's address

A page's address on the site comes from its name: Quantum Mechanics becomes quantum-mechanics.html, and a scoped concept like [[Docs]] Privacy Policy becomes docs-privacy-policy.html. To choose one instead, add slug: to the page's frontmatter:

---
title: "[[Docs]] Privacy Policy"
public: true
publications: [docs]
slug: privacy-policy
---

It is normalised the same way (lower case, spaces to hyphens), a page that asks for one keeps it over a page whose address was merely derived, two pages asking for the same address get a suffix and a warning in the report, and the home page is always index.html.

Publishing

In Settings → Publish (Alt+P), each publication is a card.

Settings. Theme, home page, kind, which documents, site address and the include slots are edited together and written to the publication page with Save changes; Discard puts them back. Under a field that names a page, the help text says when that page would not be on the site (it does not exist yet, is not public, does not name this publication, is protected), and a panel above Save changes spells out the fix for this publication's selection. A publish always uses the saved settings.

Output.

Publish to folder, once you have chosen one with Choose folder…. The folder is remembered on this device. Every publish rewrites the site into it, removes files it no longer produces, and leaves your own files (CNAME, robots.txt, anything else you add) alone. Open index.html in a browser to check it; navigation and search work from disk.
Download zip: the whole site as one file, on any browser.

The report. A publish shows its progress in the corner and finishes with a report: what was published, what was left out and why (not public, protected, in another publication), links that point at pages not on the site, missing images, and anything the theme loads from elsewhere. Show report on the finished notification opens it under the publication, even after you've closed Settings; it stays there for the session.

Keyboard. Settings reopens on the tab you were last on, so a run of edits doesn't start from General every time, and two shortcuts cover the loop:

Alt+P opens Settings on the Publish tab.
Alt+Shift+P publishes again: the publication you last published from this device (or the graph's only one) into its folder, with no dialog. If no folder is chosen yet it opens the Publish tab and says so.

Putting the site online

The folder is plain files and needs no build step anywhere. It comes seeded with a GitHub Actions workflow and a Cloudflare wrangler.jsonc, and Netlify takes the folder as it is. Hosting A Published Site walks through GitHub Pages, Cloudflare, Netlify, GitLab Pages, Vercel, S3 and your own server, with the commands for each.

A theme has slots you can fill from pages in your graph, without touching the theme: head (analytics, fonts), logo (the icon before the site title; the EtherPK one otherwise), header, footer, before-content, after-content, scripts and styles. In Settings → Publish, open a publication's Includes, name a page for a slot and save. The page is written like any other, marked public like any other, and its wikilinks work:

© {{site.year}} · [[About]] · [[Privacy Policy]]

A head include page holding a <script> tag adds a tracking script; a styles include page whose body is a ```css fence appends that CSS to the theme's stylesheet.

An include page is content that reaches your site, so it follows the same rule as every other page: it must be Public and, unless the publication takes every public document, name the publication (right-click its tab → Publish…, or public: true and publications: [docs] in its frontmatter). Until it does, the theme's own version of that slot is used and the report says which key is missing. Once named as an include it is a snippet, not a page: it fills its slot and is never published as a page of its own, so site-footer.html never appears in search or the sitemap. A protected page cannot fill a slot.

Changing the look

In Settings → Publish, a publication's Theme picks a bundled theme, a theme copied into this graph, or one at a url. Customise theme… copies the current theme into the graph and opens the Theme editor, where each file of the theme (its templates, stylesheet and search script) can be edited and saved; the next publish uses it, and every member sees the same theme. Preview in the editor renders a publication that uses the theme with your unsaved edits, page by page, so you see a change before saving it; with no such publication yet it shows a sample site. Open in new tab shows the same preview as a page of its own, for testing at full size or with the browser's phone emulation. On a phone the bundled documentation theme keeps its navigation in a drawer behind the menu button at the top right.

Themes are text only, they never run inside EtherPK, and they travel with the graph like any other content. To write one from scratch, see Theming A Published Site.

What is never published

A document without public: true.
A protected document, even with public: true. Its title never appears on the site either.
A publication's own page, and any page named as an include (it fills its slot instead).
Anything a published document links to that is not itself on the site: the link is kept, styled as missing, and points at the site's "not published" page. Search, the feed, the sitemap and every "linked references" list are built from the published documents alone.

Maths, diagrams and code

Maths is typeset when you publish, and the site carries the fonts it needs. Mermaid diagrams are drawn when you publish, from the browser, so the site shows them as images and loads no script for them. Code is highlighted with the same languages the editor knows. The site loads nothing from the internet unless a theme or an include of yours adds it, and the report lists anything that does.

Publishing Your Notes As A Website