Git Product home page Git Product logo

microdown's Introduction

Microdown Parser and Elements

Pharo

I'm a parser and object model for Microdown originally implemented by S. Ducasse, L. Dargaud and G. Polito. The implementation is based on the work on markdown of K. Osterbye. Further developments by S. Ducasse and K. Osterbye.

Microdown is a smaller markdown but it is more extensible. It contains a nice builder and some visitors. Microdown is now the default markup for the Pillar document compilation chain.

Why should you use Microdown?

Microdown is a smaller markdown but it is more extensible. It is used to produce books, slides, websites, doc. It can be read on github but also on pharo itself using the DocumentationBrowser

It supports

  • Header
  • Lists
  • Paragraph
  • Code with arguments: key=val&key2=val2 ...

But also

  • Environment with arguments
  • Table
  • Anchor
  • Annotated paragraph
  • Math with arguments
  • and more intra block elements such as extensible markups, raw, math, and references.

Microdown within the Pharo IDE.

Core Syntax in 2 seconds

   	# Header
        @anchor
	% This is line comment

	```language=Pharo&caption=Beautiful&label=Fig1
   	code
	```
   
   	![Pharo is cool .%anchor=fig:pharo&width=80](http://pharo.org)
	
   	- list
   	1. ordered list 

  	`in text` and for Pharo hyperlinks to class, method and package: 
  	`Point`, `Point class`, `Point>>#setX:setY:`, `#’Microdown-Tests’ (for packages)

  	References: *@ref@*
	

Full Syntax

Headers

Similar to markdown headers are composed of # space text on one line. The headers can be from 1 to 6.

### Header Level3

There is not support for other forms of declaration.

Anchors

In microdown we can define anchors and reference to them (see References). There are three ways to create anchors:

  • @anchorlabel will create an anchor to the preceeding element.
  • Figures, mathematical environments, environment can specify label as arguments (anchor)
  • Code block can specify label as argument (argument named anchor)

Various

  • % comments
  • *** horizontal line
  • File meta data is plain JSON
{
"date" : "12 december 2025"
}
  • Raw text
{{ raw text }}

Math support

  • $$ mathematical environment with label for easy referencing.
$$ %label=refToTheGreatEquation
V_i = C_0 - C_3 
$$
  • Math in text
'abc$	V_i = C_0 - C_3	$def'.

will generate LaTeX equivalent and can be referenced using *@refToTheGreatEquation@*

Codeblock

Microdown offer the same code block that markdown but arguments can be specified and the annotation should be named. The first line after the ``` can be language=pharo&label=code1&caption=this is my great piece of code

The following code is not able to display it because markdown quote block are strange and interpret nested block. So we cannot use quoteblock for quoting!

   ```language=pharo&anchor=code1&caption=this is my great piece of code
    codeBlockMarkupString
    ^ '```'
    ```
```language=pharo&anchor=code1&caption=this is my great piece of code
codeBlockMarkupString
   ^ '\`\`\`'
```

Extensions

  • {! aTag | parameters!} is the way to use an extension with parameters
  • Environments are defined using <!tag | parameters !>
<!agenda|title=International Workshop on Smalltalk Technologies

<!day|start=2023 August 29th&title=Monday

<!segment|start=10:30

<!talk|subject=Pharo DataFrame: Past, Present, and Future&length=30&author=Safina, Zaitsev, Ferlicot-Delbecque and Sow&room=Room B!>
<!talk|subject=Improving Performance Through Object Lifetime Profiling: the DataFrame Case&length=30&author=Jordan-Montaño, Palumbo, Polito, Ducasse and Tesone&room=Room B!> <!talk|subject=Garbage Collector Tuning in Pathological Allocation Pattern Applications&length=30&author=Palumbo, Jordan-Montaño, Polito, Tesone and Ducasse&room=Room B!>
!>
!>
!>
  • Citations {!citation|ref=Blac09a!} -- note that the bib file should be defined in the pillar.conf file

Known limits

Math should be tested

Quote block

When a line starts with '> ' it delimits a quoteblock. The markup is not interpreted.

Codeblock

Codeblock does not support more than four backticks.

Development in Pharo12!

Loading specific version

To load the latest stable version load the master. If you have trouble loading in latest Pharo just execute the preloading.st script in the .github folder. This script will remove the existing Microdown package and clear the system.

Metacello new
  baseline: 'Microdown';
  repository: 'github://pillar-markup/Microdown:master/src';
  load.

The process is the following:

  • Development in dev
  • When stable dev -> in master
  • When we can build books master is tagged.
  • Then there is the Pharo integration in dedicated branches.

Loading latest development version

Metacello new
	baseline: 'Microdown';
	repository: 'github://pillar-markup/Microdown:dev/src';
	onConflict: [ :ex | ex useIncoming ];
	onUpgrade: [ :ex | ex useIncoming ];
	load.

History

We have two sources: Pharo in one hand and Pillar and both are not totally synchronised.

Using Pharo 12: v2.5.x

  • v2.5.4 - add backward compatible anchor in caption + tonel V3 format

  • v2.5.1 - add LaTeX math with reference support for Pharo 12 and Pillar development up to v10.0.0

  • v2.4.2 for Pillar 9.0.1

Watch out v2.6.0 is older than v.2.5.4

Pillar History

For Pharo 12

  • v10.0.0 but with some links problems due to new inline parser using MD v2.5.0

For Pharo 11

  • v9.0.1 Fixing link problems.
  • v9.0.0 loading in Pharo 11. The development will now happen in P11.

For Pharo 10 -v8.3.2 fixed baseline and updated readme

Implementation

The parser follows the design mentioned in https://github.github.com/gfm, in particular the parsing strategy in appendix A.

In short, the strategy is that at any point in time, we might have a number of children of the root which are ""open"". The deepest in open in the tree is called ""current"". All the parents of current are open.

When a new line is read we do the following:

  1. Check if the new line can be consumed by current.
    • as part of this a child of current can be made which can consume the new line
  2. If current cannot consume the new line, we close current, move current to its parent, and repeat 1.
  3. The root node can consume anything, for instance by making new nodes for storing the new line.
  4. The root node is not closed until input is exhausted

The other packages in this repository are the extensions made to produce Pillar model. Such packages should be moved in the future to other location (probably pillar itself).

microdown's People

Contributors

astares avatar delgaylord avatar demarey avatar ducasse avatar estebanlm avatar gabriel-darbord avatar guillep avatar jecisc avatar kasperosterbye avatar laurinedargaud avatar leofrere avatar lgrangaud avatar marcusdenker avatar matburnx avatar melkiyasser avatar moufort avatar noha avatar olekscode avatar tesonep avatar tinchodias avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

microdown's Issues

Outdated baseline. Class comments are not rendering

When I create a new Pharo 9 image and load the baseline of Microdown, the class comments do not render. However, if I also install the baseline of Pillar, everything is OK. So it seems that some necessary packages of Pillar are igrored by Microdown's baseline.

"Change input syntax" in PEAR does not translate the input

I would expect the "Change input syntax" button in PEAR to translate between Pillar and Microdown. But it doesn't do that.
Instead, it deletes the text that was written in the editor and replaces it with a default Pillar or Microdown example.

So in fact, "Change input syntax" does what "Get example" should be doing

MicTableBloc does not work in comments!

To debug

renderComment: aString of: aClassOrPackage 

	| builder |
	builder := MicroDownParser builder.
	aClassOrPackage buildMicroDownUsing: builder withComment: aString.
	self flag: #fixMe.
	"I do not like the asText: the interaction between parser, richtext composer should be 
	more obvious"
	"^ [ MicroDownParser asText: builder contents ] on: MicParsingError, MessageNotUnderstood, SubclassResponsibility  do: [ builder contents  ]"
	
	^ MicroDownParser asText: builder contents

Support table with a simple and more relax setup than github.
A table is not forced to have a header definition.

| aaab | jkhjh |
| --- |
| bar |

or
|aaab|jkhjh|
|---|
|bar|

or
| aaa | bbb |
|ccc |ddd |

or
| aaa | bbb
| cc | ddd

Block-level elements cannot be inserted in a table.

When a table contains a header it is the first row and all rows should have that size else they are cut.

Known limits: how to put a pipe in a table?
No support for |

should revisit annotatedBlock

The following is strange

MicroDownParser parse: '!!note this is like that. Lists cannot be nested in annotated blocks.
But I can be expressed on multiple lines.

  1. one
  2. Two'

the annotated paragraph does not have children just a large text!

Feature request: Show warning before removing the unsaved text in PEAR

Here are some situations when everything you were writing can be gone:

  1. Close Pear window
  2. Press "New"
  3. Press "Change input syntax"
  4. Press "Show example"

It would be nice to show a warning in those cases: "If you leave before saving, your changes will be lost."
This issue is not critical, because in cases 2-4 you can still press Ctrl+Z and restore what you were writing

Add microdownBuilder

To hide markups from user.

  • Associate the builder to the parser.
  • Example
aBuilder codeBlock: kind withBody: str

instead of

parser codeblockMarkup, String cr, .....

supporting inliner non evaluation

Parser inline Microdown : rajouter le paramètre isEvaluated dans les inline blocks et changer le code en conséquence
monospace is not evaluated
reference are not evaluated
figures are only evaluated on caption

Metadata should be more robust

right now

{ "title" : "Pharo by Example" }

has an empty body while

{
"title" : "Pharo by Example"
}

works

Given the line based structure of microdown.
we could accept


{ "title" : "Pharo by Example",
 "title2" : "A cool book"
}

But after all the following is much better.

{ 
"title" : "Pharo by Example",
"title2" : "A cool book"
}

The Preview window in PEAR should not be editable

In Pear, we write the Microdown or Pillar text on the left and then Render it into a formatted preview on the right.
I think that the Preview should not be editable because it's not possible to save the changes or to update the code based on the changes in the Preview.

"Save" button in PEAR raises an exception

Steps to reproduce:

  1. Create a new Pharo 9 image
  2. Open Tools > Pear
  3. Press "Change input syntax"
  4. Press "New". You will get an empty editor
  5. Type some Microdown text
  6. Press "Render". You should see the correctly rendered output on the right
  7. Press "Save". And BOOM!

Screenshot 2020-07-21 at 13 06 36

Feature request: Keyboard shortcuts in PEAR

When writing text in the editor, it is really handy to have keyboard shortcuts for the basic operations such as "Save" and "Render". However, I think that other options should be supplied with shortcuts as well ("New", "Open" etc.)

Why is it important:

  1. It saves time
  2. It makes sure that you don't lose your thought when you write
  3. It encourages to Render and Save often

The standard editor shortcuts Ctrl+S, Ctrl+N, Ctrl+O, Ctrl+T (Cmd+S, Cmd+N, Cmd+O, Cmd+T) are already used in Pharo.
I don't know if it's possible to redefine them for the case when PEAR window is in focus.
If yes - that would be great!

Support for YAML metadata blocks

I'm really glad to see microdown as a bridge between (a variant of a) Markdown syntax in the surface and the Pillar machinery in the back end, as it could lower/end the Grafoscopio reliance on external dependencies (ie. Pandoc, Lunamark) for markup conversions between Markdown and HTML/LaTeX/PDF. Thanks for microdown.

Several Markdown variants have adopted YAML metadata block (gfm shows them as tables, Zettlr, Pandoc, Jeykill and other static site generators use it to define even operations and properties of the exported documents once they become LaTeX, HTML and so on). Such blocks are at the beginning of the document containing between --- the document metadata, like this:

---
name: example
context:
  - type: feature request.
  - url: https://github.com/pillar-markup/MicroDown/issues/57
--- 

Can YAML metadata blocks support be added to microdown (or as a plugin), so YAML inside a microdown text can be converted to (Ordered) dictionaries in Pharo?

Thanks again.

Problem with backslashes in math environments

Backslashes \ are very important in math environments, but Microdown removes them.
So they have to be escaped, which is very annoying and breaks the compatibility of Microdown math with standard LaTeX math.

For example, in LaTeX I would write

$ f(a) = \frac{1}{2\pi i} \oint_{\gamma} \frac{f(z)}{z - a} dz $

and get this:
ComplicatedEquation

But in Microdown it doesn't work:
Screenshot 2020-07-07 at 00 29 42

What I have to do then is escape all backslashes. Like this:

$ f(a) = \\frac{1}{2\\pi i} \\oint_{\\gamma} \\frac{f(z)}{z - a} dz $

Then everything is fine:
Screenshot 2020-07-07 at 00 35 26

But it would be great if backslashes were not captured in math environments.

Add more math examples to the code comment of MicMathInlineBlock

Here are the lines that can be added:

Here are several examples:

#### Example 1
Code: `$V_i = C_0 - C_3$`

$V_i = C_0 - C_3$

#### Example 2
Code: `$a^2 + b^2 = c^2$`

$a^2 + b^2 = c^2$

#### Example 3
Code: `$\\sin(x) = \\sum_{n=0}^{\\infty} \\frac{(-1)^{n}x^{2n+1}}{(2n+1)!}$`

$\\sin(x) = \\sum_{n=0}^{\\infty} \\frac{(-1)^{n}x^{2n+1}}{(2n+1)!}$

#### Example 4
Code: `$f(a) = \\frac{1}{2\\pi i} \\oint_{\\gamma} \\frac{f(z)}{z - a} dz$`

$f(a) = \\frac{1}{2\\pi i} \\oint_{\\gamma} \\frac{f(z)}{z - a} dz$

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.