# \[ANN\] MarkdownAST.jl: abstract syntax trees of Markdown documents

**URL:** <https://discourse.julialang.org/t/ann-markdownast-jl-abstract-syntax-trees-of-markdown-documents/87861>\
**Category:** Package Announcements\
**Created:** [September 27, 2022, 6:12am UTC](https://discourse.julialang.org/t/ann-markdownast-jl-abstract-syntax-trees-of-markdown-documents/87861 "2022-09-27T06:12:15Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [September 27, 2022, 6:12am UTC](https://discourse.julialang.org/t/ann-markdownast-jl-abstract-syntax-trees-of-markdown-documents/87861/1 "2022-09-27T06:12:15Z")

</div>

Motivated by the desire to have a better representation of Markdown documents in Julia for Documenter, I am happy to announce a package for working with Markdown [abstract syntax trees (ASTs)](https://en.wikipedia.org/wiki/Abstract_syntax_tree).

> **[GitHub - JuliaDocs/MarkdownAST.jl: Abstract syntax tree representation of...](https://github.com/JuliaDocs/MarkdownAST.jl)**
>
> Abstract syntax tree representation of Markdown documents in Julia - GitHub - JuliaDocs/MarkdownAST.jl: Abstract syntax tree representation of Markdown documents in Julia

Its goal is to provide an API for working with Markdown ASTs and also to function as a relatively lightweight interface package for sharing Markdown trees between different packages (like parsers and document generators).

To give a sense of what the package does, the following small Markdown document

```markdown
# Markdown document

Hello [world](https://example.com/)!

```

can be constructed as the following tree using the [MarkdownAST `@ast` macro DSL](https://juliadocs.github.io/MarkdownAST.jl/stable/astmacro/#MarkdownAST.@ast)

```julia
using MarkdownAST: @ast, Document, Heading, Paragraph, Link
@ast Document() do
    Heading(1) do
        "Markdown document"
    end
    Paragraph() do
        "Hello "
        Link("https://example.com/", "") do
            "world"
        end
        "!"
    end
end

```

Each node of the tree is a [`Node`](https://juliadocs.github.io/MarkdownAST.jl/stable/node/#MarkdownAST.Node) object that wraps an [_element_](https://juliadocs.github.io/MarkdownAST.jl/stable/elements/) (giving each node its semantic meaning; like `Link` or `Paragraph`) and references other `Node`s (parent, sibling, and child nodes). Unlike the `Markdown` standard library AST, this provides a type-stable way of traversing ASTs, and it also implements the [AbstractTrees.jl](https://github.com/JuliaCollections/AbstractTrees.jl) interface.

- A lot of the core design is derived from @mike’s [CommonMark.jl](https://github.com/MichaelHatherly/CommonMark.jl) (in large parts, I just documented the design and added additional APIs for working with the trees). Currently, MarkdownAST is staying pretty close to CommonMark, and once MarkdownAST is stable, I hope we can switch CommonMark over to it internally.
- The package can also [convert to and from the `Markdown` standard library AST](https://juliadocs.github.io/MarkdownAST.jl/stable/stdlib/).
- The current API is preliminary, and there will likely be a few breaking iterations to it. With that in mind, I would be very keen to get feedback on the design from anyone who might want to use MarkdownAST — please do open an [issue](https://github.com/JuliaDocs/MarkdownAST.jl/issues) (or a PR), or chime in on some of the existing ones.
- In the long run, I hope this package is a step towards replacing the current `Markdown` standard library (see also [JuliaLang/julia#37337](https://github.com/JuliaLang/julia/issues/37337)).

Finally, I would like to acknowledge the funding from the Julia project (via NumFOCUS) that enabled this work!