Add a newline after the title frontmatter and type "u"
[deleted]
Markdoc: Stripe's Markdown-based authoring framework
11–20 of 157 posts
Re: Markdoc: Stripe's Markdown-based authoring framework
#12Browsing their Docs has this weird, glitchy animation. Where is it coming from?
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?
Here's a picture of one weird animation, looks like others are speaking to something else though.
It looks like the "Try it out" is chasing the mouse, but perhaps someone tried to get a bit too fancy with it. Any mouse movement that is slightly irregular (speed, circular motion, etc.) makes for really wonky animations.
Re: Markdoc: Stripe's Markdown-based authoring framework
#13Browsing their Docs has this weird, glitchy animation. Where is it coming from?
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.
Re: Markdoc: Stripe's Markdown-based authoring framework
#14Re: Markdoc: Stripe's Markdown-based authoring framework
#15Re: Markdoc: Stripe's Markdown-based authoring framework
#16I 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
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React.
This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control".
> content can quickly become as complex as regular code
Okay, but has that actually happened in practice?
Re: Markdoc: Stripe's Markdown-based authoring framework
#17I 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.
Re: Markdoc: Stripe's Markdown-based authoring framework
#18Earlier quoted context omitted.
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control". > content can quickly become as complex as regular code Okay, but has that actually happened in practice?
> React is also a "fully declarative approach to composition and flow control".
MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.
Re: Markdoc: Stripe's Markdown-based authoring framework
#19Earlier quoted context omitted.
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control". > content can quickly become as complex as regular code Okay, but has that actually happened in practice?
No idea, but it's worth keeping in mind that documentation isn't always written and edited by developers (because developers aren't always good writers). Maintaining the separation between code and content is a good idea if a company uses technical writers or other non-developer content people.
Re: Markdoc: Stripe's Markdown-based authoring framework
#20is this jinja? the {% %} makes it look like jinja to me?