{"id":15107593,"url":"https://github.com/pillar-markup/microdown","last_synced_at":"2025-04-07T07:08:13.561Z","repository":{"id":37387987,"uuid":"264301421","full_name":"pillar-markup/Microdown","owner":"pillar-markup","description":"Microdown is a cleaned and simpler markdown but with more powerful features such as extensions.","archived":false,"fork":false,"pushed_at":"2025-03-30T19:22:18.000Z","size":5851,"stargazers_count":41,"open_issues_count":139,"forks_count":36,"subscribers_count":8,"default_branch":"dev","last_synced_at":"2025-04-05T04:54:04.190Z","etag":null,"topics":["document","markdown","parser","pharo"],"latest_commit_sha":null,"homepage":"","language":"Smalltalk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pillar-markup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-15T21:20:46.000Z","updated_at":"2025-03-30T19:22:21.000Z","dependencies_parsed_at":"2023-10-10T18:12:08.803Z","dependency_job_id":"6468de55-4b42-4041-a8e9-75800fa0f7bb","html_url":"https://github.com/pillar-markup/Microdown","commit_stats":{"total_commits":2522,"total_committers":24,"mean_commits":"105.08333333333333","dds":0.6157811260904045,"last_synced_commit":"a2e06efb46b17d30635de4eab3a6e0d0c65a04d0"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pillar-markup%2FMicrodown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pillar-markup%2FMicrodown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pillar-markup%2FMicrodown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pillar-markup%2FMicrodown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pillar-markup","download_url":"https://codeload.github.com/pillar-markup/Microdown/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608151,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document","markdown","parser","pharo"],"created_at":"2024-09-25T21:25:50.084Z","updated_at":"2025-04-07T07:08:13.535Z","avatar_url":"https://github.com/pillar-markup.png","language":"Smalltalk","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Microdown Parser and Elements\n\n\u003ca href=\"https://www.pharo.org\"\u003e\n    \u003cimg alt=\"Pharo\" src=\"https://img.shields.io/static/v1?style=for-the-badge\u0026message=Pharo\u0026color=3297d4\u0026logo=Harbor\u0026logoColor=FFFFFF\u0026label=\" /\u003e\n\u003c/a\u003e\n\nI'm a parser and object model for Microdown originally implemented by S. Ducasse, L. Dargaud and G. Polito. \nThe implementation is based on the work on markdown of K. Osterbye. \nFurther developments by S. Ducasse and K. Osterbye. \n\nMicrodown is a smaller markdown but it is more extensible. It contains a nice builder and some visitors. \nMicrodown is now the default markup for the Pillar document compilation chain. \n\n\n## Why should you use Microdown?\n\nMicrodown is a smaller markdown but it is more extensible.\nIt is used to produce books, slides, websites, doc.\nIt can be read on GitHub but also on Pharo itself using the DocumentationBrowser\n\nIt supports\n- Header\n- Lists\n- Paragraph\n- Code with arguments: key=val\u0026key2=val2\n...\n\nBut also \n- Environment with arguments\n- Table\n- Anchor\n- Annotated paragraph\n- Math with arguments\n- and more intra-block elements such as extensible markups, raw, math, and references.\n\n\n![Microdown within the Pharo IDE.](screen.png)\n\n\n## Core Syntax in 2 seconds\n\n```\n   \t# Header\n        @anchor\n\t% This is a line comment\n\n\t```language=Pharo\u0026caption=Beautiful\u0026label=Fig1\n   \tcode\n\t```\n   \n   \t![Pharo is cool .%anchor=fig:pharo\u0026width=80](http://pharo.org)\n\t\n   \t- list\n   \t1. ordered list \n\n  \t`in text` and for Pharo hyperlinks to class, method and package: \n  \t`Point`, `Point class`, `Point\u003e\u003e#setX:setY:`, `#’Microdown-Tests’ (for packages)\n\n  \tReferences: *@ref@*\n\t\n```\n\n## Full Syntax\n\n### Headers\nSimilar to markdown headers are composed of `#` space text on one line.\nThe headers can be from 1 to 6.\n\n```\n### Header Level3\n```\nThere is no support for other forms of declaration. \n\n### Anchors\nIn Microdown we can define anchors and reference to them (see References).\nThere are three ways to create anchors:\n\n- `@anchorlabel` will create an anchor to the preceding element. \n- Figures, mathematical environments, and environment can specify labels as arguments (`anchor`)\n- Code block can specify label as argument (argument named `anchor`)\n\n### Various\n\n- % comments\n- *** horizontal line\n- File metadata is plain JSON\n\n```\n{\n\"date\" : \"12 december 2025\"\n}\n```\n- Raw text\n```\n{{ raw text }}\n```\n### Math support\n\n- `$$` mathematical environment with a label for easy referencing.\n\n```\n$$ %label=refToTheGreatEquation\nV_i = C_0 - C_3 \n$$\n```\n- Math in text\n\n```\n'abc$\tV_i = C_0 - C_3\t$def'.\n```\nwill generate a LaTeX equivalent and can be referenced using `*@refToTheGreatEquation@`*\n\n### Codeblock\n\nMicrodown offers 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\u0026label=code1\u0026caption=this is my great piece of code`\n\nThe following code is not able to display it because markdown quote blocks are strange and interpret nested blocks. So we cannot use quoteblock for quoting!\n\n``` \n   ```language=pharo\u0026anchor=code1\u0026caption=this is my great piece of code\n    codeBlockMarkupString\n    ^ '```'\n    ```\n```\n````\n```language=pharo\u0026anchor=code1\u0026caption=this is my great piece of code\ncodeBlockMarkupString\n   ^ '\\`\\`\\`'\n```\n````\n\n\n### Extensions\n\n- `{! aTag | parameters!}` is the way to use an extension with parameters\n- Environments are defined using `\u003c!tag | parameters !\u003e`\n\n```\n\u003c!agenda|title=International Workshop on Smalltalk Technologies\n\n\u003c!day|start=2023 August 29th\u0026title=Monday\n\n\u003c!segment|start=10:30\n\n\u003c!talk|subject=Pharo DataFrame: Past, Present, and Future\u0026length=30\u0026author=Safina, Zaitsev, Ferlicot-Delbecque and Sow\u0026room=Room B!\u003e\n\u003c!talk|subject=Improving Performance Through Object Lifetime Profiling: the DataFrame Case\u0026length=30\u0026author=Jordan-Montaño, Palumbo, Polito, Ducasse and Tesone\u0026room=Room B!\u003e \u003c!talk|subject=Garbage Collector Tuning in Pathological Allocation Pattern Applications\u0026length=30\u0026author=Palumbo, Jordan-Montaño, Polito, Tesone and Ducasse\u0026room=Room B!\u003e\n!\u003e\n!\u003e\n!\u003e\n```  \n- Citations `{!citation|ref=Blac09a!}` -- note that the bib file should be defined in the pillar.conf file\n\n\n## Known limits\n\n#### Math should be tested\n\n#### Quote block\nWhen a line starts with '\u003e ' it delimits a quoteblock.\nThe markup is not interpreted. \n\n#### Codeblock \nCodeblock does not support more than four backticks.\n\n\n## Development in Pharo 13!\n\n### Loading specific version\n\nTo load the latest stable version load the master. If you have trouble loading in the latest Pharo just execute the preloading.st script in the .github folder. This script will remove the existing Microdown package and clear the system.\nYou can also execute the script provided below. \n\n\n```Smalltalk\nMetacello new\n  baseline: 'Microdown';\n  repository: 'github://pillar-markup/Microdown:v2.7.2/src';\n  load.\n```\n\nThe process is the following:\n- Development happens dev.\n- When stable dev -\u003e in master.\n- When we can build books master is tagged.\n- Then there is the Pharo integration in dedicated branches.\n\n\n### Loading the latest development version\n\nThe following script loads all groups in the Baseline:\n\n```Smalltalk\n#( 'Microdown' 'BeautifulComments' 'DocumentBrowser' ) do: [ :name |\n        (IceRepository repositoryNamed: name)\n            ifNil: [ self inform: 'Project not found: ' , name ]\n            ifNotNil: [ :found |\n                found\n                    unload;\n                    forget ] ].\n\nSmalltalk globals\n\tat: #BaselineOfMicrodown \n\tifPresent: [ :c | c removeFromSystem ].\n\nMetacello new\n\tbaseline: 'Microdown';\n\trepository: 'github://pillar-markup/Microdown:dev/src';\n\tonConflict: [ :ex | ex useIncoming ];\n\tonUpgrade: [ :ex | ex useIncoming ];\n\tload: #('All').\n ```\n\n## History\n\nWe have two sources: Pharo in one hand and Pillar and both are not totally synchronized. \n\n\nUsing Pharo 13: v2.7.x\n-  v2.7.2 merge pharo 13 changes / added gitbridge / OCompiler migration / cleaning syntax description / Ready for Pillar and Foliage\n-  v2.7.1 LatexQuoteblock-should-not-use-verbatim\n-  v2.7.0 Fix some errors and API/clients of the textualbuilder\n\n\nUsing Pharo 12: v2.5.x\n- v2.5.6 - Change html visitor and test for annotated paragraph\n- v2.5.5 - add support for top-level header as slide definition\n- v2.5.4 - add backward compatible anchor in caption + tonel V3 format\n- v2.5.1 - add LaTeX math with reference support for Pharo 12 and Pillar development up to v10.0.0\n\n- v2.4.2 for Pillar 9.0.1\n\nWatch out v2.6.0 is older than v.2.5.4\n\n### Pillar History\nFor Pharo 12\n- v10.0.0 but with some links problems due to new inline parser using MD v2.5.0\n\nFor Pharo 11\n- v9.0.1 Fixing link problems.\n- v9.0.0 loading in Pharo 11. The development will now happen in P11.\n\nFor Pharo 10\n-v8.3.2 fixed baseline and updated readme\n\n\n## Implementation\nThe parser follows the design mentioned in [https://github.github.com/gfm](https://github.github.com/gfm), in particular the parsing strategy in Appendix A.\n\nIn short, the strategy is that at any point in time, we might have several children of the root which are \"\"open\"\". The deepest in open in the tree is called \"\"current\"\". All the parents of the current are open. \n\nWhen a new line is read we do the following:\n\n1. Check if the new line can be consumed by current.\n\t- as part of this a child of current can be made which can consume the new line\n2. If current cannot consume the new line, we close current, move current to its parent, and repeat 1.\n3. The root node can consume anything, for instance by making new nodes for storing the new line.\n4. The root node is not closed until input is exhausted\n\nThe other packages in this repository are the extensions made to produce Pillar model. \nSuch packages should be moved in the future to other locations (probably pillar itself).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpillar-markup%2Fmicrodown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpillar-markup%2Fmicrodown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpillar-markup%2Fmicrodown/lists"}