Hacker News Reader

Comment by beebeepka | Hacker News Reader

Recently I overheard that our company intends to use markdown for configuration purposes - replacing yaml and stuff. I am not against the idea but it did surprise me because while I am happy with writing documents in MD, it never occurred to me that it could be used for configs.

Not sure what the upsides and downsides are.

View on HN

>it never occurred to me that it could be used for configs.

It can't be. Using "markdown" for config really means building a shitty ad hoc configuration language and embedding it in markdown. I've seen this a few times and it's always a disaster.

The only way I've found to make configuration tolerable is to go in the opposite direction and turn it into code with a declarative eDSL. For example Pulumi's typescript API is an absolute godsend after years of toiling away on HCL and YAML.

My gut reaction is that it sounds like a terrible idea. Markdown is designed at the outset as a markup language, meant to imbue formatting and structure to human-readable text. But it lacks a formal grammar or a strictly defined mapping from syntax to parse tree, so different tools may interpret the same document differently (i.e. there are many Markdown “dialects”). Markdown has no inherent support for any kind of data types other than text; it has lists, but nothing that would obviously be “map” or key-value data structures.

Indeed, if you’re going to make use of Markdown to store structured data like a config file, I wager the result will start looking a lot like YAML. At which point - why not just use YAML directly?

Exactly. For most systems that use heavy YAML configuration, their problem is not YAML.

YAML is a decent solution to their problem which is:

  they:
    have:
      - so
      - many
      - nested
      - levels:
        of:
          configuration:
            without:
              any:
               - abstractions &that-arent-ugly

Markdown can only make it worse.

Whether using yaml or something more modern like Cue, nowadays a configuration language needs a semantic syntax checker (not just a parser), and tools to automate transformation. If you think you are OK building these with Markdown, go for it. But you'll find it's probably a bad idea in the end…

Sounds like literate programming. I've used it once or twice for training material and as "fancy" slides at an internal presentation.

Worked quite well as one-offs but I'm not sure that scales wrt its usability and maintenance.

What were the issues you saw on usability and maintenance?

Things like jupyter notebooks and observablehq.com seem to be bringing in a breath of fresh air to literate programming.

They are lacking implementations though and they are more about programming things than writing your config in them. Sure, you can put config in code, but that sounds like a terrible idea for non-DSLs.

Pretty sure that markdown wasn't imagined for that purpose, how would it even work?

Markdown for comments in config files? Absolutely.

The autorest project uses this actually.

It works by embedding yaml code blocks into a markdown file.

It’s actually not completely awful and has proven somewhat useful to have a configuration clearly documented within the config.

https://github.com/Azure/autorest/blob/main/docs/generate/re...

> use markdown for configuration purposes - replacing yaml and stuff

That sounds unlikely. Where did you hear that?

CTO mentioned it several times and I was in no mood to ask questions

Reply on news.ycombinator.com