6 ms·
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 surpri
by beebeepka 4y ago
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.
- nneonneo 4y agoMy 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?
- kubanczyk 4y agoExactly. 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.
- xcambar 4y agoSounds 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.
- likium 4y agoWhat 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.
- zelphirkalt 4y agoThey 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.
- throw_m239339 4y agoPretty sure that markdown wasn't imagined for that purpose, how would it even work? Markdown for comments in config files? Absolutely.
- cbo100 4y agoThe 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/readme.md https://github.com/Azure/autorest/blob/main/docs/generate/re...
- deleted 4y ago[deleted]
- otikik 4y ago> use markdown for configuration purposes - replacing yaml and stuff That sounds unlikely. Where did you hear that?
- beebeepka 4y agoCTO mentioned it several times and I was in no mood to ask questions
- CipherThrowaway 4y ago>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.
- Aissen 4y agoWhether 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…