Doks – Build a Docs Site | Hacker News Reader

Doks – Build a Docs Site

getdoks.org

59 pointshenk-verlinde42 comments

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.

> deep linking into a different document

This is difficult in every docu system.

Not hard with RST/Sphinx, but that comes with other usability nits.

It's fairly easy in rST. I just can never remember the syntax :P

We switched the iommi docs from markdown to rST for this and many other similar issues of rST being more powerful.

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)

What is deep linking into a different document? You mean to a header or something else?

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.

The lack of non-docutils implementations is easily explained by rst being essentially impossible to parse; it's also somewhat annoying to write, in particular with the distinct lack of nested markup and the very baroque indentation rules - try writing nested lists without accidentally putting half of them in blockquotes. That being said sphinx-doc works very well even for complex projects and most documentation tools are rather inferior, much like static site generators it's a straightforward project to get to a "works for me" point.

rst (and sphinx) are also one of the few (open source) options which have some support for multiple modalities.

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.

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.

[1.a] And continues to lock, in many industries.

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.

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.

[1] https://astro.build/themes/details/starlight/

Since we're at it, mkdocs with material ui is the only one I found that works perfectly well without JS.

is there any extended theme that supports blog and landing page along with doc from starlight that you are aware of?

How does this compare to mkdocs? It seems incredibly similar to me at a glance, each generating docs from human readable markdown files.

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.

[0] https://react.dev/reference/react-dom/server/renderToStaticM...

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.

Take for example this page: https://getdoks.org/docs/start-here/getting-started/ ; I presume they're using their own tool to render their own documentation?

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.

You may want to replace your browser with one that works:

https://imgur.com/a/0IOKXY8

Screenshot taken on Firefox 123.0, on macOS 14.1.

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:

  document.documentElement.setAttribute('data-bs-theme', 'dark')
  document.documentElement.setAttribute('data-bs-theme', 'light')

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.

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?

Also... generic markdown?

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.

Eyyyyy. My personal site currently runs on Doks! Check it out: https://foreverliketh.is/ Also, @henk-verlinde, I'm not on the showcase :^(

but why would a "Documentation" cms care about showcasing personal sites?

as someone who is interested in this, i do think that having personal sites on the showcase is a good thing

Why not? Diversity of sites is great.

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.

Also worth checking out: https://scalar.com

And https://github.com/rust-lang/mdBook

documentation is lacking for this theme. It was more comprehensive before the transition to hyas framework.

is there a way to bypass node+npm toolchain?

Not sure if it is acceptable, but you could put the entire building pipeline in a docker container

that's a good idea. still a bit heavy but preferred to installing the toolchain on the host OS

Agree, very heavy handed, but in this situation it seemed acceptable

Everything you need to build a stellar documentation website. Fast, accessible, and easy to use.

why is this downvoted? looks fine to me and he is the author of this tool?

I don't know who was first but their "Environmental impact" (https://getdoks.org/docs/start-here/environmental-impact/) page is a rip-off of the Startlight's (Astro theme for docs) one: https://starlight.astro.build/environmental-impact/ But without mentionning Starlight, which does better for Co² emissions.

And a lot of their other pages and the overall look & feel too seem copy/pasted (authoring, getting started...).

Not that this have huge value, but it doesn't bring confidence and I just made my doc on Starlight I would've like to see a page comparing the two since they're very similar. Why going with this one over the competitors ?

Oldest GitHub release for Doks appears to be from 2020:

https://github.com/gethyas/doks/releases?page=4

Oldest GitHub release for Starlight appears to be from 2023:

https://github.com/withastro/starlight/releases?page=9

Damn, I should stop assuming everything posted is brand new...

Thanks for the check, but weird none of the solutions put the other one in their environmental study.

Reply on news.ycombinator.com