Documarium

Lists every page of a kept site, or of a preview given its draft_id, in one answer with no paging. Each line is a page's address and title, indented by depth, and on a kept site the date it last changed. A kept site lists the top-level pages first, then each deeper level, in alphabetical order of address within a level; a preview lists all its pages in alphabetical order of address. It is how page addresses are found: read_page reads one page in full, find_references finds the pages that state a given fact, and site_status says whether the site is published.

Reads one page of a kept site, or of a preview given its draft_id. It returns the page's address, its title and its full markdown; on a kept site also the date it last changed and the settings at the top of the page, as key: value lines. When no page has that address, it returns the five closest addresses instead (on a preview, every address the preview has). The markdown it returns is what a propose_edit update replaces. list_pages lists the addresses, and find_references finds which pages mention something without reading each one.

Finds the passages in a site that state a fact, and returns each with its page address, its line numbers and its text, best match first. On a kept site it matches meaning, so passages that say the fact in other words are found too, each with a confidence from 0 to 1; if that search cannot answer in time or fails, a plain word match comes back instead and the answer says so. On a preview, given its draft_id, it matches words only. Before a fact such as a refund window, a limit or a product name changes, it shows every page that states it, so one propose_edit can change them all. read_page reads a whole page.

Lists a kept site's numbered versions, newest first, a page of them at a time: each line is the version number, what changed, who changed it and the date. When older visible versions remain, the answer gives the starting_before value that lists the next page. Given compare_from and compare_to, it instead lists each page that differs between those two versions, as added, removed or the number of lines added and removed. How far back versions can be seen depends on the site's plan; older ones are still kept, and the answer says where the visible ones start. It answers what changed and when: site_status says what readers see now, and rollback takes these version numbers. A preview has no history until it is kept.

Reports the state of one site, or of a preview given its draft_id, at the moment of the call. For a kept site: its name and address; whether readers can see it, and at which version; whether a publish is under way; when it was last published; whether the last publish failed, and at which file and line; and, when the site has published as often as its plan allows for the day or month, when waiting changes go out. Someone whose role lets them keep changes also gets the changes waiting to be kept, each with a link to read it and the reference apply_edit takes. For a preview: its link, its number of pages, how many hours it has left and, for someone not signed in, how many more changes it can take before it is kept. With site left out on a connection that covers several sites, it lists them by name and address. It answers what readers see now and what is waiting: history lists past versions and who made them, and list_pages lists the pages.

Stages a set of page changes (create, update, delete or move) for review, without keeping any of them. On a kept site it returns a link that shows the site with the changes for 24 hours and can be shared, the reference apply_edit takes to keep them, and any links the changes would break; readers see nothing until the set is kept and published. On a preview, given its draft_id, it only reports what the changes would do, and apply_edit with the same operations saves them. The operations are checked together: if one is refused, none is staged. A change that would take the site past its plan's room for pages or storage is refused. It is the first step of every change to a kept site's pages, except going back to an earlier version, which rollback does; a preview of new content starts with create_preview.

Keeps changes. On a kept site it takes the proposal_id that propose_edit returned, or that site_status lists, and saves that staged set as the site's next numbered version, all at once or not at all. It does not publish: readers see the change after publish. A staged set is not kept if someone else changed the same pages in the meantime or if it is more than a day old, and the answer says which. A member whose role does not allow keeping leaves the change waiting for an editor. On a preview, given its draft_id, there is no staged set: it takes the operations themselves and saves them into the preview at once, and the preview's link shows them. rollback undoes a kept version.

Publishes a kept site: its latest kept version goes out to readers at the site's address and replaces what they saw. It answers at once, the publish starts in about a minute and readers see it shortly after, and site_status shows the progress. Only kept versions go out, so changes from propose_edit need apply_edit first, and the site needs a front page at /. Publishing needs a paid plan with room for the site; without one nothing goes out and the answer says so. When the site has already published as often as its plan allows that day or month, the version waits and goes out on its own later. A writer on the site cannot publish; an editor or admin can. A site whose content was brought from somewhere else needs, once, the person's confirmation that it is theirs to publish (rights_confirmed). Given the draft_id of a preview nobody has kept yet, it first keeps the preview exactly as claim_draft does, under the name given as subdomain, and then publishes it; if it cannot publish, the preview stays kept and the answer says why. To keep a preview without publishing it, claim_draft is the tool, and it needs no paid plan. rollback goes back to an earlier version.

Puts a kept site, or chosen pages of it, back to how they were at an earlier version. The result is saved as a new version, so no version is lost and a rollback can be undone by going back again; when nothing would change, no version is saved. If the site is published, it republishes by itself and readers see the restored pages, unless the site has already published as often as its plan allows that day or month, when it goes out on its own later. Only versions the site's plan lets it see can be chosen, by the numbers history lists. A writer on the site cannot roll back, and someone who looks after part of a site names those pages. It is for going back to a version; propose_edit makes a new change to a page.

Creates a temporary preview site from pages already converted to markdown, and returns its link and its draft_id. The preview belongs to no one until somebody keeps it, and expires if nobody does. The result says what to check, page by page, before the link is shared. It is the tool for content that has no site yet. A preview's pages are then changed with apply_edit and its draft_id; claim_draft keeps it, and publish keeps and publishes it in one call. A kept site is changed with propose_edit and apply_edit. It takes one entry per page; a record of where the content came from, exactly as it happened: a code repository, a documentation site, a product landing page, writing supplied in this conversation, a file attached to it, or nothing, when it was drafted from what the person described, with the address when there is one; the product's name; and, when the source shows one, the address of its logo. It reads no source itself: a call with no pages is answered with what to send instead. A source past the preview's page or size limit is refused, and the answer gives the limits. Which pages come over from a source with many pages is the person's choice, made after they see what was found and before it is converted: everything, one part, or a new structure. When they have already named the pages, that choice is made. Pages arrive finished, with no notes, placeholders, open questions or marks. A page with a note to its author, such as [GAP], [?] or TODO, is refused. Where the source is silent, a page carries the best answer and what was assumed is said in the conversation. On a legal page, the business's legal name, its address, the country whose law applies and who else handles its customers' data come only from the person or their source; a page missing one of them still reads complete without it, and what was assumed is said in the conversation. The page list is short: every page should be one a reader would open on its own; contact details and short notes belong inside

Keeps a preview nobody has kept yet as a site in the signed-in person's own account, at the web address named by subdomain. Its pages come over as they are and nothing is published: the site gets a private link, and readers see it only after publish. Keeping needs no paid plan. Without a subdomain, or with one that is taken, the answer offers names that are free and nothing is kept. It is the tool for keeping a preview without publishing it; publish with the same draft_id and subdomain keeps and publishes in one call, which needs a paid plan. The subdomain is the web address, not the name shown at the top of the pages, which set_branding sets. Keeping a preview confirms the content is yours, or that you have permission to publish it; this is recorded.

Change how a site looks: its theme, main colour, typeface, header links, logo and icon, and whether it has an Articles section. Only the site's owner can do this. Give only the things to change; the rest stay as they are. The changes show from the site's next publish. Every look change (theme, Articles, colour, typeface, header links, logo and icon) waits for the owner to publish; until then it shows in the site's preview. Before turning Articles on, tell the owner that readers won't see anything yet: they can look at it in the site's Preview, change anything, then publish, or ask to turn it off again. Offer to move pages that read like articles (comparisons, guides, news) under /articles with propose_edit; moved pages keep their old addresses. Page text is changed with propose_edit, not here. A logo or icon is taken from an address you give; say images_are_ours: true only when the owner has told you the pictures are theirs to use — otherwise they are kept but not shown until the owner confirms them on the site's preview. site_name is the name shown at the top of every page, not the web address: a preview's web address is chosen when it is kept, as claim_draft's or publish's subdomain, and no argument here changes it. On a preview nobody has kept yet, give its draft_id to set its name or its logo. Give languages to change the language the site's own words — Previous, Next, Search — are in.