Publishing from GitHub

1. Open Preferences › Connections and press Connect GitHub. GitHub asks which account or organisation to install the Internote app on, and which repositories it may read. Only those repositories can ever be connected.
2. Back on Internote, press Connect a repository beside the installation. Choose the repository, the Branch whose pushes publish — the repository’s default is filled in, and any branch will do — and a Folder if only part of the repository holds internotes. Leave the folder empty for the whole repository.
3. The first sync runs at once. Every .chalk file under the folder becomes a published internote, owned by you.

A site admin does the same from the site’s admin area, under Connections. Internotes from a site’s repository belong to the site and carry its byline.

A push to the branch the connection follows publishes whatever changed under the folder. Pushes to any other branch are ignored. There is no draft state for a connected internote: what is on that branch is what readers see.

A new .chalk file

Becomes a new internote, published.

A changed file

Updates its internote in place.

A renamed file

Keeps its internote — the address, likes and bookmarks travel with it.

A deleted file

Unpublishes its internote. Put the file back and the same internote is published again.

A changed partial, dataset or image

Re-publishes every internote that uses it.

A .part.chalk partial is never an internote of its own: it is spliced into the files that include it and published only through them. A .chalk file whose document is not an internote — a docs page, say — is reported as a failure, so keep other kinds of Chalk outside the folder.

Everything an internote points at is written relative to the file itself, the way it would be in any editor:

• internote(ref: ./intro.chalk) references a sibling internote. On Internote it becomes a link to it.
• @include:header.part.chalk splices a partial from beside the file.
• @data#readings:data.csv reads a dataset from beside the file. A .geojson works the same way.
• image(source: ./figure.png) shows an image from beside the file. Images are capped at 2 MB.

The files an internote may draw on are images — .png, .jpg, .gif, .webp and .svg — .csv and .geojson data, and .part.chalk partials. A pointer at anything else fails the internote, as does a pointer at a file that is not in the repository.

A reference to an internote is gentler: one naming a .chalk file this connection does not publish — outside the folder, or not there at all — is left as written and reported as a warning, and the internote still publishes.

A file that does not compile does not take down what readers already see. The published copy stays as it was, and everything else in the push publishes as usual.

The failure is reported in two places: as a check named Internote on the commit on GitHub, with the error placed on the file and line, and on the connection’s row under Connections, where the failed files are listed with their messages.

Fix the file and push again. The next sync picks it up.

Sync now, on the connection’s row, recompiles and publishes every file under the folder, changed or not. It is the one action that does: a push, or a change to the connection’s settings, publishes only what changed.

Edit changes the two settings a connection has, its branch and its folder. Either change reconciles the whole tree: files newly in scope are published, files that fall out of it are unpublished — and are published again if the scope moves back — and the rest are left as they are.

Edit on GitHub replaces the editor on a connected internote and opens the file in the repository. When the repository is public, every reader sees it, so anyone can propose a change. When it is private, only people who can edit the internote see it.

While it is connected, the internote cannot be edited, published, unpublished, deleted or moved to a site here. Each of those says so and asks you to disconnect first — otherwise the next push would simply undo it.

To edit an internote on Internote again, disconnect it from its file: tick it in Studio and choose Disconnect from file, which takes any number of them at once. Each keeps everything the last sync gave it and is an ordinary internote from then on.

Tick the internote in Studio — or, for a site’s internote, on the site’s Manage page — and choose Connect to a file: one at a time, since it asks for a path. Pick the repository and type the file’s path, which must be on the connection’s branch and under its folder.

The file’s contents replace the internote’s at once, so put the current source in the file first — the internote’s address and history are what you keep. Connecting one of your own internotes to a site’s repository moves it into the site.

A map can follow a folder of a connected repository. Every internote under it, at any depth, is a member, and every push keeps that up to date — a new file arrives as a new node, a deleted one leaves.

Open the map, press Edit, and choose Connect to a folder at the foot of the details panel. Pick the repository and type the folder, or leave it empty for everything the connection publishes. The members appear straight away; the internotes are already published, so there is nothing to wait for. For a site’s map this is for the site’s admins, whose connections it uses.

Only membership comes from the repository. The map’s title, description, tags, visibility, sharing and its arrangement stay here and stay yours to edit — a push never moves a node you have placed. An arriving internote lands in a free row below the arrangement, for you to put where it belongs.

Links between internotes

Become the map’s edges. An internote(ref: ./other.chalk) in one file draws a line to the internote that file publishes, so a folder of internotes that cite each other arrives already shaped.

An internote added by hand

Stays. A map can hold members from anywhere alongside the folder’s; a sync only adds and removes its own. One whose file turns out to be in the folder becomes the folder’s from then on.

A file that fails to compile

Is not a member until it publishes. One that published before and then fails keeps its last good version, so it keeps its place.

A nested folder

Can have a map of its own. An internote under both folders is a member of both maps.

A member the folder put there cannot be removed from the map by hand — the next push would put it back. Delete the file, move it out of the folder, or disconnect the map. Disconnecting — from the same panel, or from Connections — leaves every internote on the map exactly where it is and hands the map back to you.

Disconnecting a repository under Connections stops its pushes from publishing. Every internote it produced stays on Internote with its last synced source and becomes editable here again. Nothing changes on GitHub.

The same happens from GitHub’s side: withdrawing the app’s access to a repository, deleting that repository, or uninstalling the app disconnects what it was publishing. Renaming a repository or moving it to another account does not — the connection follows it.

See also Publishing for the draft workflow that applies to internotes written here.