Publishing from GitHub

Write internotes in your own editor, keep them in a GitHub repository, and let a push publish them. The repository is the source of truth: a connected internote is edited on GitHub, not here.

#Connecting a repository

  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.

An organisation’s admins do the same under Connections in the organisation’s preferences. Internotes from its repository belong to the organisation and carry its byline.

#What a push does

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
Moves its internote to Recently Deleted. Putting the file back creates a new internote; restoring the old one from Recently Deleted brings it back, no longer tied to the repository.
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.

A private repository does not publish private internotes. An internote is public until you make it private on Internote, from the status badge beside its title, and a push never changes that. Whether the repository is private decides only who is shown the link to edit the file on GitHub.

#Files that belong together

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.

#When a file fails

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 as a check named Internote on the commit on GitHub, with the error placed on the file and line. On Internote, each failed internote is marked Sync failed with its message and listed under Needs attention on the Internotes tab of Studio — yours, or the organisation’s for its repository. The connection’s row under Connections counts the failures and links there.

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

#Syncing by hand

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.

#Editing a connected internote

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 or deleted here; only its visibility can be changed. Each of those says so and asks you to disconnect first — otherwise the next push would simply undo it. The repository’s owner, you or the organisation, also stays one of its authors for as long as it is connected.

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.

#Connecting an internote you already have

Tick the internote in Studio — for an organisation’s repository, in the organisation’s Studio, which is for its admins — 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. An internote connected to an organisation’s repository has the organisation as one of its authors, and keeps it while it is connected.

#Building a map from a folder

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 an organisation’s map this is for its 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

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.

Last updated