Lexer and friends

.github/workflows/check.yml

@@ -79,7 +79,7 @@ jobs:
     # https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
     strategy:
       matrix:
-        msrv: [1.67.1] #version at the moment of creation 
+        msrv: [1.80.0] # due to Option::take_if usage
     name: ubuntu / ${{ matrix.msrv }}
     steps:
       - uses: actions/checkout@v4

Cargo.toml

@@ -1,17 +1,17 @@
 [package]
 name = "yamd"
-version = "0.13.3"
+description = "Yet Another Markdown Document (flavour)"
+version = "0.14.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
-description = "Yet Another Markdown Document (flavor)"
 repository = "https://github.com/Lurk/yamd"
 readme = "README.md"
 keywords = ["markdown", "parser"]
 
+[dependencies]
+serde = { version = "1.0.197", features = ["derive"] }
+
 [dev-dependencies]
 pretty_assertions = "1.4.0"
 
-[dependencies]
-serde = { version = "1.0.197", features = ["derive"] }
-chrono = { version = "0.4.37", features = ["serde"] }
-serde_yaml = "0.9.34"
+

readme.md

@@ -1,42 +1,73 @@
-# Yet another markdown document flavour (YAMD)
+# yamd
+
 [![codecov](https://codecov.io/gh/Lurk/yamd/branch/main/graph/badge.svg?token=F8KRUYI1AA)](https://codecov.io/gh/Lurk/yamd)
 [![crates.io](https://img.shields.io/crates/v/yamd.svg)](https://crates.io/crates/yamd)
 [![Released API docs](https://docs.rs/yamd/badge.svg)](https://docs.rs/yamd)
 
-## Status
+<!-- cargo-rdme start -->
+
+YAMD - Yet Another Markdown Document (flavour)
+
+Simplified version of [CommonMark](https://spec.commonmark.org/).
+
+For formatting check YAMD struct documentation.
+
+## Reasoning
+
+Simplified set of rules allows to have simpler, more efficient, parser and renderer.
+YAMD does not provide render functionality, instead it is a [serde]
+serializable structure that allows you to write any renderer for that structure. All HTML
+equivalents in this doc are provided as an example to what it can be rendered.
+
+## Difference from CommonMark
+
+### Escaping
+
+Escaping done on a [lexer] level. Every symbol following the `\` symbol will be treated as a
+literal.
+
+Example:
+
+| YAMD      | HTML equivalent |
+|-----------|-----------------|
+| `\**foo**`|`<p>**foo**</p>` |
+
+### Escape character
+
+To get `\` - `\\` must be used.
+
+Example:
 
-It is not ready to poke around. There is significant API changes expected.
+| YAMD          | HTML equivalent       |
+|---------------|-----------------------|
+| `\\**foo**`   |`<p>\<b>foo</b></p>`   |
 
-## Why?
 
-Initial idea was to create human readable text format for my blog. Why not existing flavour? 
-Existing flavours do not have elements like image gallery, dividers, highlight, etc. 
+### Precedence
 
-## Features
+[CommonMark](https://spec.commonmark.org/0.31.2/#precedence) defines container blocks and leaf
+blocks. And that container block indicator has higher precedence. YAMD does not discriminate by
+block type, every node (block) is the same. In practice, there are no additional rules to encode
+and remember.
 
-Deserialize markdown to YAMD struct, Serialize YAMD struct to markdown.
+Example:
 
-## Example
+| YAMD                  | HTML equivalent                               |
+|-----------------------|-----------------------------------------------|
+| ``- `one\n- two` ``   | `<ol><li><code>one\n- two</code></li></ol>`   |
 
-```rust
-use yamd::{deserialize, serialize};
-let input = r#"---
-title: YAMD documnet showcase
-date: 2023-08-13T15:42:00+02:00
-preview: here is how you can serialize ande deserialize YAMD document
-tags: 
-- yamd
-- markdown
----
 
-# This is a new Yamd document
+If you want to have two ListItem's use escaping:
 
-Check out [documentation](https://docs.rs/yamd/latest/yamd/) to get what elements **Yamd** format supports.
+| YAMD                      | HTML equivalent                           |
+|---------------------------|-------------------------------------------|
+| ``- \`one\n- two\` ``     | ``<ol><li>`one</li><li>two`</li><ol>``    |
 
-"#;
-let yamd = deserialize(input).unwrap();
-let output = serialize(&yamd);
-```
+The reasoning is that those kind issues can be caught with tooling like linters/lsp. That tooling
+does not exist yet.
 
+### Nodes
 
+List of supported [nodes](https://docs.rs/yamd/latest/yamd/nodes/) and their formatting slightly defers from CommonSpec.
 
+<!-- cargo-rdme end -->