Octavo is a JavaScript library for making HTML pages editable in Chromium and Chrome (Safari is reported to work too), without touching the source.
To make a page editable, all you need to do is download octavo.js and link to your local copy of it from within the webpage:
<script src="path/to/octavo.js"></script>
Please don't link to the script here; this site is not a CDN. Nothing else is required on the client side, so once you have that, the page will be editable. To save pages, however, Octavo uses HTTP PUT, which must be handled on the server side.
There are two ways to start editing an Octavo enabled page by placing the page in edit mode. Either ⌃E, or ⇧Click. The latter method only works if you don't make a selection with your click. To stop editing, you can either use ⌃E again, which works as a toggle, or Esc, which will also automatically save your changes before exiting edit mode. To save the document manually, use ⌃S.
Once in edit mode, a status bar will display in the corner of the page showing the current element context. You can now click around, use arrow keys, type, and press Return to make new lines or new elements. This functionality is mostly enabled as part of the native browser controls for HTML5's contenteditable attribute. Octavo adds extra functionality on top of these existing controls.
There are two basic ways to interact with elements in Octavo. One method deals with block elements, and the other with inline elements. Block elements are large, self-contained elements like headings, paragraphs, and preformatted sections. Inline elements are smaller, nested elements such as anchors (links), emphasis, and code.
Block elements are transformed using Octavo from any point within the block. This means that, in general, you can transform any existing block into any other existing block. To create a new block, you usually press Return at the end of a block to create a new paragraph, and then transform that paragraph into something else if need be.
Here are the block transformation keyboard shortcuts:
Octavo normally uses keyboard shortcuts rather than GUI controls for the most common tasks, because keyboard access is faster than mouse access. Note that the transformation command for Headings is special in that not only does it transform any other block to a heading, but it also cycles through different levels of heading. Any non-heading block is transformed first into an h1, then into an h2, an h3, and an h4 in sequence, with each press of ⌃H. Any h4 elements are transformed back into h1. This allows quick and easy access to the most common levels of header elements. You can also use ⌃1 through ⌃6 to transform blocks to the respective headings.
To stop editing a block element, you can usually press return at the end of the element to create a new paragraph block immediately after it. This does not work in preformatted sections, where Return simply creates a new line. To make a new paragraph from the end of a preformatted section, use ⌃O. Pressing Return inside a block usually splits that block into two.
Inline elements work in a different way. Pressing one of the inline element shortcuts will do one of two things. If an amount of text is selected, then that selection will be wrapped in the corresponding inline element. If no text is selected, then a new inline element will be created, and the caret placed inside the new element.
Here are the inline element keyboard shortcuts:
Here, ⌃A is slightly special in two ways. First, it can only be used on a selection of text; it won't create a new element if nothing is selected. Second, it will prompt for a link for the anchor to point to. The user does not have to supply a link immediately; the prompt will remain until another prompt is needed or the author saves using ⌃S or Esc.
To stop editing an inline element, press the corresponding inline element shortcut again from anywhere within the inline element. This will place the caret immediately after the current inline element. To remove an inline element, or indeed any enclosing element, use ⌃R from within that element.
When creating a new page for the first time, the existing content will be dependent on what is in the document to start with. It is possible to serve pages with only the link to Octavo and perhaps a stylesheet in the page head section, giving the user a blank canvas. But other setups may have different kinds of starting pages.
To return an existing document to a clean starting state, press ⌃N. This will transform the status bar in the corner of the document into a link prompting the user to click it. This is to ensure that a document is not reset accidentally, as this action cannot be undone. Once the status bar link is clicked, the user will be prompted for a new document title, and then placed into the single block, an h1 heading which will be pre-selected.
It is possible to force a document to enter this reset mode upon entering edit mode by adding the following meta element to the top of a document:
<meta data-octavo-reset>
This meta element will be automatically removed once as edit mode is entered.
To insert a new image, use ⌃K. This will prompt for a link to an image, much like when creating a new anchor. Unlike creating a new anchor, however, ⌃K does not require any text to be pre-selected. If some text is pre-selected when ⌃K is used, this text will be removed from the document and used as the alt attribute of the new image.
You can also paste images, if your server supports it. This is an experimental feature, but if you have a JPG or PNG image on the clipboard, you can paste it straight into the document. It will then be sent to the server at a specific address using HTTP PUT.
There are some special keyboard shortcuts to facilitate other editing tasks.
⌃- and ⌃= move the existing block up or down before the preceding or after the following blocks respectively. This can be much handier than copying and pasting the block.
⌃. highlights the existing element when held down. This can help to show the user the extent of the existing element, which may for example not be obvious if no styling is applied.
⌃] and ⌃[ indent and unindent block elements respectively in 12px steps.
⌃\ selects the present element's entire content.
There are also some experimental features, mostly bound to ⌃ and number keys:
⌃6 works a little like a hybrid of ⌃H and the inline shortcuts.
If you forget any of the keyboard shortcut functions, you can summon and dismiss a cheat sheet using ⌃G.
The simple editing functions should cover the vast majority of editing actions required when making a reasonably simple document. For advanced editing, the browser's native DOM inspector can always be used, but Octavo also supports a GUI menu for some more advanced features, some of which would be otherwise unwieldy in the DOM inspector.
There are two ways to access the tool menu: either by using ⌃D, or by clicking on the element name in the status bar in the corner of the document. When using ⌃D, the current parent element will be selected if there is no caret text selection made; otherwise the first few children of the parent element will be selected as an experimental feature.
The tool menu consists of many links which will perform actions on the specified element. Be warned that some of those actions may be destructive, including one for removing the element and all of its contents. To dismiss the tool menu, use ⌃D or click once again on the name of the element in the status bar.
There are five kinds of tools in the tool menu:
Tools include change, wrap, take, destroy, and set-id.
Tools include left, centre, right, float-left, no-float, float-right, small-caps, no-caps, box, and unbox.
Tools include before-parent, after-parent, into-prev, and into-next.
Tools include show-nbsp, hide-nbsp, zws-pad, and zws-unpad.
Tools include wrap, toc, and timestamp.