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?
"Quarto® 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?
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.)
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
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!
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.)
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...
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.
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.
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.
We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs
> 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.
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
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?
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!
[1]: http://sgmljs.net
What kind of project or business that you run that you need it?
How much hours do you estimate it would have taken you?
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.
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.
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.
Very cool of them to open source this. Looks great.
Any framework that supports this functionality is a great contribution to OS
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...
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
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...
Job sounds super fun by the way :)
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 ...
[1]: https://mkdocstrings.github.io/
Or is this only for https://stripe.com/docs, https://stripe.com/docs/payments, etc?
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)
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
Might be easier to graft into an existing, dynamic CMS (that uses a DB)
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.
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.
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.
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”.)
What separates this from any of the existing markdown static site generators?
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.
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:
I think MSFT just uses stock DocFX for the Azure docs site, but I'm not sure.
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.
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.
I guess it's my lucky day.
On a side-note, mixing serifs and sans in the way the site does looks like something only a mass murderer would do.
