19 releases

0.2.10 May 18, 2021
0.2.9 Feb 19, 2021
0.2.0 Jan 29, 2021
0.1.7 Nov 10, 2020

#268 in Text processing

Download history 197/week @ 2024-01-01 355/week @ 2024-01-08 286/week @ 2024-01-15 195/week @ 2024-01-22 182/week @ 2024-01-29 172/week @ 2024-02-05 351/week @ 2024-02-12 219/week @ 2024-02-19 224/week @ 2024-02-26 201/week @ 2024-03-04 647/week @ 2024-03-11 377/week @ 2024-03-18 18/week @ 2024-03-25 59/week @ 2024-04-01 15/week @ 2024-04-08 27/week @ 2024-04-15

122 downloads per month
Used in 5 crates (3 directly)

MIT license


Crate somedoc

A very simple document model and markup generator.

MIT License Minimum Rust Version crates.io docs.rs Build Audit GitHub stars


The somedoc::model module provides the model to construct documents.


fn readme_maker(crate_name: &str, repo_owner: &str, repo_name: &str, headline: &str) -> Document {
    let tbd = Paragraph::plain_str("TBD");
    let mut doc = Document::default();

    doc.add_heading(Heading::heading_1(&format!("Crate {}", crate_name)))

    let mut para = Paragraph::default();
        "MIT License",
            repo_owner, repo_name
        "Minimum Rust Version",
            repo_owner, repo_name

        .add_paragraph(Paragraph::bold_str("Version 0.1.0"));

    let mut list = List::default();
    list.add_item_from(Span::plain_str("Initial release.").into());




The somedoc::write module contains a number of serializers that generate specific markup formats for different platforms. So far, this includes HTML, LaTeX, and Markdown of different flavors.

JSON Interchange

A JSON representation of the library's Document structure is also provided and can be read as well as written to allow for tool interchange.


The following writes a constructed document to stdout as a Markdown document. The default flavor supported by the writer is the CommonMark spec.

use somedoc::write::write_document_to_string;
use somedoc::write::markdown::MarkdownFlavor;

let doc = make_some_document();

let doc_str = write_document_to_string(&doc, MarkdownFlavor::default().into()).unwrap();
println!("{}", doc_str);

The following writes the same document out in the XWiki markup form.

use somedoc::write::{write_document_to_string, OutputFormat};

let doc = make_some_document();

let doc_str = write_document_to_string(&doc, OutputFormat::XWiki).unwrap();
println!("{}", doc_str);


Version 0.2.10

Added: use basic HTML output for tables in CommonMark.

Version 0.2.9

Fixed: using id macro for anchors in XWiki output.

Version 0.2.8

Fixed: trailing '|' removed from table rows for XWiki output.

Version 0.2.7

  • Testing: test the to_string and from_str functionality for OutputFormat.
    • OutputFormat now delegates the addition, and parsing, of flavors.

Version 0.2.6

  • Testing: better link testing.
  • Fixed: link output for non-XWiki markdown.
  • Fixed: link output for HTML.
  • Fixed: closed tag in HTML wasn't.
  • Fixed: XWiki writer didn't do line breaks correctly.
  • Fixed: XWiki line breaks.
  • Refactor: simplified Image to have path/inner and alt_text fields.
    • This reduced confusion with captions on links and images.
    • Added: helper functions and constructors to Image.
  • Added: Label::copy_from constructor.
  • Added: missing math and add_math functions from HasInlineContent.
  • Added: missing Into<BlockContent> for Math.

Version 0.2.5

  • Testing: added tests for labels, paragraph alignment, images, math, block quotes, and some text styles.
  • Testing: added tests for remaining markdown flavors.
  • Added: missing math and add_math functions for HasBlockContent trait.
  • Added: new preamble elements to correctly layout and caption equations.
  • Added: new FrontMatter enum for generated tables of content.
  • Added: new helper functions to Span.
  • Fixed: LaTeX writer had incorrect indentation for image blocks.
  • Fixed: HTML writer had incorrect indentation for image and math blocks.
  • Fixed: markdown writer swapping the markdown/xwiki format for block quotes.

Version 0.2.4

  • Fixed: bug in LaTeX writer emitting two \ref commands for internal references.
  • Fixed: bug in HTML writer which did not add id attributes for labels.
  • Fixed: bug in LaTeX writer not clearing table headings.
  • Fixed: bug in Label::is_valid matching spaces.

Version 0.2.3

  • Added: JSON writer
    • Added a feature fmt_json.
    • Added dependencies on serde and serde_json.
    • Also added a version field to the Document to allow for tool checking, this will be the crate version on write.
    • All structures now support Serialize/Deserialize for Serde
  • Added JSON reader using the same Serde support.

Version 0.2.2

  • Added: mostly complete API/library documentation.
  • Added: inner_impl macro for consistent use of inner and into_inner methods.
    • Refactor: this required renaming link to inner on Image.
  • Fixed: Duplicate From and from implementations on inline content.
  • Refactor: renamed label to text on model::block::table::Column.
  • Refactor: renamed Captioned trait to HasCaption for consistency.
  • Refactor: replaced Text with Caption as type for HyperLink caption; implemented HasCaption also.
  • Refactor: made definition lists only a single level, and the term is simply a String.
  • Refactor: removed constructors that only took a single value and use From<> instead in Caption, Code, Formatted, Heading, Image.
  • Refactor: renaming new_with_ functions to simply with_.
  • Refactor: removed ParagraphStyle, made alignment a single value property on Paragraph.
    • Moved the Alignment enum to its own module shared with Paragraph and table::Column.
    • Added new HasAlignment trait (and macro) for consistency between paragraph and column.
  • Clean-up: fixed all Clippy warnings.

Version 0.2.1

This is a significant update, some APIs will have changed, but the plan is that these new API forms will be stabilized toward a 0.3.0 release that can be relied on for non-breaking changes.

  • Added: additional features in the HTML writer. It should be complete pending testing.
  • Added: complete writer implementation for LaTeX. It should be complete pending testing.
  • Added: configuration features for each writer, fmt_html, fmt_latex, fmt_markdown`, etc. with the default feature including all of these.
  • Added: Writer, and ConfigurableWriter to the write module to capture the instantiation of a writer struct.
  • Added: more library/API documentation, but not all yet.
  • Refactor: combined all markdown-like formats into a common module.
  • Refactor: moved the Anchor type to a new Label, it is no longer a stand-alone inline value, but has been added as a property to most block types.
  • Refactor: moved Abstract out of the Metadata enum and made it a property of the document proper. This also affects the visitor API.
  • Refactor: renamed label/alt_text on HyperLink to caption.
  • Clean-up: made the document API easier, removing Result<> where it wasn't needed.
  • Clean-up: removed the unused dependency on log.
  • Testing: added dependency on pretty_assertions for better comparison of test failures.
  • Testing: creating test cases across formats.

Version 0.2.0

  • Added: new visitor traits and migrated the XWiki writer to use it.
  • Added: new HTML writer using the new visitor traits.
  • Added: new Math (inline), and MathBlock (block) constructs.
  • Added: new Caption type and implementation for Code, MathBlock, and Table.
  • Added: Deref for some String newtypes (Anchor, Caption, Emoji, and Text).
  • Testing: using proptest for the String newtypes listed above.

Version 0.1.7

  • Fixed: fixed a bug in HeadingLevel/markdown generation.

Version 0.1.6

  • Added: started on library documentation.
  • Added: model::inline::emoji_names module, but only enabled for emoji_names feature.
  • Added: readme_maker example, this is used in the README and lib.rs documentation.
  • Fixed: fixed a bug in XWiki write_code function.
  • Refactor: document metadata, and Markdown writer accordingly.
  • Refactor: renamed TextStyle -> SpanStyle, added Sized variant.
  • Clean-up: the read module as it was currently empty.
  • Clean-up: femoved the model::visitor module, too many changes to stabilize yet.
  • Testing: some initial test cases.

Version 0.1.5 (not published)

  • Added some more replacement rules for XWiki anchors.

Version 0.1.4

  • Moved the rules for formatting an Anchor into each writer.

Version 0.1.3

  • Added Formatted alongside CodeBlock.
  • Removed some additional blank lines from both Markdown and XWiki writers.

Version 0.1.2

  • Fixed nested list bug in XWiki writer.

Version 0.1.1

  • Added cargo-husky for git hooks.
  • Fixed bug in tables for XWiki writer.

Version 0.1.0

  • Initial commit. Basic model working, initial Markdown and XWiki writers.


~145K SLoC