[HN Gopher] Markdoc: Stripe's Markdown-based authoring framework
___________________________________________________________________
Markdoc: Stripe's Markdown-based authoring framework
Author : colinclerk
Score : 760 points
Date : 2022-05-11 15:07 UTC (1 days 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
| [deleted]
| _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.
| evolve2k wrote:
| I spent 6 months assessing the options came down to 'Material
| for Mkdocs'.
| meshaneian wrote:
| Solid competitor to https://hackmd.io/ (codimd on github)
| creakingstairs wrote:
| I'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.
| 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 "
| maxerickson wrote:
| That's not how language works, their phrase (that does
| not actually have a widely used established meaning)
| means what they meant, not what you say it means.
| docmechanic wrote:
| Yes, that term does have a widely established meaning
| within the specific context of discussion, technical
| writing. If the commentator is unaware of what 'docs as
| code' means in the context under discussion and meant
| something different, I encourage them to disambiguate by
| picking a term not already so defined.
| 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
| nukemandan wrote:
| I am a huge fan of this style of page! is there an OSS
| example of this in full? I would be very keen to see what
| goes into making such a dynamic page in markdoc looks
| like
| pomber wrote:
| Not Markdoc, but there are several OSS examples of how
| you can do something similar with MDX + Code Hike.
| https://codehike.org/
| 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!
| __mharrison__ wrote:
| Last week I ported my static physical book building tooling
| from rst-based [0] to markdown (pandoc filter) based.
|
| I've used my rst tooling to publish many books (like Effective
| Pandas) and am wanting to drop rst in an effort to simplify my
| life. My pandoc toolchain is not in github yet, but preliminary
| exploration validates that I can publish my next physical book
| with it (with things like front matter, indices, etc).
|
| In the process I messed around with MyST and mistletoe. I
| dropped MyST because it was evident I would need to mess around
| with Sphinx again. Been there done that. Too much abstraction.
|
| Mistletoe would have worked too (I need to create custom
| fences/markup for a few features) but I wanted to see if I
| could do it with Pandoc.
|
| The Pandoc distinction between Blocks and Inlines is annoying
| as is the requirement to handle everything at once. With
| Pandoc, you only get notified at the start of an element, not
| the end which probably complicates it a bit more than Mistletoe
| would have.
|
| (I still need to port my slide generation tooling and will
| probably use mistletoe for that. For epub generation I think I
| will stick with Pandoc.)
|
| 0 - https://github.com/mattharrison/rst2nitrile
| [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?
| __mharrison__ wrote:
| A few folks recommended Quarto to me when I asked about
| current recommendations recently. My main goal is physical
| books and that doesn't seem to be a first class citizen
| anywhere. Looking through Quarto, I can't find reference to
| markdown syntax for index entries (which indicates that they
| don't support it.)
|
| Also, I'm heavily biased, but based on my experience I will
| need to hack whatever tool and I'm not really interested in
| hacking JS/TS. (My whole reason for getting rid of my rst
| based tooling is to simplify and sticking in Python
| simplifies my life, coding in JS/TS not so much.)
| jtbayly wrote:
| Bookdown seems to support index entries:
|
| https://bookdown.org/yihui/bookdown/latex-index.html
|
| I wouldn't be surprised if Quarto supports the same syntax,
| since they are related. But it is possible it doesn't.
| __mharrison__ wrote:
| It might. I'm not interested in hacking R.
| jtbayly wrote:
| I'd be very interested in seeing your markdown (pandoc
| filter) based solution, if you can publish it.
| jtbayly wrote:
| I'm also very interested in physical books. Can you point
| me to anything that supports index entries well, regardless
| of the language they are written in?
|
| I certainly agree about expecting to need to hack, whatever
| the tool.
| __mharrison__ wrote:
| As I mentioned elsewhere, I've published multiple books
| using rst2nitrile. For example, Effective Pandas was
| written with it...
| 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)
| quard wrote:
| Looks like you should able to add markdoc into Docusaurus with
| plugins etc.
| 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?
| todd3834 wrote:
| So 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
| 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!
| fastball wrote:
| For my startup, which is built around Markdown notecards[1],
| we've been using markdown-it, which it seems is also being
| leveraged by the Markdoc project. So far I've written a couple
| of extensions for markdown-it and haven't really had any
| issues.
|
| [1] https://supernotes.app
| 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.
| atonse wrote:
| Any reason why this would be better than liquid?
|
| Genuinely curious because we're about to adopt liquid.
| kyawzazaw wrote:
| A 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?
| 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.
| mikelabatt wrote:
| It was good to read "Why not AsciiDoc?" in their FAQ:
| https://markdoc.io/docs/faq
| 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. :)
| DrewADesign wrote:
| They also treat docs as a way to add detail to and flesh
| out well-designed products rather than as a way to
| disclaim and explain things they didn't feel like or have
| the resources to fix.
| eek2121 wrote:
| I would describe stripe docs as 'acceptable'. Don't get me
| wrong, I personally have brought them tons of business and
| work with their API more than a human should. My only issue
| is that if you are working with their API, you will
| discover HUGE gaps if you step outside "the norms". That
| being said, they are a step above everyone else, which
| should tell you something. Also, the comment regarding
| open-source applies 300%.
| cdevroe wrote:
| It seems that many Stripe team members walk the HN halls,
| if you were to give a few examples of the "HUGE gaps" you
| mentioned they might fill them in.
| edwinwee wrote:
| Yes--would like to hear more about how we can fill in the
| gaps. (Can also email me directly at edwin@stripe.com.)
| 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
| Abishek_Muthian wrote:
| Unfortunately my experience has been different; I found that
| Stripe's Go doc doesn't match their API and while searching on
| it I found that someone else had mentioned that to their
| personnel over freenode 2 years ago.
|
| So I raised an issue on GitHub[1] on Apr 9 and hasn't been
| attended to yet.
|
| On a more serious note, Stripe's payment links doc seemed to
| imply that tax rates are automatically calculated if the tax
| rates are set(as we do with code when we pass the tax_id), But
| I found after couple of payments that tax aren't being charged,
| On conversing on Twitter with the payment links dev I came to
| realize that the required option was not there for me[2] and
| then after couple of hours with their support staff I was
| informed that the options was not available for India as
| 'Stripe Tax' is a separate product.
|
| Overall, I'm happy with Stripe's tech; at least compared to the
| other options I have. But their docs have caused me some
| frustrations.
|
| [1] https://github.com/stripe/stripe-go/issues/1447
|
| [2]
| https://twitter.com/joshuaackerman/status/144759582096702259...
| 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?
| riwsky wrote:
| It'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.
| 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/
| __mharrison__ wrote:
| At this point using rst is like advocating for Subversion
| instead of Git(hub). (Which is actually a good metaphor
| considering where docutils is hosted...)
|
| I say this as a (former) committer to docutils.
|
| The LaTeX support is ok in rst if you want to create something
| similar to a Word document. If you actually wanted to print a
| book, you need to use something like my tool, rst2nitrile.
|
| The Python documentation folks seem to be interested in
| abstracting Sphinx to markdown as well with MyST...
|
| rst is a dead end at this point.
| 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.
| smaudet wrote:
| If you have to extend Markdown, the battle is lost. The
| basic core idea, is OK, but as soon as you find yourself
| needing to do more documenty things (lists with formatting,
| tables, etc.) its the wild, wild west - different extension
| standards CommonMark, Github style, etc., editor, or
| library of choice.
|
| Not to mention all the special-custom-component standards
| now which require code... the whole point of Markdown was
| you could just use any old text editor and be just as well
| off as looking at a prettified version.
|
| You have the higher complexity and learning curve anyways,
| more, even.
|
| I guess, the bad design decisions in RST are bad, but there
| are equally bad design decisions in all these new
| extensions, editors.
|
| Instead of trying use a hammer put in screws, we should
| just change tooling. If you need document-level formatting
| etc., plain-text formatting is cool but don't try to be
| markdown. Use markdown when you just need simple text docs,
| if you find yourself doing complex stuff maybe you
| shouldn't be using markdown, or at least not calling
| yourself "markdown".
| 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.
| __mharrison__ wrote:
| Funny you say that. I spent most of last week porting some of
| my rst based book authoring tooling to md/pandoc.
| 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.
| annagrigoryan2 wrote:
| Found this right when I was looking for a quality markdown
| parser.
|
| I guess it's my lucky day.
| 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-12 23:02 UTC)