How to sort sections of markdown by heading?

Question

Given a large markdown file with a structure like:

# Main

## Sub main Z
### Title Z
Content Z
### Title B
Content B

## Sub main A
### Title A
Content A

How would one sort its sections so that they are in alphabetical order by heading?

# Main

## Sub main A
### Title A
Content A

## Sub main Z
### Title B
Content B
### Title Z
Content Z

Answer 1

I don't think there is any solution that does not require you to write some code.

But the programmatic solution is pretty easy if you can code:

1. Parse the Markdown into an AST (abstract syntax tree).
2. Manipulate the AST, reordering nodes as you want.
3. Write the modified AST back to Markdown.

The trick is choosing a Markdown parser that supports the above steps, that lets you do it in the language of your choice, and that lets you do it most easily.

Here are the ones that I personally know that meet these requirements:

Pandoc

Probably the number one Markdown toolkit in the world. Pandoc's native language is Haskell, but it supports many languages. If you're going to do a lot of Markdown stuff down the road, it probably makes sense to become knowledgable in Pandoc anyway.

• It has an option, --section-divs, that converts the document into a section hierarchy based on headings, which will make resorting sections at every nesting level almost trivial (if you can code).

• It has support for filters, which are exactly the solution I am describing.

• It has special support for Lua and Lua filters, which might be the easiest to code.

• You can also write filters in other languages: Python, PHP, Perl, Javascript/Typescript, Groovy, Ruby.

• A quick web search shows many example filters. With some more searching you might get lucky and find one that does what you want already written, though I doubt it as sorting sections alphabetically seems an uncommon thing to do.

CMark

The C reference implementation of CommonMark. Languages other than C are supported:

It provides a shared library (libcmark) with functions for parsing CommonMark documents to an abstract syntax tree (AST), manipulating the AST, and rendering the document to HTML, groff man, LaTeX, CommonMark, or an XML representation of the AST. It also provides a command-line program (cmark) for parsing and rendering CommonMark documents.

• Flexible. CommonMark input is parsed to an AST which can be manipulated programmatically prior to rendering.
• Multiple renderers. Output in HTML, groff man, LaTeX, CommonMark, and a custom XML format is supported. And it is easy to write new renderers to support other formats.

It is easy to use libcmark in python, lua, ruby, and other dynamic languages: see the wrappers/ subdirectory for some simple examples.

remark

A Javascript-based framework specifically designed around AST manipulation. I've never used it, but it possibly has tools to make AST manipulation easier, though I'm only guessing.

🍀🍀🍀🍀

Good luck!