Still WIP! More docs coming soon.
Using the Converter
npm install -g doczen-convertdoczen /path/to/my/document.md
Syntax
Doczen syntax is a superset of markdown. You can use the full power of markdown, plus these additions:
Sections
A REPL is attached to a section, so to have multiple REPLs on a page, you need to use multiple sections.
You denote a new section with 3 or more colons in a row on a line alone.
More than 3 is allowed, but not necessary.
A blank line before/after the divider is allowed, but not necessary.
:::
This is a section
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
This is another section.
And here is section 2 paragraph 2
If you don't want your section to have a REPL, put an x
after the divider, like this:
:::x
This is a section without a REPL
A document starts with an implicit section, so there's no need to add a divider at the beginning of the file.
[Runnable] Code Blocks
All triple-backtick code blocks will be runnable by default, so you don't have to do anything special.
You can use a few "classes" to customize the code block:
.not-runnable
- Omit the "execute in REPL" button.no-highlight
- Omit syntax highlighting
You can combine "classes". Use them like this:
```javascript.not-runnable.no-highlight
```
Fill-in-the-blank Code Sections
You can make a fill-in-the-blank section in any triple-backtick code block by
wrapping any number of underscores or spaces inside [[ ]]
. Like this:
```javascript
console.log([[_______]] + ", World!")
```
The number of spaces or underscores you use will determine the width of the blank space.
Advanced Features
You may or may not need these:
Giving a Code Block an ID (& hiding it)
You can give a code block an ID like this:
```javascript#my-code-block
```
You'll probably also want to use the .hidden
class on the code block:
```javascript#my-code-block.hidden
```
You can combine an ID with any of the "classes" listed above. This is mostly useful for preloaded REPL contexts...
REPL Preloaded Context
If you want to preload some context into your REPL (say, to define some functions or make a global variable available), you can do it like this:
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
<#id-of-tag-with-code
Then whatever's inside $('#id-of-tag-with-code')
will be eval'd in the REPL.
Here's a full example:
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
<#my-section-context
Hey look, i'm in a section!
```javascript#my-section-context.hidden
function say_hello() {
console.log("Hello, World!")
}
```
Now if a user executes say_hello()
in the section's REPL, "Hello, World!" will be printed
to the console.
Use With Gulp
var doczen = gulp
Options object passed to .stream(opts)
:
// Or with options: // All options are optional // specify template template: '<div id="docs"></div>' // OR optionally specify template_file (asynchronous read) template_file: './template.html' // If a template is specified, you'll want to set the selector container_selector: '#docs' // If you want to modify the marked settings marked: ...