Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

MDN converted to Markdown

openwebdocs.org

Post reply on HN
Print view View original

21–30 of 140 posts

Re: MDN converted to Markdown

#21

Post by likium »

xcambar wrote: post #17
beebeepka wrote: post #13

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.

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.

Re: MDN converted to Markdown

#22

Post by [deleted] »

beebeepka wrote: post #13

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.

[deleted]

Re: MDN converted to Markdown

#23

Post by Sugimot0 »

I played with mdn-cli which was a neat cli that queries duckduckgo for the first mdn result and parses it to markdown. I then passed that through a parser to make it pretty, and then integrated it with my editor for getting fast documentation without too much context switching.

My biggest gripe was the lag to request ddg and then mdn and then parse it and pipe it. I wanted something simpler like `man` for mdn. Now i imagine having the documentation already in md and keeping it local, i'm a step closer and it'll be more powerful with tools like fzf, ripgrep, and mdcat.

Gotta check if there's already a search tool for MD that weighs heading levels, or code blocks, bold text, etc

Re: MDN converted to Markdown

#25

Post by kubanczyk »

nneonneo wrote: post #15
beebeepka wrote: post #13

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.

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 d…

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.

Re: MDN converted to Markdown

#26

Post by otikik »

beebeepka wrote: post #13

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.

> use markdown for configuration purposes - replacing yaml and stuff

That sounds unlikely. Where did you hear that?

Re: MDN converted to Markdown

#27

Post by gherkinnn »

swyx wrote: post #8
nerdponx wrote: post #6

It's too bad that AsciiDoc still hasn't really caught on like Markdown. It's a whole lot nicer for more-complicated documents. I understand their reasons for not using it here, but it still seems like a perfect fit for this task. Eclipse still seems to be working on a formal spec, but hopefully that will help implementations to grow and adoption to increase. In any case, avoiding raw HTML is a huge improvement. I lik…

Markdown is "worse is better". AsciiDoc is more powerful, but has a steeper learning curve, therefore it lost. tale as old as tech. EDIT: i'm compiling a list of "Worse is Better" technology battles: - Mixed paradigm languages vs Functional languages - Typescript vs Flow - React+Redux beat Angular and Elm - VHS beat Betamax - AC beat DC - what else? please share more here https://hashnode.com/preview/636602dec7fec996…

- Javascript vs *

- English vs *

Both awful languages in many ways. And yet, here we are. Also who the fuck wants to speak Esperanto?

In some cases I don’t think it’s “worse is better”, much as “the flexible beats the over-designed ivory tower”.

Another way of looking at it is “capabilities matter, vulnerabilities don’t”.

Think of a river carving its way through a valley. It is terribly undesigned and messy but it flows exactly where it had to.

Re: MDN converted to Markdown

#28

Post by chrisandchris »

Sugimot0 wrote: post #23

I played with mdn-cli which was a neat cli that queries duckduckgo for the first mdn result and parses it to markdown. I then passed that through a parser to make it pretty, and then integrated it with my editor for getting fast documentation without too much context switching. My biggest gripe was the lag to request ddg and then mdn and then parse it and pipe it. I wanted something simpler like `man` for mdn. Now i…

If there just would be some format and rendering engine that would us allow to display text nice. Let me think, something like HTML and a browser?

Jokes aside, it's interesting to see at what lengths people go just to get it "in a format I prefer" rather than using the given format (and the other side not having any kind of structured format as it looks).

Re: MDN converted to Markdown

#29

Post by CipherThrowaway »

beebeepka wrote: post #13

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.

>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.

Re: MDN converted to Markdown

#30

Post by cbo100 »

throw_m239339 wrote: post #18
beebeepka wrote: post #13

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.

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...

Post reply on HN