Book structure

At the top level, books are listed by language: en, ru ... Each language is a separate book.

The book content resides in files with .md extension. There may be asset files like scripts, styles etc. A book content may use them, but no parsing and formatting is applied to non-.md files.

Book pages and chapters must start with a digital number followed by a hyphen: 01-..., 02-... etc. It is used for sorting.

Anything ending with .bak is ignored.

The title is inferred from the first header of the page. For a folder (chapter), the file 00-index.md is used for this purpose. This file should have at least a header. You can also add few introductory paragraphs.

Tasks for the chapter must be in the task subfolder.

Encoding is UTF-8. Line breaks are unix-style: \n.

Navigation

Browser navigation by using nav.html.

Navigation does not autopickup your changes. If you change the structure or references, then the navigation needs to be rebuilt.

JavaScript is unable to traverse the directory tree, that's why a signed Java Applet is used. It gets executed only when rebuilding navigation. You need to have Java installed.

Actually, the applet is small, simplified and secured to maximum. All it can do is to get file names inside a folder and write to file which ends with '.applet.json'. For additional security, it only works locally, so if anyone tries to put it on the web, nothing would work.

The sources are in the engine/jpath folder. If you feel really paranoid, recompile it and sign by your certificate.

Please never click "Trust always" on it.

Layout

Page layout

    # Title

    This is a short intro to the page.
    The cut below is optional, but recommended.
    If there is no cut, then several first lines are used.

    =Cut

    The body.

    =Head

    Scripts, styles, other unformatted stuff that goes to HEAD.

All sections (starting with "=") are optional.

Task layout

    # Title

    The body, task formulation.

    =Hint 1
    ...
    =Hint n
    ...
    =Solution
    ...

All sections are optional, the solution should exist.

Formatting

Headers

Headers starts from #:

# Title
## SubTitle

There should be only one 1st-level header in the document: the title.

A header may have id:

## Header with id [id]

External Links

Links can be written as [title](url), for example:

    [Google](http://google.com)
    ["Title with backslashed quote: \", [ and ] "](http://somewhere.com)

To put a link which name is same as URL, use empty ():

    [http://google.com]()

Internal links and references

All internal links must be made through references, not URLs. The purpose of such structure is to ensure consistency across the book. All references are global and unique.

A reference is created with [#id] anywhere in the text. A reference must be latin alphanumeric with hyphens.

    [#events-this]

It may have a title after |:

    [#closure-peculiarity|Closure Peculiarity]

Headers with [id] can be used as titled references.

To make an internal link link, use [title](#id), for example:

    Somewhere: [#good-info]

    Now the link: [Good reading](#good-info)

A link can also use the reference title:

    This will show up as "Good reading" link: [](#good-info)

Bold, italic

Use *text* for italic, **text** for bold. If there are spaces, it won't get formatted: a * b * c leaves formatting as is, because there are spaces around '*'.' Instead of asterisks, one can use underlines, like this: _italic_ __bold__.

Code

Inline code

The inline code in backtricks `code` is wrapped into CODE tag.

To use backtricks inside the code, put double backtricks around it:

    `` `which` `` -> <code>`which`</code>

All special chars inside code are replaced inside `...`. You can write `<body>`. But even if you want to use tags, they won't work. For example:

    `<body>` -> <code>&lt;body&gt;</code>

To use tags inside the inline code code, use the CODE tag:

    <code>on<i>event</i></code>

Code blocks

A code block is wrapped in bb-tags: 

    [html]
    <!DOCTYPE HTML>
    <html>
    ...
    </html>
    [/html]

Other languages supported(by extensions): js, css, java, ruby, php, txt, py, xml, xslt, html, erl.

A code block can be made runnable by adding a run attribute: 
    [html run]
    <p> A "run" button will appear above the code block </p>
    [/html]

The attribute autorun makes html/js code run automatically. For book pages, the execution happens on the same domain, in iframe for HTML or eval for JS.

Important parts of the code can be delimited by *!* ... */!*.

    [js]
    var body = *!*document.body*/!* // inline

    *!*
    alert(body) // block
    body.innerHTML = 5
    */!*
    [/js]

Code inclusions

For a larger code, you may want to put it into a file and use the src attribute:

    [js run src="assets/my.js"][/js]
ADD: UNTRUSTED (force on another domain)

The path is resolved relative to the current page. The absolute path is resolved relative to the book. External URLs like http://... are not allowed.

Special chars

Special characters '<', '>' and '&' are autoreplaced in a smart way. You can put them in the text:

    a < b  // autoreplaced to a &lt; b
    <a> // not autoreplaced, tags still work

Verbatim pieces

No format happens inside [verbatim] bb-tag: 
    [verbatim]
    `no format [#here]`
    [/verbatim]

Best Practices