doczen-convert

Still WIP! More docs coming soon.

Using the Converter

npm install -g doczen-convert
doczen /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 = require('doczen-convert/stream')

gulp.src('docs/**/*.md')
    .pipe(doczen(optional_options))
    .pipe(gulp.dest('output_docs'))

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: {...}
}