Name collision with:
Markdoc: Stripe's Markdown-based authoring framework
21–30 of 157 posts
Re: Markdoc: Stripe's Markdown-based authoring framework
#22is this jinja? the {% %} makes it look like jinja to me?
Looks like JSP to me. Or maybe ASP? Or ERB? Not sure which one came first, but many templating languages use those tokens.
Given Stripe's ruby predilection, my guess is ERB.
Re: Markdoc: Stripe's Markdown-based authoring framework
#23Does 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 web UI/editor built into the binary. Oh, and if it could manage multiple documents and versioning that would be great too. Looking for a Fossil SCM kind of feel?
Closest thing I've used would probably be LyX but that's almost too capable!
I do appreciate this is a really hard thing to do and I'm wondering what toolchains other people are using?
Re: Markdoc: Stripe's Markdown-based authoring framework
#24Re: Markdoc: Stripe's Markdown-based authoring framework
#25is this jinja? the {% %} makes it look like jinja to me?
[deleted]
Re: Markdoc: Stripe's Markdown-based authoring framework
#26Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm thankful to their team for how good their Docs are.
Very cool of them to open source this. Looks great.
Re: Markdoc: Stripe's Markdown-based authoring framework
#27Does 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…
[deleted]
Re: Markdoc: Stripe's Markdown-based authoring framework
#28I 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.
mdx is great, especially if your team is already fluent with react/jsx. You might also be interested in docusaurus https://docusaurus.io/ as it has support for mdx built in.
Re: Markdoc: Stripe's Markdown-based authoring framework
#29Good 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 markdoc with its own set of non standard extensions. Hopefully rst format can catch up among JavaScript developers.
So far haven’t seen a complete documentation tool like Python Sphinx [1].
[0] https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...
Re: Markdoc: Stripe's Markdown-based authoring framework
#30Does 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…
Emacs org-mode with babel for executing code blocks to generate the diagrams prior to exporting to html/pdf is my flow for this. It still has a steeper learning curve for non-technical users, but if you use post-commit hooks you can have people just make changes that way and let the scripts do the work.