Editing Text

Editing text in Blueprint — any text more complicated than ordinary paragraphs — involves a little understanding of the way Blueprint transforms the text you write.

Blueprint doesn't have a WYSIWYG interface for editing text. This is a deliberate decision, intended to help you to focus on the structure of what you're writing, not the presentation. It also means you're a lot less likely to 'break' the site design by using an inappropriate font, or font size, or whatever.

Instead, you write text in a similar way to how you might write it in a plain text email, and Blueprint transforms it into the structural elements you mean. The way it does this involves a process called Markdown, and if you're curious you can follow that link to read more about it.

Blueprint has a toolbar on all textareas that are processed with Markdown, which looks like this:

In the screenshot above, the toolbar is shown with its help window open (click the [?] button to toggle it).

The help window covers the basics of writing Markdown text. There are toolbar shortcuts for italicising, bolding and linking text — simply write the text then click the button. If you want to know what your full range of Markdown options are, read the syntax specification.

Blueprint-specific extensions

Blueprint also has a few special extensions on Markdown processing, which are intended to offer integration with text editing and the various other concepts in Blueprint, such as linking to internal pages and inserting images and downloads. The rest of this document provides the technical specification for these extensions.

Quick links

You can link to other pages in the site using a simple syntax of page-slug->text inside square brackets. Note that page-slug is the relative url of a page (except the leading forward slash). text is the displayed contents of the link element.

Inserting assets

In general, you insert an asset by putting its name within double-square-brackets. Clicking on an asset in the sidebar will do this automatically.

There are a number of advanced options for inserting particular kinds of assets. The various recognised assets are:

• Images (have a mimetype of image/*)
• Videos (have a mimetype of video/* or application/x-shockwave-flash)
• Audio files (have a mimetype of audio/*)
• Document files (have a mimetype of application/*)
• Other files

The 'insert asset' button on assets in the sidebar provides a GUI for building the options that sit after the pipe (|) in the asset token. These options vary based on the type of file:

For all asset types:

• path_only — just display the public path to the file, unlinked and not within any special markup
• link_text — display a link to the file, with the given link text

For videos, audio files, documents and other files:

• show_icon — display the mime icon for the file in the download link. Default to true if unspecified.
• show_name — display the name of the asset in the download link. Defaults to true if unspecified.
• show_size — display the size (in Kb if under 1Mb, in Mb otherwise) of the asset in the download link. Defaults to true if unspecified.

For images:

• There is a special caption syntax, which uses parentheses adjoined to the asset token. Note that you can escape closing parentheses inside the caption using a backslash. So, eg: (This is the adjoining caption (which itself contains parentheses\).)
• enlarge — clicking on the asset will take you to a full-sized version of the image. This link will have a rel="lightbox" attribute, so if a lightboxing library is active in your site, it should pop up in the existing window.
• link — a URL to which the user will be taken when the image is clicked (an alternative to enlarge)
• class — the CSS class to give the image
• title — the title and alt text to give the image
• Any other attribute will be directly applied to the image tag.

Note that if you are the site developer and you use a site rule to override the default asset snippets, you may choose not to honour some of these options, or perhaps add your own options. In such cases you should obviously provide documentation to your site editors so they are not confused by the logic described on this page.