I've been thinking about using this or Docusaurus to start a blog. Does anyone have an opinion on which of the two is better/easier/etc?
Markdoc: Stripe's Markdown-based authoring framework
51–60 of 157 posts
Re: Markdoc: Stripe's Markdown-based authoring framework
#52One curiosity: I was trying to figure out how the diagram at the top of https://markdoc.io/docs/render was generated.
The items inside the diagram seem curiously absent from the source of the page: https://raw.githubusercontent.com/markdoc/docs/main/pages/do...
Instead, when the `diagram` tag is defined, it maps the "type" parameter to a particular diagram: https://github.com/markdoc/docs/blob/main/components/Diagram...
Any reason it is done that way, rather than specifying the diagram in the source of the document using mermaid, pikchr, etc? Even inlining the SVG seems like it would be better for keeping everything together.
Re: Markdoc: Stripe's Markdown-based authoring framework
#53Earlier quoted context omitted.
I'm an engineer on the Docs team at Stripe. Can you say more about where you're seeing the animation and what it looks like?
I see this when browsing between pages (Firefox, Linux) https://user-images.githubusercontent.com/128088/167891663-c... Another small bug, the ::selection colour in CSS matches the yellow background on your homepage so if you select text there (in the 'Get started quickly' bit) you can't see what you've selected.
Yes, this is exactly what I meant.
Re: Markdoc: Stripe's Markdown-based authoring framework
#54One curiosity: I was trying to figure out how the diagram at the top of https://markdoc.io/docs/render was generated. The items inside the diagram seem curiously absent from the source of the page: https://raw.githubusercontent.com/markdoc/docs/main/pages/do... Instead, when the `diagram` tag is defined, it maps the "type" parameter to a particular diagram: https://github.com/markdoc/docs/blob/main/components/Diagram…
Good question. You are right in that it is implemented as a mapping from type → SVG in the Markdoc docs site. However, diagrams don't need to be implemented this way.
In fact, on stripe.com/docs we use Markdoc + https://reactflow.dev to render custom diagrams (with translated content and everything). There is a good example of this in action on https://stripe.com/docs/payments/checkout/how-checkout-works, if you are curious.
Re: Markdoc: Stripe's Markdown-based authoring framework
#55Earlier quoted context omitted.
Would be very cool with some information on how they work with creating the docs, manage them etc.
I agree. Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.
As an individual developer with many open-source projects, I'm pretty sure that my docs would be better if I had $2+ billion in funding ;)
Re: Markdoc: Stripe's Markdown-based authoring framework
#56[deleted]
Re: Markdoc: Stripe's Markdown-based authoring framework
#57Good 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 implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because...
3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out.
So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though.
Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText.
Do not use RestructuredText.
Re: Markdoc: Stripe's Markdown-based authoring framework
#58I don't understand how this is fundamentally different than MDX, which can already mix React components within Markdown. We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs
I haven't heard of MDX before, but this looks fantastic. The API looks more intuitive than Markdoc. https://mdxjs.com/ for anyone else wanting to learn more.
If you want to play with MDX without having to set it up, check out https://motif.land. It comes with a collaborative editing environment too, that is incredibly easy to use for authoring markdown (our non-technical folks use it too).
Re: Markdoc: Stripe's Markdown-based authoring framework
#59This looks nice but you might want to have an example of the custom syntax on the front page because as far as I can tell that is the main thing this adds, and currently the front page doesn't make it sound different to anything else.
Re: Markdoc: Stripe's Markdown-based authoring framework
#60Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…
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, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more."
Does that sound like it meets your needs?