[HN Gopher] Doks - Build a Docs Site
___________________________________________________________________
Doks - Build a Docs Site
Author : henk-verlinde
Score : 44 points
Date : 2024-03-05 16:25 UTC (6 hours ago)
(HTM) web link (getdoks.org)
(TXT) w3m dump (getdoks.org)
| henk-verlinde wrote:
| Everything you need to build a stellar documentation website.
| Fast, accessible, and easy to use.
| leesalminen wrote:
| 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.
| flinth_ wrote:
| 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 Co2 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 ?
| michaelmcdonald wrote:
| 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
| flinth_ wrote:
| 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.
| ApolloFortyNine wrote:
| How does this compare to mkdocs? It seems incredibly similar to
| me at a glance, each generating docs from human readable markdown
| files.
| bluGill wrote:
| 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.
| euroderf wrote:
| > deep linking into a different document
|
| This is difficult in every docu system.
| LegibleCrimson wrote:
| Not hard with RST/Sphinx, but that comes with other usability
| nits.
| boxed wrote:
| 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.
| riskable wrote:
| 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.
| euroderf wrote:
| 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.
| mosselman wrote:
| What is deep linking into a different document? You mean to a
| header or something else?
| bluGill wrote:
| 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.
| formerly_proven wrote:
| 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.
| deathanatos wrote:
| 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.
| MilStdJunkie wrote:
| 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.
| nbrempel wrote:
| Also worth checking out: https://scalar.com
| ivanjermakov wrote:
| And https://github.com/rust-lang/mdBook
| deathanatos wrote:
| 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.
| cstrahan wrote:
| 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.
| tonymet wrote:
| is there a way to bypass node+npm toolchain?
| FLpxpyJ wrote:
| Eyyyyy. My personal site currently runs on Doks! Check it out:
| https://foreverliketh.is/ Also, @henk-verlinde, I'm not on the
| showcase :^(
| toddmorey wrote:
| 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/
| rudasn wrote:
| Since we're at it, mkdocs with material ui is the only one I
| found that works perfectly well without JS.
| methodical wrote:
| 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...
___________________________________________________________________
(page generated 2024-03-05 23:01 UTC)