History

If Kondo seems a bit odd, it's because it is trying to replace (without breaking any old content) the following three legacy systems:

  • The original renderer took .ucc files that contained plain HTML. When Kondo was implemented it was found in /cgi-bin/ucc-parser.0 and was a Python script that:

    • Searched for .conf from the root up to the directory containing the .ucc.
    • Read these .conf files, which simply contained "key = value" lines.
    • Used the "template" setting to find a .template file.
    • Used the Python % operator with the template on the left and the .conf variables (plus a "content" variable containing the HTML) on the right. If you find .template files with Python %(content)s variable substitutions or .conf files they likely belong to this system.

  • The DOCTYPE grahame renderer was a shell script (found at /cgi-bin/ucc-parser) that ran grep on the .ucc looking for DOCTYPE grahame. If it found it, the page was rendered with an XSLT processor using an .xsl stylesheet. If it didn't find the DOCTYPE, it called /cgi-bin/ucc-parser.0. A large number of old documents are still in this format. There were some terse notes in the original README.

  • A Markdown renderer was then also introduced into /cgi-bin/ucc-parser, triggered by the presence of @markdown. It called a Rust binary, /cgi-bin/ucc-markdown, which—impressively—output DOCTYPE grahame XML to then run through the same XSLT stylesheet. It included the following directives:

    • @markdown, @title, @banner, @style, @page, and @body, which are supported by Kondo.
    • @--, @include, and @exec, which could be anywhere in the document and aren't supported in Kondo to save a bit of processing time.
    • @nocache, which will probably be supported once Kondo supports WSGI.

    There were additional notes in the old /markdown.ucc.

These three renderers, nested inside of each other like rings of an ancient tree, did not spark joy.

Deprecated Formats

In old documents you may see one of the following directives:

@markdown

Or:

@grahame

Or even one or more of:

@github
@github-full
@ready-for-kondo

They no longer do anything at all, and you can safely remove them from any document.

Also, if you're editing old documents, you may see a @html directive, marking the file as containing only regular HTML:

@html

<p>Hello, world!</p>

You should avoid writing new documents in HTML. Where a part of the page can't be expressed in Markdown, Markdown allows the use of HTML tags.