Ninety-nine Pitchers of Malt
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    doczen-convertpublic

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

    Keywords

    install

    npm i doczen-convert

    Downloadsweekly downloads

    2

    version

    0.0.6

    license

    ISC

    last publish

    collaborators

    • avatar
    • avatar