Using Markdown on the UCC Website

The UCC website now supports Markdown as a format for writing web pages.

Writing Markdown For A UCC Page

UCC Markdown pages are still .ucc files. To differentiate them from old-school .ucc files or DOCTYPE grahame files, they begin with the directive @markdown.

All lines beginning with an @ character are assumed to be directives to the Markdown interpretter. The directives supported are:

At the top of the file

• @markdown - indicate this is a Markdown page
• @title - the title for this page
• @page - the tab this page belongs to, one of home, about, infobase, services or events
• @banner - the banner title for this page (the underlined thing at the top)
• @nocache - don't cache this page (you probably want this if you're using @exec)
• @style - use a particular stylesheet for this page
• @body - append the following file at the end of this page

Anywhere

• @-- - a comment (to be honest, anything that starts with an @ is a comment)
• @include - include another file. This WILL be parsed as markdown
• @exec - execute a program/shell fragment (passes CGI env, buyer beware! Will parse for markdown)

At the moment, all other @directives are ignored. More may be added in the future. Directives may be included at any point in the Markdown, defining a directive twice has an undefined behaviour, don't do it.

Besides the directives, you'll want to read the Markdown Syntax Reference which tells you everything that you need to know about writing Markdown.

Sample Markdown Page

An example Markdown page might look like this:

@-- this is a UCC markdown file
@markdown
@-- the page title (the one that appears in the browser title bar)
@title Markdown for UCC
@-- what tab this page belongs to
@page services
@-- the big banner title on the top of the page
@banner Using Markdown on the UCC Website

The UCC website now supports
[Markdown](http://daringfireball.net/projects/markdown/) as a format for writingweb pages.

Writing Markdown For A UCC Page
===============================

UCC Markdown pages are still .ucc files. To differentiate them from old-school
.ucc files or DOCTYPE grahame files, they begin with the directive `@markdown`.

FAQ

I want to include some DOCTYPE grahame

Tough, I haven't figured out how to do that yet.

The parser could still be replaced despite this limitation because no-one is actually using @include for anything

Why can't I surround my @include or @exec in <pre></pre>?

This is due to a stupid technical limitation of PXY's parser (and may actually be fixed in tommoa's parser, but untested atm). The solution is to pass the -pre flag.

@include -pre myfile.ucc

This is useful with the -raw flag for displaying source code. Want to wrap it in something else? Sorry, you might be better off working out how to fix the bug.

I'm calling @exec, but my script is only ever run once!

Have you added @nocache to the top of your top-level file? It must be in the file that is actually requested by the user, it can't be in a file you @include or the output from @exec.

I want to set my title/banner from a script/include file

No can do, sorry. You're welcome to attempt to fix this.

Technical Mumbojumbo

In the old parser, parsing was handled by python-markdown. In the new parser, instead take a look at pulldown-cmark.

There is a script in ucc-markdown in the cgi-bin directory that converts Markdown files into DOCTYPE grahame XML files. If ucc-parser finds @markdown in the file. It will generate intermediate XML that it feeds to xsltproc to generate HTML. The HTML is then stored on disk and served similarly to how DOCTYPE grahame already works.

Credits

The initial implementation of this was done by PXY as a response to people who didn't like writing DOCTYPE grahame for the UCC website.

New implementation (whipped up in about 30 mins on 17-08-2019) by tommoa because he needs tables to be formatted more nicely tyvm.