[HN Gopher] Markdoc: Stripe's Markdown-based authoring framework ___________________________________________________________________ Markdoc: Stripe's Markdown-based authoring framework Author : colinclerk Score : 558 points Date : 2022-05-11 15:07 UTC (7 hours ago) (HTM) web link (markdoc.io) (TXT) w3m dump (markdoc.io) | data_ders wrote: | is this jinja? the {% %} makes it look like jinja to me? | mooreds wrote: | 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. | digisign wrote: | Installed via npm, my money's on javascript. | [deleted] | majkinetor wrote: | I 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 | dragonwriter wrote: | Name collision with: | | https://github.com/haghish/markdoc | _miau_hoch2 wrote: | For 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/). If you haven't | already, have a look. I think it is pretty impressive. From tags, | tabs to the fantastic built-in search ... | armchairhacker wrote: | After looking through Docusaurus, GitBook, and a few others, I | also ended up with mkdocs and github pages. It's very | straightforward to setup. | meshaneian wrote: | Solid competitor to https://hackmd.io/ (codimd on github) | schemescape wrote: | Are 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. | [deleted] | polutropos wrote: | This is amazing. Does this power the Stripe API reference pages? | https://stripe.com/docs/api | | Or is this only for https://stripe.com/docs, | https://stripe.com/docs/payments, etc? | nkohari wrote: | Right now we're only using it in our narrative docs | (http://stripe.com/docs) but we have plans to use it in the | reference docs as well. | vvram wrote: | What powers the API docs ? | nkohari wrote: | It'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 wrote: | Just to add to that, "normal" markdown (I forget which | flavor exactly) is currently used for the text blocks | within the Stripe API reference documentation. | alphang wrote: | From 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. | etchalon wrote: | I 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 | Veen wrote: | 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 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. | pomber wrote: | I like that they write it as a trade of. I think I still | prefer the maintainability complications of "docs as code" | https://www.youtube.com/watch?v=xEu3t-KJVVg | docmechanic wrote: | Just a gentle reminder that docs like code has an actual | definition that we can refer to. | | When we say treat the docs like code, we mean that you: * | Store the doc source files in a version control system. * | Build the doc artifacts automatically. * Ensure that a | trusted set of reviewers meticulously review the docs. * | Publish the artifacts without much human intervention. | | Docs Like Code, Anne Gentle, p. 10 | maxerickson wrote: | The quoted text says "as" and clearly intends that meaning. | docmechanic wrote: | 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 " | ipsum2 wrote: | > 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? | nkohari wrote: | > Okay, but has that actually happened in practice? | | Before we built Markdoc, our documentation was powered by | ERB (embedded Ruby templates). Having content mixed with | arbitrary code made it _incredibly_ hard to reason about | either. Because Markdoc is a declarative language rather | than imperative, there 's no intermediate state to keep | track of, making things easier to follow. | | At Stripe, both engineers and tech writers contribute to | documentation. Markdoc makes things easier for everyone by | keeping the content separate from the code, while still | making it possible to build more interactive experiences | when you want to. (For example, our integration builder [0] | is also powered by Markdoc.) | | [0] https://stripe.com/docs/payments/quickstart | dragonwriter wrote: | > 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 wrote: | 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. | docmechanic wrote: | An 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 wrote: | We 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 wrote: | 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. | ankrgyl wrote: | 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). | dsmmcken wrote: | 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. | nik736 wrote: | Browsing their Docs has this weird, glitchy animation. Where is | it coming from? | nkohari wrote: | 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? | ziddoap wrote: | 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. | | https://imgur.com/a/X4cZYaM | [deleted] | petepete wrote: | 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. | nik736 wrote: | Yes, this is exactly what I meant. | [deleted] | lucideer wrote: | I see it on Firefox, not on Chrome (am on Linux). Very | obvious, hard to miss. | kurttheviking wrote: | I'm seeing weird effects from the "Try it out" text that | chases the cursor. Sometimes it jumbles and freezes, etc. | bww wrote: | Shameless 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 | uvesten wrote: | Looks 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".) | AtNightWeCode wrote: | I 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 wrote: | "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 wrote: | https://github.com/markdoc/docs/blob/main/components/SideByS... | gambler wrote: | https://technology.reclamation.institute/pages/cured-html | blutack wrote: | Does 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? | geokon wrote: | I 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 | | (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 | chrisweekly wrote: | Obsidian.md is amazing; basically an OS for markdown. | uneekname wrote: | Pandoc filters and templates can be used to create complex, | replicable workflows like this. | | If you want to generate diagrams using pandoc, there are | filters that will do that for you. | | I dream of a UI for authoring pandoc ASTs ... someday I'll sit | down and make it! | [deleted] | jtbayly wrote: | Have you checked out Quarto? https://quarto.org | | "Quarto(r) 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? | bbkane wrote: | Typora includes diagram supports and export to PDF. It costs | $15 with a free trial, but it's worth every penny. | arminiusreturns wrote: | 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. | gpoore wrote: | I've created a VS Code extension that provides a live Pandoc | preview with scroll sync and support for executing code: https: | //marketplace.visualstudio.com/items?itemName=gpoore.c.... | Adding support for diagrams would just be a matter of creating | a config file specifying the diagram executable and command- | line options. | cercatrova wrote: | Lol, 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. | ABraidotti wrote: | 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? | slorber wrote: | I don't know about Markdoc but with Docusaurus you can have | your blog in 1min, just go to docusaurus.new | | (I'm the maintainer) | zellyn wrote: | One 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. | mfix22 wrote: | 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. | zellyn wrote: | Interesting. 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 :-) | dallasgutauckis wrote: | Add a newline after the title frontmatter and type "u" | [deleted] | ohgodplsno wrote: | The joys of parsing user input live and trying to display it | immediately :) | mfix22 wrote: | Fix is up--thanks for calling this out. | inson wrote: | Is this a new type of Jinja? | seanwilson wrote: | How 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. | andrerpena wrote: | 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! | tannhaeuser wrote: | Hey, 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 | Duhck wrote: | We use Remark, and given the ability to leverage AST, its | pretty much limitless in terms of customization | SneakyTornado29 wrote: | Wow! 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? | kposehn wrote: | I was in the same boat, wanting to migrate away from | Jekyll+Liquid. Very glad they released this. | IshKebab wrote: | This 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. | openbrian wrote: | See also HedgeDoc https://hedgedoc.org/ which is collaborative | and supports tables. | bkrishnan wrote: | As someone who was about to use Remark | (https://github.com/remarkjs/remark) and Next.js to start a new | blog, does this solve something that Remark doesn't? Genuinely | curious. | tauchunfall wrote: | From a quick glanze it could've been implemented with remark | instead of patching markdown-it. | cdevroe wrote: | Stripe'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 wrote: | Would be very cool with some information on how they work with | creating the docs, manage them etc. | cdevroe wrote: | 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. | jb3689 wrote: | It helps when you have people staffed full time for the | work. Stripe views docs as a product, not an afterthought | cdevroe wrote: | Totally agree. There are other companies, though, that | have people staffed for the work and they do not do | nearly as good of a job. I shall refrain from naming | names. :) | threepio wrote: | 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 ;) | droopyEyelids wrote: | The 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 wrote: | I think they meant "better than my docs are now with $0 | funding" rather than "better than the median company with | $2bn funding" | robertlagrant wrote: | Maybe you'd have $2+ billion in funding if your docs were | better! | clintonb wrote: | > I'd love to know if Stripe has any secrets to keeping | their Docs updated. | | Simple: documentation is part of the "definition of done". | This goes for API docs (e.g., editing field descriptions) | and integration guides/high-level docs. The feature/project | isn't done if no one knows how to use it. | [deleted] | wolframhempel wrote: | Totally agree. What makes Stripe's docs so great is not just | the content, but also the structure and embedded functionality. | Switching between programming languages is seamless, the | examples are pre-populated with data from my stripe account | which is immediately meaningful to me. | | Any framework that supports this functionality is a great | contribution to OS | ksajadi wrote: | I'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? | segphault wrote: | Hey, 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. | euroderf wrote: | Do all your extensions to Commonmark enable you to generate | semantic HTML/XML that can be processed further down a | pipeline with XSLT ? Or is the system used mainly to generate | fairly standard HTML ? I'm thinking DITA here. | data_ders wrote: | way 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? | bccdee wrote: | What are the advantages of integrating templating and | markdown like that? If I'm using markdown with nunjucks, for | instance, what do I stand to gain from switching to Markdoc? | ksajadi wrote: | Upon 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. | epaulson wrote: | How 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 wrote: | I'm a bit confused. Following the React tutorials | 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 wrote: | This is possible! Check out | https://markdoc.io/docs/nodes#customizing-markdoc-nodes | alberth wrote: | So 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 wrote: | It 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 wrote: | you 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) | dragonsh wrote: | 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 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... | | [1] https://www.sphinx-doc.org/en/master/ | cubes wrote: | 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." | TkTech wrote: | While 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 wrote: | 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. | zdw wrote: | > As a former colleague liked to say, "The bar to authoring | documentation needs to be so low you can trip over it." | | Wikis have an incredibly low bar, and at some point making | things easy leads directly to garbage-in-garbage-out | disorganization. | | Having docs go through the same linting and code review | process (which should also be easy!) as code is the way | forward for docs longer than a few pages. | | Sphinx is excellent and batteries included for this sort of | lint process. | IshKebab wrote: | 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. | euroderf wrote: | Several previous discussions at HN have suggested that | AsciiDoc is better to work with than RST. | fedeb95 wrote: | the pointer is annoying though | oellegaard wrote: | It 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? | lordleft wrote: | This is an almost breathtaking documentation site. | aquilaFiera wrote: | We 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 | prepend wrote: | Thanks 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- | Sala... | aquilaFiera wrote: | It'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) | 9dev wrote: | I'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 wrote: | The Stripe docs use a library of a few dozen Markdoc tags. | While the tags are different, the articles on | https://markdoc.io are pretty similar to those in the Stripe | docs. For example: https://raw.githubusercontent.com/markdoc/ | docs/main/pages/do... ___________________________________________________________________ (page generated 2022-05-11 23:00 UTC)