Ask HN: Markdown-like structured document format | Hacker News Reader

Ask HN: Markdown-like structured document format

2 pointskolev5 comments

I'm writing some legal documents, which I want to post in GitHub so that people can track history and so on. The issue I'm having with Markdown is that it doesn't support numbered lists with letters, which are typical for legal documents. Also, it doesn't support references to other pieces of the document. If I insert an article, I need to change all other article numbers and references manually. I looked into Legal Markdown [0], which is an extension, and it addresses some of the issues but leaves others unaddressed. Any suggestions?

[0] https://lmd.io/

View on HN

Maybe pandoc would work for you (http://pandoc.org/)

from the documentation:

"Unlike standard markdown, Pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to arabic numerals. List markers may be enclosed in parentheses or followed by a single right-parentheses or period. They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces.1"

Also, see http://pandoc.org/README.html#citations

I wonder why the ambitious CommonMark project did not look into adopting any of these. Regarding references, this is great, but I was referring to internal within the document ones, not external. For example, in "Article I" you mention "Article II, Section 3", which should change to "Article III, Section 3" if I insert a new article between the first and the second or to "Article II, Section 4" if I insert a section.

AsciiDoc (http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) supports numbered lists with letters, and links referencing anchors elsewhere in the document. Also, GitHub's code browser renders AsciiDoc documents (file names ending with .ad or .adoc).

I've always thought it's just for code documentation, but I see know it could be used more broadly! Thank you!

After playing a few days with AsciiDoc, I definitely like it, but it still doesn't solve basic legal document requirements like the references. Maybe I will submit a request to extend it.

Reply on news.ycombinator.com