GuideConfiguration
Build with AI
Publish llms.txt and Markdown versions of your pages for language models, and work on a Douze site with an AI agent.
Language models read Markdown better than HTML. A Douze site can publish an llms.txt file that lists its pages,
and a Markdown twin of each page next to its HTML, with a template and one workflow step. This page shows both, then
gives tips for AI coding agents that work on a Douze site.
llms.txtLink to this heading
llms.txt is a Markdown file at the root of a site that describes it and links to its pages.
In Douze it is a template in the content folder, llms.txt.liquid, rendered like a page and written as llms.txt:
# My site
> Documentation of My product.
## Pages
{% for p in collections.all %}
- [{{ p.data.title }}]({{ p.data.url | replace: 'index.html', 'index.html.md' | absolute_url }}): {{ p.data.description }}
{%- endfor %}
collections.allholds every page, sorted by date then by path. Filter it withwhere_exp, or loop over a sidebar to follow the order of your navigation.absolute_urlprependssite.url, fromdouze.yml.- The
liquidstep encodes the output of{{ }}for the content type of the file it writes, and a.txtfile is not encoded: characters such as&stay as they are. - Templates such as this one are not in the collections, and layouts only apply to HTML files.
The links point at the Markdown twins of the pages, below. Link to the HTML pages instead
({{ p.data.url | replace: 'index.html', '' | absolute_url }}) if you do not publish twins.
Markdown twins of pagesLink to this heading
The fork step passes each file through and adds a copy of it. Placed after render (Liquid) and before
markdown, it copies every Markdown page with its Liquid rendered, includes and shortcodes included, before it
becomes HTML. The copy is written next to the page, at the page's URL followed by .md, as llms.txt suggests:
/guide/intro/ has /guide/intro/index.html.md.
site:
url: https://example.com
steps:
pages:
inputs: "_content/**"
uses: frontmatter
permalink:
needs: pages
uses: permalink
collections:
needs: permalink
uses: collect
render:
needs: [permalink, collections]
uses: liquid
twins:
needs: render
uses: fork
match: "**/*.md"
with:
permalink: "{{ url | replace: 'index.html', 'index.html.md' }}"
data:
markdown: false
markdown:
needs: twins
uses: markdown
layout:
needs: markdown
uses: layout
write:
needs: layout
uses: write
permalinkis a template over the page's data;urlis the page's HTML path (/guide/intro/index.html).datais merged over the copy's data:markdown: falsekeeps themarkdownstep from rendering the copy to HTML, and since the copy is not an.htmlfile,layoutleaves it alone.- Code fences are not Liquid, so a page that shows
{{ }}in a fence keeps it in its twin. - The lines that mark raw HTML regions (the output of block shortcodes) are removed from the copy
(
strip-regions, on by default). The HTML of the shortcode stays. contentsets another text for the copy, a template with the page's text ascontent, for instance to add the title as a heading:content: "# {{ title }}\n\n{{ content }}".skipleaves some pages without a copy:skip: "draft".
With _site/guide/intro/index.html and _site/guide/intro/index.html.md written, a "Copy as Markdown" or "View as
Markdown" link on each page is a link to {{ url }}.md. See the fork step.
Tips for AI agentsLink to this heading
An agent that edits a Douze site works best when it can see the workflow and check its changes. Put these in your
agent instructions (AGENTS.md, CLAUDE.md):
Read the workflow, do not guess it.
douze --print-workflowprints every step a build runs, the default ones included, with theirinputs,needsand options. It exits without building.Build in plain mode.
douze build --plainprints one line per step and the errors, without the live view (agents usually run withCIset or a redirected output, which does the same).Check the exit code.
0is success,1a build error,2an invalid command line ordouze.yml.Read errors as positions. Errors have one format, with the step, the file and the position:
douze.yml(6,3): error: step 'markdown' needs unknown step 'markdwn'; did you mean 'markdown'? error: render: /blog/first/index.md(3,1): '{% endif %}' was expectedThe file of a build error is the file's path in the workflow at that step (after
permalink, its output path), and the line is in the page's body, after its front matter.Check requirements before building.
douze doctorlists what the steps need (libvips, downloaded tools, the programs of command steps) and exits with1when one is missing.Make mistakes fail.
strict: trueon theliquidstep makes an undefined variable an error, and thefrontmatterstep'srequirelists keys every page must have:pages: inputs: "_content/**" uses: frontmatter with: require: [title, description] render: needs: paginate uses: liquid with: strict: trueFail on purpose.
{% error "message" %}in a template fails the page with the position of the tag, and{% warn "message" %}logs a warning: use them to assert what a template expects.