Another doc site that uses .md. Unfortunately md doesn't do a few things you want from a complex documentation (good and easy for small documents, but not powerful enough for complex projects). Things like deep linking into a different document rarely work.
Yeah. A lot of the new .md build systems are sprouting up to address the gaps between .md and complex pubs, a space occupied by the more complex LMLs (lightweight markup) like .adoc and .rst. This - for the Nth million time - beautifully illustrates conservation of complexity: you liked Markdown because low complexity, then you got complex requirements, now you have to shovel the complexity into a bespoke build system.
I understand there's a couple of .md forks dedicated to solving some of the problems with complex docs, but the trap phrase there is "a couple of forks". One writer goes with MDX, another writer uses a Jekyll script, another writer uses MultiMarkdown . . whoops! Broken pubs system.
I understand Markdown, and I like it. I like it a LOT[1]. But it's not for every use case.
[1] It led the charge against the XML Publications Fortress, which had[a] locked down documents inside of an ivory fortress for decades. Curious what the doc looks like? Want to contribute? TOO BAD. But then came Adam Schwartz on his White Horse, and the world was changed.
In the past, I've either dropped into just straight-up HTML for more complicated bits, or done two-pass rendering. (E.g., have input → tool A → documentation generator → docs. We do this to render a few tables in our docs from YAML data files that just contain the actual data in the table. Our doc system includes an "include this file" directive, so the result can be pasted into other prose still written normally.)
It's not completely optimal. I do wish M↓ supported things like admonitions (callouts for warnings, notes, todos) better, in particular, since our docs are rife with those.
Doks supports authoring content in Markdown and HTML with no configuration required. You can add support for Emacs Org-Mode, AsciiDoc, RST, and Pandoc by installing additional parsers.
From one document to the middle of a different one. I use restructured text which lets me link that way. It is a little tricky, but not difficult and makes it much easier to have documents reference others. I have separate user documentation from design documentation, but the design documentation often needs to reference the user documentation for the thing it just talked about to get into details that otherwise would have to be repeated.
Unfortunately restructure text is not nearly as popular as markdown and so lots of other tools I want either don't exist, or are out of date.
ReStructuredText (.rst, what Sphinx uses) handles it quite well. I understand why Markdown became so popular (super easy/intuitive) but what I don't understand is why so many documentation systems use it. It's quite limited... On purpose!
You want to support simple text features in a forum or comments on a website? Markdown is perfect. You want to support basically every documentation feature imaginable while still retaining reasonable ease-of-use? ReStructuredText is the way to go.
As I understand it, rST and Asciidoc are roughly equivalent in that they provide significant document-oriented upgrades to Markdown - upgrades that are on the order of Docbook. This makes them attractive. But you won't convince me that cross-document deep linking is a solved problem unless you accept that the use case is a static document base. Anything to do with products under continuing development is going to bring headaches. Is there any CMS that "solves" this in a robust way ? I wonder.
nah we use asciidoc for this. worked next to the guy who invented it back in the day. another team at our company used to to make topic-based authoring the CMS standard. been doing this fine for years now and even the writers seem happy (super rare for tech writers innit)
I don't want to crash this getdoks post (so you should check it out) but I searched far and wide across different docs setups and I'm SO happy with Starlight from the Astro folks.[1]
Supports Markdown, Markdoc (powers Stripe docs & is what we're using), MDX, and of course HTML.
Since it's built on Astro, it's super easy to extend with React, Vue, Svelte, Solid, or Qwik for interactive demos, code sandboxes, or other more complex features.
On that metric, everything is just like MkDocs. In my opinion, though, crucially, is that almost anything is better than MkDocs.
A couple of the problems with MkDocs:
- Themes available don't look really good, more thrown together than engineered. Most use MkDocs Material, the best features of which are paywalled.
- The MD rendering is weird,for example only some levels of indentation work for lists, breaking pages that work properly with other renderers. Another, more opinionated, example would be the odd admonition syntax.
Perhaps this comment is about to be an example of the classic "why not just rebuild XYZ technology to solve a simple problem already solved 100 times?" trope among engineers, but having used Hugo and a few other markdown-based documentation builders like this, why not just build a react site and build it to static HTML[0]? I think this is the approach I'll take in the future, it always seems like just as much if not more work to learn some new SSG framework and build components for it, and seems much more complicated to add complex functionality than the usual HTML/CSS/JS we're all familiar with. If anybody has taken this approach before, I'd be curious to know your reasoning on why and/or why not this is a good idea.
if you have large number of pages i.e. 1000+(its not that far fetched with documents) most of react/vue based solutions struggle in generating them in the sense that it takes long time to see output for any change you make.
Its question o familiarity if you are not aware of react than it would take even more time for you to learn it and use it than ssg frameworks.
you can still use your familiar html/css/js if you want to without learning whole ssg almost all ssg frameworks provide a way to code html/css if required.
ssg's are battle tested when it comes to myriad seo features like twitter cards/og/json-ld/schema etc. which are proven to be working in the field. When you go for rolling out on your own you will end up in solving lot of edge cases that different platforms(twitter/fb/google) have that would result in cover image not being displayed properly to site not appearing in google etc.
It seems to have some pretty basic bugs? Teletype renders as censoring, essentially: https://i.imgur.com/fyi32mR.png (what I can only presume is a light mode/dark mode half & half type situation…)
That doesn't convince me it's ready for prime time, though.
Curiously, that was FF 123.0b2, on macOS 13.1. Pretty close.
These things are almost always bugs in JavaScript running on the site, IME.
If I inspect a tt, it's setting a background of slate (black), and a foreground of "inherit", which is black. This is just messed up CSS, and the inspector seems to indicate that the JS on the page is crashing, and I see there's a sun/moon hieroglyph in the corner, i.e., there's JS for controlling light/dark mode.
It seems like the code responsible for the light/dark mode must run one of these two things:
If neither happens, the page is left with the default styling, which is a bizarre mix of light/dark mode and contains the issues I've screenshotted.
Neither happens, because slightly prior to that, the JS makes a call to a fallible function, and then subsequently fails to handle the error case. The uncaught exception kills it before it can call one of the two above lines, so we're left with a page with broken styling.
What does this do that all the other Hugo docs templates don't do?
The "Showcase" section just shows a bunch of non-docs stuff. Why would I use this instead of readthedocs, gitbook, docasaurus, or any of the million others?
which other hugo docs? i am looking for some good hugo docs and all of them are either ugly or don't implement landing+blog which would require additional effort from user for that functionality. Only good ones are this theme lotusdocs and hashnode.
I used this just a couple months ago to build a multilingual docs site. The site turned out great! Was able to train a couple people to use GitHub’s built in editor to manage the content themselves.
Readit News
I understand there's a couple of .md forks dedicated to solving some of the problems with complex docs, but the trap phrase there is "a couple of forks". One writer goes with MDX, another writer uses a Jekyll script, another writer uses MultiMarkdown . . whoops! Broken pubs system.
I understand Markdown, and I like it. I like it a LOT[1]. But it's not for every use case.
[1] It led the charge against the XML Publications Fortress, which had[a] locked down documents inside of an ivory fortress for decades. Curious what the doc looks like? Want to contribute? TOO BAD. But then came Adam Schwartz on his White Horse, and the world was changed.
[1.a] And continues to lock, in many industries.
It's not completely optimal. I do wish M↓ supported things like admonitions (callouts for warnings, notes, todos) better, in particular, since our docs are rife with those.
Deleted Comment
Deleted Comment
Deleted Comment
Unfortunately restructure text is not nearly as popular as markdown and so lots of other tools I want either don't exist, or are out of date.
This is difficult in every docu system.
You want to support simple text features in a forum or comments on a website? Markdown is perfect. You want to support basically every documentation feature imaginable while still retaining reasonable ease-of-use? ReStructuredText is the way to go.
We switched the iommi docs from markdown to rST for this and many other similar issues of rST being more powerful.
Supports Markdown, Markdoc (powers Stripe docs & is what we're using), MDX, and of course HTML. Since it's built on Astro, it's super easy to extend with React, Vue, Svelte, Solid, or Qwik for interactive demos, code sandboxes, or other more complex features.
[1] https://astro.build/themes/details/starlight/
A couple of the problems with MkDocs: - Themes available don't look really good, more thrown together than engineered. Most use MkDocs Material, the best features of which are paywalled. - The MD rendering is weird,for example only some levels of indentation work for lists, breaking pages that work properly with other renderers. Another, more opinionated, example would be the odd admonition syntax.
[0] https://react.dev/reference/react-dom/server/renderToStaticM...
Its question o familiarity if you are not aware of react than it would take even more time for you to learn it and use it than ssg frameworks.
you can still use your familiar html/css/js if you want to without learning whole ssg almost all ssg frameworks provide a way to code html/css if required.
ssg's are battle tested when it comes to myriad seo features like twitter cards/og/json-ld/schema etc. which are proven to be working in the field. When you go for rolling out on your own you will end up in solving lot of edge cases that different platforms(twitter/fb/google) have that would result in cover image not being displayed properly to site not appearing in google etc.
It seems to have some pretty basic bugs? Teletype renders as censoring, essentially: https://i.imgur.com/fyi32mR.png (what I can only presume is a light mode/dark mode half & half type situation…)
That doesn't convince me it's ready for prime time, though.
https://imgur.com/a/0IOKXY8
Screenshot taken on Firefox 123.0, on macOS 14.1.
These things are almost always bugs in JavaScript running on the site, IME.
If I inspect a tt, it's setting a background of slate (black), and a foreground of "inherit", which is black. This is just messed up CSS, and the inspector seems to indicate that the JS on the page is crashing, and I see there's a sun/moon hieroglyph in the corner, i.e., there's JS for controlling light/dark mode.
It seems like the code responsible for the light/dark mode must run one of these two things:
If neither happens, the page is left with the default styling, which is a bizarre mix of light/dark mode and contains the issues I've screenshotted.Neither happens, because slightly prior to that, the JS makes a call to a fallible function, and then subsequently fails to handle the error case. The uncaught exception kills it before it can call one of the two above lines, so we're left with a page with broken styling.
It's a JavaScript bug.
The "Showcase" section just shows a bunch of non-docs stuff. Why would I use this instead of readthedocs, gitbook, docasaurus, or any of the million others?
Also... generic markdown?