41–50 of 89 posts
Yes, it's extensible. But I don't want to write a role just to add bold to a reference!
Markdoc just hits the sweet spot of being super easy to get started with but elegantly extensible that makes it scale. I think the OP here simplifies a bit though of what Markdoc is. While it is pretty simple to integrate into a next.js site for a SSG doc site, it is more of a library that can be integrated into almost any site or rendering framework.
In some ways, this is the biggest "challenge" of Markdoc right now. It isn't focused on a polished out-of-the-box experience like Docusaurus or MKDocs, but is instead more of a DIY tool.
That said though, what is there is really great. With the ability to create custom tags easily and then the ability to analyze and transform an AST in a simple, but easy to understand way, I think markdoc is actually a great option for more than just building a doc site, but as a more general purpose tool for authoring any text-heavy content.
With Markdoc, I have built: * a higher level utility for creating a "library" of content with consistent ids for stable and validated links * a validation library to ensure that doc structures follows best practices like having metadata tags in the frontmatter, properly nests headers and doesn't skip H3s, etc * an integration for authoring and reusing doc content in spectacle[0] presentations * have a clear direction of how to "scale" docs-as-code as we were struggling to do that with a simple, flat file of markdown files
I have started to toy with the idea of a more general purpose CMS built around markdoc... but in general, a really great tool and kudos to stripe team for building it :)
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.
PDFs I've written in Markdown and typeset using ConTeXt:
* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...
* https://pdfhost.io/v/mhw8jCJzw_autnoma
* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
* https://impacts.to/downloads/lowres/impacts.pdf
I think Markdown can be used in serious documentation projects. I am biased, given that I've been working on my free and open source, cross-platform Markdown editor for several years:
https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable. Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be ta…
What is "regular markup"?
> Most folks mention that Markdown is not suitable for serious documentation projects. PDFs I've written in Markdown and typeset using ConTeXt: * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... * https://pdfhost.io/v/mhw8jCJzw_autnoma * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... * https://impacts.to/downloads/lowres/impacts.pdf I think Markdown can be used in serious documentation…
I've been generating PDF documentation with Obsidian. The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
I love Asciidoc, but the tooling is pretty crummy. It's not much fun to install and manage asciidoctor if you aren't into the ruby space, and pandoc doesn't take asciidoc as an input. Its the first I'm hearing of Antora though, so I'll be sure to check that out.
I agree. Every time I think about picking a markup language, I wind up wanting to use Asciidoc but then getting frustrated by the tooling. Maybe there's a great static site generator written in GO with strong Asciidoc support?? Antora is new to me as well, will review.
I love Asciidoc, but the tooling is pretty crummy. It's not much fun to install and manage asciidoctor if you aren't into the ruby space, and pandoc doesn't take asciidoc as an input. Its the first I'm hearing of Antora though, so I'll be sure to check that out.
I thought the answer always was "pandoc" when the question was (un)structured markup...
"The original version of Markdown by John Gruber doesn’t specify the syntax unambiguously. For example, it doesn’t have table formatting."
Table formatting is an example of a missing feature in a deliberately minimalist specification. Or possibly a feature that is handled elsewhere in the markdown "stack" (by html). So if the syntax is indeed not specified unambiguously (facts not in evidence?) then this isn't a good way of demonstrating that.