Documentation for agents

Every page on this site is also served as plain markdown, so a coding agent can read it without parsing HTML. The markdown is the page's source, so it uses the syntax the site is written in: headings, tables, fenced code blocks, and MkDocs Material's tabs (=== "macOS"), admonitions (!!! note) and key names (++ctrl+c++).

Index files

URL	Contents
https://docs.alisx.com/llms.txt	Every page as a markdown link with a one-line summary, grouped as the site's navigation is. Start here. Follows the llms.txt convention.
https://docs.alisx.com/llms-full.txt	Every page's markdown in one file, in the order of the index.
https://docs.alisx.com/sitemap.xml	Every page's HTML URL, for crawlers. robots.txt allows everything and names it.

One page as markdown

There are two ways to ask for a page as markdown.

Add .md to the page URL. https://docs.alisx.com/tutorials/install-the-cli/ becomes https://docs.alisx.com/tutorials/install-the-cli.md. A section index such as https://docs.alisx.com/how-to/cli/ becomes https://docs.alisx.com/how-to/cli.md or https://docs.alisx.com/how-to/cli/index.md; both work.

Ask for markdown. Request the page URL with the header Accept: text/markdown. The response is the markdown, with Content-Type: text/markdown and a Content-Location header naming the .md URL. A browser, which asks for text/html first, keeps getting the page.

Shell

curl -s https://docs.alisx.com/reference/cli/build.md
curl -s -H 'Accept: text/markdown' https://docs.alisx.com/reference/cli/build/

Each markdown page starts with a front matter block: title, description where the page declares one, and url, the page's HTML address. Links inside the page are absolute and point at the markdown version of the linked page, so an agent can follow them without keeping track of a base URL. Every HTML page also names its markdown twin with <link rel="alternate" type="text/markdown">.

The CLI's own manual

These pages describe the platform for people and agents alike. The alis command line carries a separate operating manual written for agents, with the output contract, the exit codes and the recovery steps for each error: run alis docs (see alis docs). An agent working in a terminal reads that first and comes here for the broader picture.