15 ms·
Markdoc: Stripe's Markdown-based authoring framework
- dallasgutauckis 4y agoAdd a newline after the title frontmatter and type "u"
- ohgodplsno 4y agoThe joys of parsing user input live and trying to display it immediately :)
- mfix22 4y agoFix is up—thanks for calling this out.
- deleted 4y ago[deleted]
- mikelabatt 4y agoIt was good to read "Why not AsciiDoc?" in their FAQ: https://markdoc.io/docs/faq https://markdoc.io/docs/faq
- etchalon 4y agoI 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 https://github.com/streamlit/docs
- Veen 4y agoThey explain the difference in an FAQ. https://markdoc.io/docs/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 and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.
- ipsum2 4y ago> 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?
- dragonwriter 4y ago> 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.
- Veen 4y agoNo 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.
- docmechanic 4y agoAn alternative point of view from Docs Like Code, p.11 Reasons we treat docs like code Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding. For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.
- etchalon 4y agoWe handle this by having some components that don't require much training to use (<Note />, <Warning />, <Function />). I don't think you have to choose between "can be powerful" and "can be simple." If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.
- ipsum2 4y agoI haven't heard of MDX before, but this looks fantastic. The API looks more intuitive than Markdoc. https://mdxjs.com/ https://mdxjs.com/ for anyone else wanting to learn more.
- dsmmcken 4y agomdx is great, especially if your team is already fluent with react/jsx. You might also be interested in docusaurus https://docusaurus.io/ https://docusaurus.io/ as it has support for mdx built in.
- ankrgyl 4y agoIf you want to play with MDX without having to set it up, check out https://motif.land 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).
- nik736 4y agoBrowsing their Docs has this weird, glitchy animation. Where is it coming from?
- nkohari 4y agoI'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?
- kurttheviking 4y agoI'm seeing weird effects from the "Try it out" text that chases the cursor. Sometimes it jumbles and freezes, etc.
- ziddoap 4y agoHere'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. https://imgur.com/a/X4cZYaM https://imgur.com/a/X4cZYaM
- deleted 4y ago[deleted]
- petepete 4y agoI see this when browsing between pages (Firefox, Linux) https://user-images.githubusercontent.com/128088/167891663-c021ab67-e8ce-4124-8c3f-cd1684cca82c.mp4 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.
- nik736 4y agoYes, this is exactly what I meant.
- ksajadi 4y agoI'm not sure what the difference is between this and a bunch of other ones like Jekyll or Middleman? Is it in the render phase? What am I missing?
- ksajadi 4y agoUpon further inspection, I think the biggest difference is that Markdoc uses Nextjs which means you can write React right in the middle of your code and import React components. But then again, you have Gatsby that's also based on React and is built for static site generation, and supports Markdown.
- segphault 4y agoHey, I work on the Docs Product engineering team at Stripe and created Markdoc. The scope is somewhat different: Jekyll and Middleman are static site generators that provide a full stack for content publishing whereas Markdoc is a framework for processing Markdown content with custom tags and transforming it into the desired output format. Markdoc can be used inside of a static site generator or a custom documentation platform. Markdoc's syntax and custom tags also take a somewhat different approach than many of the string templating systems that are commonly used in static site generators. Markdoc is not a preprocessor, the tags are treated as a first-class part of the markdown content, which parses into a data structure that can be statically analyzed, programmatically transformed, and rendered into the desired output format. For us, that's React, but it could be raw HTML, Web Components, a slide deck, or whatever else you might come up with.
- data_ders 4y agoway cool! I work at dbt Labs and see a similarity with dbt jinja, where all dbt does is render the jinja tags into "pure" SQL. is this the same thing in that markdoc "compiles" markdoc files into markdown, that then can be used in static-site generators?
- riwsky 4y agoIt’s not. dbt goes out of its way to avoid having to parse SQL into an ast; Markdoc is Stripe going out of its way to parse input to an ast. dbt’s approach is more similar to the ERB system Stripe mentions Markdoc replacing.
- data_ders 4y agois this jinja? the {% %} makes it look like jinja to me?
- dragonwriter 4y agoName collision with: https://github.com/haghish/markdoc https://github.com/haghish/markdoc
- deleted 4y ago[deleted]
- blutack 4y agoDoes 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?
- deleted 4y ago[deleted]
- arminiusreturns 4y agoEmacs 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.
- chrisweekly 4y agoObsidian.md is amazing; basically an OS for markdown.
- geokon 4y agoI got kinda intimidated with the Asciidoc toolchain that I instead just wrote a bit of Clojure to call the Java AsciidocJ API. A tiny script that did what I want (make Reveal slides) and it's simple/straightforward and I guess crossplatform :) So better than even a command line thing If you want a GUI then I'm guessing AsciidocFx https://github.com/asciidocfx/AsciidocFX https://github.com/asciidocfx/AsciidocFX (haven't tried it myself) There is also Orgmode and Texmacs - but I don't really like that the markup is kinda "locked" to an editor. For instance I've done stuff with Orgmode for ages, but it breaks between Emacs major versions and you can't really export it without having Emacs. I also feel like I'm in effect locked into the platform Texmacs actually looks fantastic, but I'm nervous putting all my beans in that basket
- cdevroe 4y agoStripe'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.
- oellegaard 4y agoWould be very cool with some information on how they work with creating the docs, manage them etc.
- cdevroe 4y agoI 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.
- threepio 4y agoAs 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 ;)
- droopyEyelids 4y agoThe odds are deeply against your assertion- If we look at companies with $2b in funding, chances are yours would fall somewhere in the the median range, rather than at the top of the pack.
- monknomo 4y agoI think they meant "better than my docs are now with $0 funding" rather than "better than the median company with $2bn funding"
- dragonsh 4y agoGood 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/restructuredtext.html https://docutils.sourceforge.io/docs/ref/rst/restructuredtex... [1] https://www.sphinx-doc.org/en/master/ https://www.sphinx-doc.org/en/master/
- cubes 4y agoI'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."
- TkTech 4y agoWhile completely true, and I personally prefer markdown documentation (or even just a README.md if I can get away with it), larger projects definitely benefit from rst. You're probably going to end up re-inventing parts of it, like all of these markdown documentation projects do via extensions to the language, or littering your markdown with HTML like <div class="alert alert-info">Note, this feature is only available on processors with SSE2 or greater!</div>.
- ericholscher 4y agoThe 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.
- oellegaard 4y agoIt looks like a static site generator - but at the same time it appears you cannot actually generate a static site from it, but you need to run a node.js server. What separates this from any of the existing markdown static site generators?
- alberth 4y agoSo what's the workflow for this? Because this seems to be run locally, vs something hosted like a CMS. You locally have a NodeJS app running, you draft a new page, it renders it for you in HTML/CSS, and then you upload the rendered output to your web server? (Sorry for the naive question)
- harg 4y agoIt would depend on the use case, but as this looks like it's aimed at a technical audience, you'd generally have some sort of CI/CD pipeline that renders the markdoc on a server and deploys the output accordingly, be it a react app, plain html, etc. In many cases, authors would probably need to run the toolchain locally so they can preview their changes. But publishing would basically be the same as committing code and having a CI pipeline take it from there
- verdverm 4y agoyou definitely need something around this, it lacks a lot of the other features in Hugo or Jekyll Might be easier to graft into an existing, dynamic CMS (that uses a DB)
- polutropos 4y agoThis is amazing. Does this power the Stripe API reference pages? https://stripe.com/docs/api https://stripe.com/docs/api Or is this only for https://stripe.com/docs https://stripe.com/docs, https://stripe.com/docs/payments https://stripe.com/docs/payments, etc?
- nkohari 4y agoRight now we're only using it in our narrative docs (http://stripe.com/docs http://stripe.com/docs) but we have plans to use it in the reference docs as well.
- vvram 4y agoWhat powers the API docs ?
- nkohari 4y agoIt's all custom; the frontend is React and the backend is Ruby. Our plan is to introduce Markdoc as an intermediary step to improve the authoring experience.
- rattray 4y agoJust to add to that, "normal" markdown (I forget which flavor exactly) is currently used for the text blocks within the Stripe API reference documentation.
- bww 4y agoShameless plug: for REST APIs, I've written a tool called Instaunit which combines HTTP API integration tests with documentation generation, since these two things must always be maintained in lockstep. It's got a ways to go before it generates output that looks as good as Stripe's documentation, but it makes it dead simple to create API documentation that's guaranteed to be in sync with your service, because it was generated by your tests when they ran. https://github.com/instaunit/instaunit https://github.com/instaunit/instaunit
- uvesten 4y agoLooks neat! The documentation does not seem to have any examples of the generated docs, though. I think that would be a good addition, because it’s a good selling point for the project. (I.e I don’t think I’d go through downloading and running it just to see if the generated documentation is ”good enough”.)
- ABraidotti 4y agoI'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?
- zellyn 4y agoOne curiosity: I was trying to figure out how the diagram at the top of https://markdoc.io/docs/render 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/docs/render.md 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.js 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.
- mfix22 4y agoGood 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 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 https://stripe.com/docs/payments/checkout/how-checkout-works, if you are curious.
- zellyn 4y agoInteresting. Thanks for the reply. I'm trying to understand what it would be like to adopt Markdoc as our internal documentation system. I didn't like the "spooky action at a distance" of defining diagrams far away from the text, so I'm glad to hear it's not usual practice :-)
- deleted 4y ago[deleted]
- IshKebab 4y agoThis 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.
- _miau_hoch2 4y agoFor anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material (https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...
- armchairhacker 4y agoAfter looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.
- evolve2k 4y agoI spent 6 months assessing the options came down to ‘Material for Mkdocs’.
- d4rkp4ttern 4y agoDoes Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.
- squidfunk 4y agoAuthor of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs. [1]: https://mkdocstrings.github.io/ https://mkdocstrings.github.io/ [2]: https://github.com/mkdocstrings/python https://github.com/mkdocstrings/python [3]: https://github.com/mkdocstrings/crystal https://github.com/mkdocstrings/crystal
- d4rkp4ttern 4y agoThis is great, thank you.
- AtNightWeCode 4y agoI have been looking for exactly this. Will test it out for sure. On a side-note, mixing serifs and sans in the way the site does looks like something only a mass murderer would do.
- fellowniusmonk 4y ago"side-by-side" is a module that seems to be used extensively throughout this projects documentation, as well as in stripes documentation. I don't see where it is defined anywhere, do they have a library of these common helpers? I looked but I guess my searchfu isn't what it used to be.
- matv 4y agohttps://github.com/markdoc/docs/blob/main/components/SideBySide.js https://github.com/markdoc/docs/blob/main/components/SideByS...
- openbrian 4y agoSee also HedgeDoc https://hedgedoc.org/ https://hedgedoc.org/ which is collaborative and supports tables.
- aquilaFiera 4y agoWe get to use Markdoc every day and it is a joy to work with. Shameless plug: we're looking for someone to come in and a product manager over the Stripe Docs. Imagine working on docs at the company known for docs. Very fun problems. https://stripe.com/jobs/listing/product-manager-docs/3928998 https://stripe.com/jobs/listing/product-manager-docs/3928998
- 9dev 4y agoI’m curious how much you’ve actually customised it. Does the docs source still have a resemblance to markdown, or is it more of a react-like DSL by now? Job sounds super fun by the way :)
- nkohari 4y agoThe Stripe docs use a library of a few dozen Markdoc tags. While the tags are different, the articles on https://markdoc.io https://markdoc.io are pretty similar to those in the Stripe docs. For example: https://raw.githubusercontent.com/markdoc/docs/main/pages/docs/faq.md https://raw.githubusercontent.com/markdoc/docs/main/pages/do...
- prepend 4y agoThanks for posting this. What is a good way for learning about the salary and compensation for this position? Nothing specific, b it just ballpark to determine if there’s basic compatibility before applying. The title is too specific to get good numbers from googling and I worry that docs product managers wouldn’t make what typical product managers make. [0] [0] https://www.glassdoor.com/Salary/Stripe-Product-Manager-Salaries-E671932_D_KO7,22.htm https://www.glassdoor.com/Salary/Stripe-Product-Manager-Sala...
- aquilaFiera 4y agoIt's a normal PM position and you'd be in the normal PM salary bands. You'd be my peer. I manage the server-side SDKs, the CLI, the VS Code extension, the React Native SDK, the API upgrade experience, etc. We'd be in the same ladder. (AFAIK there's just one PM ladder at Stripe)
- majkinetor 4y agoI am glad to know there are those that put so much thought into documentation. Documentations is just another service, and deserves all the same methodology: CI/CD, automatic tests, components and reuse, different environments etc. As far as I can see, you can get similar workflow with combination of existing tools. I created this docker image that combines them for very easy consumption and created thousands of pages of technical, functional and user documentation with it: https://github.com/majkinetor/mm-docs https://github.com/majkinetor/mm-docs
- seanwilson 4y agoHow well does this scale to hundreds of pages? I found Jekyll and others can start to slow down here during page generation where it can take several seconds to generate not that many pages, especially if you're using a lot of template features. It's part of the reason Hugo is my default as it's so fast.
- gambler 4y agohttps://technology.reclamation.institute/pages/cured-html https://technology.reclamation.institute/pages/cured-html
- andrerpena 4y agoOMG. 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!
- kposehn 4y agoI was in the same boat, wanting to migrate away from Jekyll+Liquid. Very glad they released this.
- atonse 4y agoAny reason why this would be better than liquid? Genuinely curious because we’re about to adopt liquid.
- Duhck 4y agoWe use Remark, and given the ability to leverage AST, its pretty much limitless in terms of customization
- SneakyTornado29 4y agoWow! Was thinking of doing the same because I wanted to include custom HTML elements suck as boxed block quotes in my Markdown documents. So does this solve the problem?
- tannhaeuser 4y agoHey, if you really want to customize markdown with your own elements and their rendering/templating, check out SGML [1]. It's made for exactly this type of flexible and extensible document apps/sites, even allows custom Wiki syntax rules. [1]: http://sgmljs.net http://sgmljs.net
- kyawzazaw 4y agoA 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?
- alphang 4y agoFrom the docs, it looks like they're emphasizing the document format part, and less so the authoring system (which would make me think of SSG/CI/etc). It also looks like there are functions, but they're considerably shaved down compared to JavaScript/etc. I wonder if this will get more adoption in the TW community and by various static site generators.
- cercatrova 4y agoLol, I haven't seen the text following the mouse cursor ("Try it out") in a long time. Glad to see some whimsy is still present on the Internet.
- lordleft 4y agoThis is an almost breathtaking documentation site.
- fedeb95 4y agothe pointer is annoying though
- schemescape 4y agoAre relative links supported? The landing page uses root-relative links and the FAQ/examples don't seem to cover links in depth. I like relative links because my editor (VS Code) will auto-complete relative links... but many Markdown-based tools don't handle the Markdown-source-to-output-HTML translation.
- bkrishnan 4y ago[dead]
- tauchunfall 4y agoFrom a quick glanze it could've been implemented with remark instead of patching markdown-it.
- epaulson 4y agoHow does this compare to DocFX? One thing I think Microsoft does very well is the Azure documentation. It's consistently structured across services, but even better, it's also all just a bunch of Markdown and for any page, you can open a Github issue right from that page. And because it's in Github, you can see the history of a page, which has been helpful to see when options change or when limitations were clarified. I think MSFT just uses stock DocFX for the Azure docs site, but I'm not sure.
- andrerpena 4y agoI'm a bit confused. Following the React tutorials https://markdoc.io/docs/render#react https://markdoc.io/docs/render#react I was able to render my own react components on custom tags, which I wanted. Nice! But I'm not being able to define how to render my own components for Markdown tags like paragraph or heading :(
- matv 4y agoThis is possible! Check out https://markdoc.io/docs/nodes#customizing-markdoc-nodes https://markdoc.io/docs/nodes#customizing-markdoc-nodes
- inson 4y agoIs this a new type of Jinja?
- meshaneian 4y agoSolid competitor to https://hackmd.io/ https://hackmd.io/ (codimd on github)
- creakingstairs 4y agoI’ve been writing a similar thing for my blog. I wish I came across this sooner as this looks like exactly what I had wanted.
- todd3834 4y agoSo it’s been a few hours and I really love this library! I integrated it into a React/esbuild application and it is working great. The React/Prism example for code highlighting took a little work. They have an example but it is a little buried. Their example wasn’t working for me but it was enough for me to get my own working without react-prism. Shameless plug: If anyone is interested, I published my esbuild plugin so you don’t have to transform on the server if you want to just import a markdown file. https://github.com/toddw/esbuild-markdoc-plugin https://github.com/toddw/esbuild-markdoc-plugin
- annagrigoryan2 4y agoFound this right when I was looking for a quality markdown parser. I guess it's my lucky day.
- d4rkp4ttern 4y agoDoes this have functionality to auto-generate docs from (python) docstrings? Currently using Sphinx with RTD (ReadTheDocs) theme for this, and quite happy with it, though the setup took a lot of hunting around for examples. Wondering if this is the best auto-doc approach for python these days. For context, I am developing a code base with the intention of later open sourcing it, so wanted to have it properly documented from the start.