Skip to content

Commit

Permalink
Merge pull request #61 from Lurk/lexer
Browse files Browse the repository at this point in the history
Lexer and friends
  • Loading branch information
Lurk authored Sep 28, 2024
2 parents 2bb2698 + eee3666 commit be5e351
Show file tree
Hide file tree
Showing 47 changed files with 4,301 additions and 3,013 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"

81 changes: 56 additions & 25 deletions readme.md
Original file line number Diff line number Diff line change
@@ -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 -->
Loading

0 comments on commit be5e351

Please sign in to comment.