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.
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.
# 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.
# Title The body, task formulation. =Hint 1 ... =Hint n ... =Solution ...
All sections are optional, the solution should exist.
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]
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]()
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)
*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__
.
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><body></code>
To use tags inside the inline code code, use the CODE
tag:
<code>on<i>event</i></code>
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
.
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]
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 characters '<', '>' and '&' are autoreplaced in a smart way. You can put them in the text:
a < b // autoreplaced to a < b <a> // not autoreplaced, tags still work
[verbatim]
bb-tag:
[verbatim] `no format [#here]` [/verbatim]
assets
folder unless the content is really global.