Customisation with CSS

The simplest way of customising the look-and-feel of an MKDoc site is to attach a CSS (Cascading Style Sheet) file to override some of the default values for colour, fonts and layout.

Cascading Style Sheets

MKDoc separates style from content for consistency and accessibility — Styling such as colours and fonts is defined as a policy rather than requiring each author to style their own content — This is achieved simply by using widely available Cascading Style Sheet Standards.

A style sheet is a simple text file that declares styles for HTML elements such as body text, paragraphs, headlines, etc… Style sheets cascade, which means that multiple stylesheets can be used to apply finer adjustments in turn.

An example style sheet

Here is a really simple stylesheet, all it does it to take the existing styles (declared by other MKDoc stylesheets), but changes the colour of all headline elements to dark green:

h1, h2, h3 {color: green;}

To use this style with MKDoc, simply write it in a text file called style.css and upload it as a file attachment.

You should be able to see that all the headline elements in the page have been changed to green as a result. MKDoc styles cascade, so any documents attached to this document would automatically have green headlines too.

All the elements in a page can be styled individually, even the text or logo in the banner at the top can be replaced by any image using CSS. Page layouts can be changed such as moving the sidebar navigation from right to left or from left to right.

Favicon icons

Websites/pages can have icons, simply upload a standard Windows format .ico file named favicon.ico to the front page and this will be automatically applied to all documents.

Advanced styling

Uploading CSS files to MKDoc documents can achieve nearly every stylistic change imaginable; though there are other techniques which involve accessing files on the webserver itself:

• Instead of supplementing the default MKDoc CSS, you can override it completely by replacing the CSS files on the system, each MKDoc site can have it's own custom style this way.

  This will involve editing the $SITE_DIR/httpd/httpd.conf file and pointing the /.static/css Alias to the new location.

• MKDoc uses the TAL XML templating standard to assemble the underlying HTML; you can override one or more of these templates, though most designers will find that the default MKDoc templates are sufficient for nearly all purposes. Do this if you must rearrange the display order of page elements or create custom templates for special purposes.

  Any templates you place in the $SITE_DIR/resources/templates folder will override the default MKDoc-1.6 templates automatically.

Firefox Tips

If you install Firefox and the Web Developer Extension then it is easy to dynamically edit the CSS of a page and see your changes as you make them, as illustrated in the following screen shot.

When you are happy with the CSS you have developed you can save it as style.css and upload it as a file component.