Publish Settings

A publication is a page in your graph that defines a website. The site settings go in a publication: mapping in its frontmatter, and the outline below the frontmatter becomes the site menu. The page itself never appears on the site.

Because publications are pages, their settings and menus travel with the graph, and so do the publishing keys in your documents and any themes copied into it. Every member of a shared graph sees the same publications on every device, and a graph folder or a Local Mirror also holds them.

The publish destination, a folder or a GitHub repository, is not part of the graph. Each device keeps its own destination for each publication, so you set it up on each device. Your GitHub token is stored with your own settings and reaches your other devices when those settings sync to your account.

Settings > Publish has a form for the publication: mapping, with one card for each publication under Publications. Your changes on a card stay a draft until you select Save changes, which rewrites the whole mapping at once and leaves the other frontmatter keys alone. Discard puts the card back to the values on the page. Publishing always uses the saved settings, so save before you publish.

Select Edit page to edit the same settings on the publication page itself. A card with no unsaved changes shows the settings as they were on the page when you opened the tab or last saved.

To put a document on a site, add two keys to its own frontmatter: public: true, which gives your consent, and a publications list with the publication id. For a publication set to Every public document, public: true is enough. The Publish dialog writes both keys for you.

A publishing key left empty counts as not set and takes its default, so you can add a key to a page and fill it in later.

Publication settings

A publication page looks like this:

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

The New publication form sets title and id, and every other key has its own field on the card.

Key	Field	Default	What it does
title	Name	The page name	Name the publication page and the site.
id	Id	Required	Identify the publication in publications lists. Use lower-case letters, digits and hyphens.
kind	Kind	docs	Choose docs (Documentation) or blog (Blog). On a blog, dated documents are posts, newest first.
selection	Documents	named	Choose named (Those that name this publication) or all-public (Every public document).
home	Home page	None	Name the document whose content is the front page, index.html. Without one, a docs site's front page lists its pages, and a blog with the EtherPK Blog theme lists its latest posts.
url	Site address	None	Give the address of the site, starting with https:// or http://. Without it, the site gets no sitemap or feed.
theme	Theme	EtherPK Docs or EtherPK Blog, by kind	Pick a bundled theme, a theme in this graph, or a theme at a url (Theme url).
recent	Posts on the front page	10	Set how many posts a blog front page lists, as a whole number above zero.
includes	Includes	None	Name the page that fills each slot. See Include slots.

The card has no Id field, because documents name a publication by its id.

The home page and every include page reach the site, so each must be public, and in a publication that takes named documents, each must also name the publication. If the home page breaks these rules, the front page lists the published pages instead and the report shows a warning. If an include page breaks them, the theme fills the slot with its own content, and the report names the key missing from that page's frontmatter.

Because a publication page is never published, the home page and includes must name content pages. Protected pages are never published either. If a field names a page that would not reach the site, the card says why and how to fix it.

A publication page with an invalid value, or a journal entry with a publication: mapping, defines no publication until you fix it, so it has no card. The problem shows at the top of the tab, with a link to the page. Site address is not checked when you save, so an address that does not start with https:// or http:// makes the page invalid, and its card disappears until you fix it.

Site navigation

The outline on the publication page becomes the site menu:

• A bullet that holds only a wikilink is an entry for that page.
• A nested bullet is a sub-entry.
• A plain bullet with children, or a heading, is a group with no link. Any other bullet text is an entry with no link.
• A bullet that holds only a Markdown link is an outside link.

A page in the publication that the outline leaves out is still published, but it stays out of the menu while the outline has entries. If the outline is empty, the menu lists every page on a docs site, or every undated page on a blog. A blog also has posts.html, which lists every post by year. The menu shows it only when you add this bullet to the outline:

- [All posts](posts.html)

Include slots

An include puts the body of a page into a slot in the theme. Every bundled theme has these nine slots:

Slot	What the page does
head	Add markup inside <head>, such as analytics or fonts.
logo	Replace the logo before the site title.
favicon	Replace the browser tab icon, with one <link rel="icon"> tag.
header	Replace the site header.
before-content	Add a banner or notice above the content on every page.
after-content	Add an author note or comments below the content on every page.
footer	Fill the site footer.
scripts	Add scripts after the theme scripts.
styles	Append the first css fence in the page to the theme stylesheet.

Wikilinks in an include page resolve, and {{site.year}} becomes the year, as in this footer:

---
title: Site Footer
public: true
publications:
  - docs
---
© {{site.year}} [[Welcome]]

An include page fills a slot only in the publications that name it as an include. No publication in the graph publishes it as a page of its own, so it never shows up in search or the sitemap, even on a site set to Every public document.

Publish destination

Under Publish to on each card, choose A folder on this device or A GitHub repository. Setting up one replaces the other on this device. Download zip downloads the site as one zip. In a browser that cannot write to a folder, only the repository and the zip are available. The browsers that can write a folder are listed on Choosing Where To Store Your Notes.

Each publish writes the .html files at the top of its folder or branch, the search files, sitemap.xml, feed.xml, and the assets/, theme/, maps/ and pictures/ folders. It also deletes any file in those places that it did not write, so Choose folder… refuses a local graph folder, a Local Mirror folder, and any folder inside or containing one. A publish adds starter files such as README.md and wrangler.jsonc when they are missing and leaves them alone after that, and in AGENTS.md it rewrites only its own section. It never writes or deletes anything else, such as CNAME, robots.txt or .git/.

To publish to a repository, enter it as owner/name under Repository and a branch under Branch (main if you leave it empty), then select Save and check. Each publish makes one commit, and earlier versions of the site stay in the branch history, which might be public. See Hosting A Published Site for more information.

GitHub token

Enter your GitHub token in the GitHub section above the cards. The token is stored with your settings, so any code running in the EtherPK tab can read it, including extensions. Limit it to your site repositories and the Contents permission.

Publish report

When a publish finishes, the number of documents, the theme and any warnings appear under the card. Select Show report for the full report, which lists the documents left out and why, and the links to pages that are not on the site. Because the report names the documents the site leaves out, protected ones included, it is never written into the site, the zip or a commit.

Themes in this graph

Themes in this graph lists the themes copied into the graph, and Add theme copies one in. See Theming A Published Site for more information.

Document keys

A document can carry these keys in its frontmatter:

Key	Value	What it does
public	true	Give consent to publish the document. A quoted "true" or yes does not count.
publications	A list of ids	Put the document in each publication listed. Write one id per line, or inline as [docs, blog]. A single id still needs a list.
slug	An address	Set an address for the page in place of the one derived from its name.
date	YYYY-MM-DD	Date the page. On a blog, a dated page is a post. Dated pages go into the feed.

---
title: Guide
public: true
publications:
  - docs
  - blog
---

A page's address is its name in lower case, with spaces and underscores turned into hyphens, other characters dropped and .html added. For example, [[Garden]] Notes becomes garden-notes.html. A journal entry uses its day as its address. See Titles Aliases And Frontmatter for more information.

Publish dialog

To open the Publish dialog, right-click a document tab and select Publish…. On a phone, long-press the document name.

The dialog has a Public checkbox and one checkbox for each publication that takes named documents. Ticking a publication also ticks Public, since no publication takes a document that is not public. Unticking Public withdraws the document from every site at once, because every publication needs the consent that public: true gives.

Content left out of a site

A site leaves out:

• documents without public: true
• protected documents, whatever their frontmatter says, and their titles
• publication pages, and include pages as pages of their own

A link to a page that is not on the site looks like a missing link and leads to a page that says "This page is not published." Search, the feed, the sitemap and linked references use only the published documents, so nothing on the site shows that a private document exists. See Protected Documents for more information.

Keys

Alt+P opens Settings on the Publish tab. Alt+Shift+P publishes again to the same folder or repository without opening a dialog. It uses the publication you last published from this device, or the only one in the graph. See Keyboard Shortcuts for more information.