From 26e89b8bfb7f4a6a2f28f5f42f0773cb9e07103b Mon Sep 17 00:00:00 2001 From: Giorgio Garofalo Date: Tue, 9 Jul 2024 00:13:09 +0200 Subject: [PATCH] Update README.md --- README.md | 256 ++++++++++++++++++++++++++---------------------------- 1 file changed, 125 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index e1e47b25..c6223dc7 100644 --- a/README.md +++ b/README.md @@ -1,155 +1,149 @@ # Quarkdown -Quarkdown is a work-in-progress markup language to create documents with the minimalism and straightforwardness of Markdown, -while allowing full control over the structure and style of the document that LaTeX provides via a Turing complete, dynamically typed scripting engine. +Quarkdown is a Markdown parser and renderer that extends the capabilities of CommonMark and GFM with its own *Quarkdown +flavor*. + +The standout feature the flavor introduces is its support for **functions**, allowing users to access an +extensive [standard library](stdlib/src/main/kotlin/eu/iamgio/quarkdown/stdlib), use conditional statements and loops, +define new functions and variables - all within Markdown. + +This out-of-the-box scripting support opens doors to complex and dynamic content that would be otherwise impossible +to achieve with vanilla Markdown. + +## Comparison + +| | Markdown | LaTeX | Quarkdown | +|-----------------------|:------------------:|:------------------:|:------------------:| +| Concise and readable | :white_check_mark: | :x: | :white_check_mark: | +| Full document control | :x: | :white_check_mark: | :white_check_mark: | +| Scripting | :x: | :x: | :white_check_mark: | + + + + + + + + + + + + + + +
LaTeXQuarkdown
+ +```latex +\section{Section} +\subsection{Subsection} +\begin{enumerate} + \item \textbf{First} item + \item \textbf{Second} item +\end{itemize} +\begin{center} + This text is \textit{centered}. +\end{center} +``` -The base Markdown parsing is CommonMark-compliant, along with several GFM extensions. + -## Overview +```markdown +# Section -### Basics -CommonMark/GFM Markdown is (almost) 100% supported. Along with it, Quarkdown's flavor introduces the following: +## Subsection -- Math span - `$ \LaTeX expression $` +1. **First** item +2. **Second** item -- Math block - ``` - $$$ - \LaTeX expression - $$$ - ``` - -- Image size specification: - - `!(150x100)[label](/url.png)` (manual width and height) - - `!(150x_)[label](/url.png)` (manual width, automatic height, keeps the aspect ratio) - - `!(_x100)[label](/url.png)` (automatic width, manual height, keeps the aspect ratio) - - -- Functions: - - `.func` - - `.func {arg1} {arg2}` - - ``` - .func {arg1} {arg2} - This is some nested body content. - ``` - -### Scripting -_Block function calls_, opposite to _inline function calls_, also support a _body_ argument, -which is some nested and indented Quarkdown content. - -The following snippets are valid Quarkdown sources that calculate and display the first 8 numbers of the Fibonacci sequence: -- Iterative: - ```markdown - .var {t1} {0} - .var {t2} {1} - - .table - .foreach {..8} - | $ F_{.1} $ | - |:-------------:| - | .t1 | - .var {tmp} {.sum {.t1} {.t2}} - .var {t1} {.t2} - .var {t2} {.tmp} - ``` -- Recursive: - ```markdown - .function {fib} - num: - .if { .islower {.num} than:{2} } - .num - .ifnot { .islower {.num} than:{2} } - .sum { - .fib { .subtract {.num} {1} } - } { - .fib { .subtract {.num} {2} } - } - - .table - .foreach {..7} - | $ F_{.1} $ | - |:------------:| - | .fib {.1} | - ``` +.center + This text is _centered_. +``` -Output: +
-| $F_0$ | $F_1$ | $F_2$ | $F_3$ | $F_4$ | $F_5$ | $F_6$ | $F_7$ | -|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:| -| 0 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | +## Targets -## Goals +HTML is currently the only supported rendering target. LaTeX rendering is a future goal. -This is an example of what Quarkdown aims to look like: -```markdown -.docname {Quarkdown} -.docauthor {iamgio} -.aspectratio {4:3} +- **HTML** + - :white_check_mark: Plain output (default) + - :white_check_mark: Slides (via [reveal.js](https://revealjs.com)) + - :white_check_mark: Paged (book) (via [paged.js](https://revealjs.com)) -.tableofcontents <-- Generates a table of contents page - that contains "Hello Quarkdown" - and "Extended Markdown" +The desired document type can be set by calling the `.doctype` function within the Markdown source itself: +- `.doctype {slides}` +- `.doctype {paged}` -# Hello Quarkdown +> [!NOTE] +> Make sure to set the output directory in order to save the output to file. +> This can be done by setting the command line argument `--out ` or `-o `. -## An overview +## Scripting -.box {Box title} - This is some text within a box. - 1. And this - 2. is a - 3. Markdown list +
+Iterative Fibonacci -.center - This content is **centered**! - ![An image](img.png) +``` +.var {t1} {0} +.var {t2} {1} + +.table + .foreach {0..8} + n: + | $ F_{.n} $ | + |:----------:| + | .t1 | + .var {tmp} {.sum {.t1} {.t2}} + .var {t1} {.t2} + .var {t2} {.tmp} +``` + +| $F_0$ | $F_1$ | $F_2$ | $F_3$ | $F_4$ | $F_5$ | $F_6$ | $F_7$ | $F_8$ | +|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:| +| 0 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | -# Extended Markdown +
-Quarkdown's custom Markdown flavor introduces new blocks as well! +
+Recursive Fibonacci -$ This is a LaTeX expression $ +> The recursive approach is significantly slower than the iterative one. ``` +.function {fib} + n: + .if { .islower {.n} than:{2} } + .n + .ifnot { .islower {.n} than:{2} } + .sum { + .fib { .subtract {.n} {1} } + } { + .fib { .subtract {.n} {2} } + } + +.table + .foreach {0..8} + | $ F_{.1} $ | + |:----------:| + | .fib {.1} | +``` + +| $F_0$ | $F_1$ | $F_2$ | $F_3$ | $F_4$ | $F_5$ | $F_6$ | $F_7$ | $F_8$ | +|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:| +| 0 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | + +
## Status -The project is under development. Currently supported: - -- Base Markdown blocks - - [x] Paragraphs - - [x] Headings - - [x] Code - - [x] Quotes - - [x] Lists (+ GFM tasks) - - [x] Horizontal lines - - [x] Link references - - [x] GFM tables - - [ ] GFM footnotes - -- Base Markdown inline - - [x] Text - - [x] Links - - [x] Reference links - - [x] Autolinks (+ GFM extension) - - [x] Images - - [x] Reference images - - [x] Comments - - [x] Emphasis - - [x] Code spans - - [x] GFM strikethrough - -- Quarkdown features - - [x] Functions - - [ ] Styles - - [x] Math (LaTeX) blocks and inlines - - [ ] Highlight - - [ ] Subscript/superscript - -- Rendering - - [x] HTML - - [ ] LaTeX - -- Misc - - GUI (with dynamic hot reload) \ No newline at end of file +The project is under active development. + +#### Future plans + +- Wiki, getting started guides and tutorials +- New themes +- Contribution guidelines +- Auto-generated stdlib documentation ([Dokka](https://github.com/Kotlin/dokka) custom plugin) +- External libraries support +- LaTeX rendering +- GUI editor / IDE plugin \ No newline at end of file