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

Markdoc: Stripe's Markdown-based authoring framework

markdoc.io

Post reply on HN
Print view View original

121–130 of 157 posts

Re: Markdoc: Stripe's Markdown-based authoring framework

#121

Post by __mharrison__ »

IshKebab wrote: post #57
dragonsh wrote: post #29

Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now…

I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it. 1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but... 2. The only…

Funny you say that. I spent most of last week porting some of my rst based book authoring tooling to md/pandoc.

Re: Markdoc: Stripe's Markdown-based authoring framework

#122

Post by __mharrison__ »

dragonsh wrote: post #29

Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now…

At this point using rst is like advocating for Subversion instead of Git(hub). (Which is actually a good metaphor considering where docutils is hosted...)

I say this as a (former) committer to docutils.

The LaTeX support is ok in rst if you want to create something similar to a Word document. If you actually wanted to print a book, you need to use something like my tool, rst2nitrile.

The Python documentation folks seem to be interested in abstracting Sphinx to markdown as well with MyST...

rst is a dead end at this point.

Re: Markdoc: Stripe's Markdown-based authoring framework

#123

Post by jtbayly »

__mharrison__ wrote: post #120
jtbayly wrote: post #60

Earlier quoted context omitted.

Have you checked out Quarto? https://quarto.org "Quarto® is an open-source scientific and technical publishing system built on Pandoc - Create dynamic content with Python, R, Julia, and Observable. - Author documents as plain text markdown or Jupyter notebooks. - Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more. - Author with scientific markdown,…

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.) Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really int…

I'm also very interested in physical books. Can you point me to anything that supports index entries well, regardless of the language they are written in?

I certainly agree about expecting to need to hack, whatever the tool.

Re: Markdoc: Stripe's Markdown-based authoring framework

#124

Post by maxerickson »

docmechanic wrote: post #117
maxerickson wrote: post #104

Earlier quoted context omitted.

The quoted text says "as" and clearly intends that meaning.

Ah, thank you for the term in question. Found a relevant link: https://www.writethedocs.org/guide/docs-as-code/ "There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out: Docs Like Code - Anne Gentle Modern Technical Writing - Andrew Etter "

That's not how language works, their phrase (that does not actually have a widely used established meaning) means what they meant, not what you say it means.

Re: Markdoc: Stripe's Markdown-based authoring framework

#125

Post by kyawzazaw »

andrerpena wrote: post #86

OMG. I was just about to start my own Markdown parser because I needed custom elements and I was finding too hard to work with existing "customizable" Markdown parsers. Also, I needed a React renderer for React-Native and I was also about to write my own. By the looks of it, I will be able to just use Markdoc. Thank you Stripe!

A bit of a tangential question.

What kind of project or business that you run that you need it?

How much hours do you estimate it would have taken you?

Re: Markdoc: Stripe's Markdown-based authoring framework

#127

Post by __mharrison__ »

jtbayly wrote: post #123
__mharrison__ wrote: post #120

Earlier quoted context omitted.

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.) Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really int…

I'm also very interested in physical books. Can you point me to anything that supports index entries well, regardless of the language they are written in? I certainly agree about expecting to need to hack, whatever the tool.

As I mentioned elsewhere, I've published multiple books using rst2nitrile. For example, Effective Pandas was written with it...

Re: Markdoc: Stripe's Markdown-based authoring framework

#128

Post by smaudet »

ericholscher wrote: post #43
cubes wrote: post #36

Earlier quoted context omitted.

I've used both Markdown and RST extensively. I feel RST has a steeper learning curve than Markdown, and that can be an obstacle to a successful documentation culture at an organization. As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

The learning curve for RST is generally higher because it does more. You'll notice that Markdown's learning curve goes up quite a bit as they add all the features that RST has. That said, RST has some bad design decisions, but I'd say about 75% of the complexity it introduces is needed, and the 25% is bad design.

If you have to extend Markdown, the battle is lost. The basic core idea, is OK, but as soon as you find yourself needing to do more documenty things (lists with formatting, tables, etc.) its the wild, wild west - different extension standards CommonMark, Github style, etc., editor, or library of choice.

Not to mention all the special-custom-component standards now which require code... the whole point of Markdown was you could just use any old text editor and be just as well off as looking at a prettified version.

You have the higher complexity and learning curve anyways, more, even.

I guess, the bad design decisions in RST are bad, but there are equally bad design decisions in all these new extensions, editors.

Instead of trying use a hammer put in screws, we should just change tooling. If you need document-level formatting etc., plain-text formatting is cool but don't try to be markdown. Use markdown when you just need simple text docs, if you find yourself doing complex stuff maybe you shouldn't be using markdown, or at least not calling yourself "markdown".

Re: Markdoc: Stripe's Markdown-based authoring framework

#129

Post by atonse »

kposehn wrote: post #87
andrerpena wrote: post #86

OMG. I was just about to start my own Markdown parser because I needed custom elements and I was finding too hard to work with existing "customizable" Markdown parsers. Also, I needed a React renderer for React-Native and I was also about to write my own. By the looks of it, I will be able to just use Markdoc. Thank you Stripe!

I was in the same boat, wanting to migrate away from Jekyll+Liquid. Very glad they released this.

Any reason why this would be better than liquid?

Genuinely curious because we’re about to adopt liquid.

Re: Markdoc: Stripe's Markdown-based authoring framework

#130

Post by jtbayly »

__mharrison__ wrote: post #120
jtbayly wrote: post #60

Earlier quoted context omitted.

Have you checked out Quarto? https://quarto.org "Quarto® is an open-source scientific and technical publishing system built on Pandoc - Create dynamic content with Python, R, Julia, and Observable. - Author documents as plain text markdown or Jupyter notebooks. - Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more. - Author with scientific markdown,…

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.) Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really int…

Bookdown seems to support index entries:

https://bookdown.org/yihui/bookdown/latex-index.html

I wouldn't be surprised if Quarto supports the same syntax, since they are related. But it is possible it doesn't.

Post reply on HN