Turnkeel GitHub (opens at launch)

Docs The app

Docs and Links

Docs shows your product's Markdown, synced from its repository and drawn in place. Links holds the addresses a team keeps going back to, such as dashboards and consoles. Docs come only from the repository; links are edited in the app.

Choosing the docs

.turnkeel/docs.yml lists which Markdown files show under Docs, in which groups and in which order:

groups:
  - title: Product
    docs:
      - docs/ARCHITECTURE.md
      - path: docs/API.md
        title: API
        summary: Every endpoint
  - title: Launch
    docs:
      - docs/launch/*.md

A doc is a path from the repository's root, or a path with a title and a summary. A pattern with * or ? names the matching files in one folder, in the order of their names, and takes no title. Without a title, a doc takes its first # heading, or its file name.

A doc must be a Markdown file (.md or .markdown) inside the repository, tracked by git and not ignored, not hidden (apart from .turnkeel/docs/), not a symbolic link, and at most 1,000,000 characters. A problem names docs.yml and the line, and nothing is sent.

Syncing docs

turnkeel sync --dry-run
turnkeel sync

turnkeel sync sends the listed docs with the gate and listing files, with the commit and branch checked out. The server parses the Markdown and says which local images the docs use. The CLI then uploads each image that is new or changed: a PNG, JPEG, GIF or WebP file in the repository, tracked by git, of at most 20 MB, that a doc names itself. A project with docs and no gates syncs its docs alone. The token needs docs:sync.

The docs that docs.yml lists replace those the project had, so a doc that left the list is removed. A docs.yml that lists no doc is refused, unless --all-docs-removed says every doc was removed on purpose. A doc changes only when sync runs; nothing in the app writes one.

How a doc is shown

  • A list at the side with the groups, titles and summaries of docs.yml. Below 1024 px it is a select above the doc.
  • One reading column with the doc's title, its path and "Synced from <commit>, <time>".
  • One Markdown pipeline for docs, cards, changelogs and listings. Raw HTML is dropped. Mermaid diagrams are drawn in the current theme, as pictures that run no script.
  • Images from the repository show from the files sync uploaded. An image at a remote address is not loaded and shows as a link.
  • A doc of 5,000 characters or more folds by heading, with Expand all and Collapse all. Long code blocks fold too.
  • An "On this page" outline names the sections of a doc with two or more.
  • A link to another synced doc opens in Turnkeel. A relative link to a file that is not synced opens on the repository, when the project has a repository address.

With nothing synced yet, the page says how to start: list the files in .turnkeel/docs.yml, then run turnkeel sync.

Links is one column of groups: the project's groups first, then the groups of the whole workspace, which show in every project and say so. Each link shows its label, which opens in a new tab, its address and its note. A search box matches labels, addresses, notes and group titles across every group.

Members, Admins and Owners add, edit, reorder and remove groups and links in the app. Links are private dashboards, so they are kept in Turnkeel and not in the repository. Only http and https addresses are kept.

Tool Command Scope Does
list_docs docs:read Lists the project's docs in the order of docs.yml
read_doc docs:read Returns one doc by its path, with its Markdown
add_link turnkeel link add links:write Adds a link at the end of a group

A doc's text reaches an agent as text from its file, never as instructions. An agent adds a link only to a group whose id a person gave it, with Copy its id in the group's menu. It cannot read, change, reorder or remove links or groups, and a link it added says so, as in "Added by builder, 11 Nov". A group of the whole workspace takes an agent's link only with a workspace-wide token.

The source of this page will be on GitHub when the repository opens. Something wrong or unclear? Write to us.