md_gen

md_gen is a framework for generating documentation in markdown. It can generate metadata compatible with Vuepress.

Purpose

md-gen is intended to generate Vuepress compatible (or basic) markdown site. It is usefull for documenting from complex data structures.

By now, every call beginning with add_* is generated on its own line in the markdown source. You can mix different formats on the same line using add_text(text: &str). Some exceptions are multi-lines :

• table headers
• definition
• unordered / ordered lists
• specific code
• ...

md_gen in action

use md_gen::{Markdown, Metadata};

fn main() {

    let mut md = Markdown::new("docs/index.md");

    // Create metadata if you generate a vuepress markdown site.
    let metadata = Metadata {
        title: "My project doc",
        permalink: "/index.md",
        categories: vec!["myProject", "doc", "markdown", "vuepress"],
        tags: vec!["tag1", "tag2"].into_iter().collect()
    };

    // Adds metadata to the doc
    md.add_meta_data(metadata);

    // Compose the doc

    // Main Heading
    md.add_main_heading("My project doc"); // # My project doc

    // Adds an horizontal rule
    md.add_horizontal_rule(); // ---

    // Adds a lvl 1 heading (...and so on to lvl 3)
    md.add_lvl1_heading("My lvl 1 title");
    // ## My lvl 1 title

    // Adds a blank line
    md.add_blank_line();  // \n

    // Adds a blocquoted unordered list from a Vec<&str>
    md.add_unordered_list(vec!["item1", "item2"]); 
    // - item1
    // - item2

    // Adds a blank line
    md.add_blank_line();  // \n

    // Adds a blocquoted unordered list from a Vec<&str>
    md.add_blockquoted_unordered_list(vec!["item1", "item2"]); 
    // > - item1
    // > - item2

    // Adds a blank line
    md.add_blank_line();  // \n

    // Adds a blocquoted unordered list from a Vec<&str>
    md.add_ordered_list(vec!["item1", "item2"]); 
    // 1. item1
    // 2. item2

    // Adds a blank line
    md.add_blank_line();  // \n

    // Create a table

    // Table headers
    md.add_table_headers(vec!["Header1", "Header2"]);
    // Table row
    md.add_table_row(vec![
            "Cell content 1",
            "Cell content 2"
        ]);
    }
    // | Header1 | Header2 |
    // | --- | --- |
    // | Cell content 1 | Cell content 2 |

    // Adds a link (internal and external)
    md.add_link("/another_page.md", "Link to another page");
    // [Link to another page](/another_page.md)

    // Adds an image
    md.add_image("assets/image1.png", "Alternative text");
    // ![Alternative text](assets/image1.png)

    // Adds a definition
    md.add_definition("Word", "Definition of this word.");
    // Word
    // : Definition of this word.

    // Adds a block of specific code
    md.add_specific_code("rust", "let foo = MyStruct {\n  bar=\"bar\"\n};");
    // ```rust
    // let foo = MyStruct {
    //   bar="bar"
    // }
    // ```

    // You can also write your own formatted text.
    md.add_text("**[Will Rust win ?](https://www.googlefight.com/rust-vs-rest+of+the+world.php)**");
    // **[Will Rust win ?](https://www.googlefight.com/rust-vs-rest+of+the+world.php)**

    // Try to write the file
    match md.write() {
        Ok(_) => {
            println!("Doc {} has been generated.", md.filename);
        },
        Err(err) => {
            println!("Error while writing {}. {:?}", md.filename, err);
        }
    }

}

About the author and the code

Long time developper, Rust beginner. I am open to positive feedbacks about this library and the way it is written or its future features. Feel free to contact me.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.