63 lines
2.1 KiB
Markdown
63 lines
2.1 KiB
Markdown
# YAMD
|
|
|
|
Indentation-based markup language that compiles to HTML via Ruby codegen.
|
|
|
|
## Syntax
|
|
|
|
Structure is defined by indentation (tabs). Lines at a given indent level belong to the enclosing directive.
|
|
|
|
### Directives (line-start only)
|
|
|
|
| Syntax | Description |
|
|
|--------|-------------|
|
|
| `#% <ruby code>` | Metadata / Ruby statement. e.g. `#% meta "date", "2025 01 01"` |
|
|
| `#! <expr>` | Block wrapper. Evaluates `expr` as a Ruby method call, content is passed as a block. e.g. `#! tag('h1')` |
|
|
| `#$ <expr>` | Raw block. Like `#!` but inner lines are passed as a raw string (no YAMD parsing). Used for code blocks. e.g. `#$ code` |
|
|
| `#. ` | List item. Must appear inside a `#! list(...)` block |
|
|
|
|
### Inline constructs
|
|
|
|
| Syntax | Description |
|
|
|--------|-------------|
|
|
| `` #`...` `` | Inline code |
|
|
| `#{expr}` | Ruby expression interpolation (result converted to string) |
|
|
| `#(expr)` | Inline math (AsciiMath, rendered to MathML) |
|
|
| `#name(args)` | Method call. e.g. `#link("url")` |
|
|
| `#name(args)#{ content }#` | Method call with content block. e.g. `#link("url")#{ click here }#` |
|
|
| `##` | Escaped literal `#` |
|
|
| `}#` | Closes a `#{` content block |
|
|
|
|
### Comments
|
|
|
|
Lines matching `#` followed by nothing or a space (i.e. `#` or `# ...`) are comments and are skipped.
|
|
|
|
### Available renderer methods
|
|
|
|
These are defined by `HTMLRenderer` in `exe/yamd`:
|
|
|
|
| Method | Usage |
|
|
|--------|-------|
|
|
| `tag(name, **attrs)` | HTML element. `#! tag('h2')` |
|
|
| `list(numbering)` | List. numbering: `"-"` (ul), `"1"`, `"a"`, `"A"`, `"i"`, `"I"` (ol). Dot-separated for nested: `"-.1"` |
|
|
| `link(url)` | Anchor tag. `#link("https://example.com")#{ text }#` |
|
|
| `code(lang: Lang::DEFAULT)` | Code block (used via `#$`). Optional `lang:` for highlighting rules |
|
|
| `meta(name, value)` | HTML `<meta>` tag. Used via `#%` |
|
|
| `inline_code(text)` | Inline `<code>`. Used via `` #`...` `` |
|
|
| `inline_math(text)` | AsciiMath to MathML. Used via `#(...)` |
|
|
|
|
### Example
|
|
|
|
```
|
|
#% meta "date", "2025 01 01"
|
|
|
|
#! tag('h1')
|
|
Title
|
|
|
|
Paragraph text with #`inline code` and #link("https://example.com")#{ a link }#.
|
|
|
|
#! list('-')
|
|
#. First item
|
|
#. Second item with sub-content
|
|
#$ code
|
|
x = 1
|
|
```
|