7 ms·
Doks – Build a Docs Site
- henk-verlinde 3y agoEverything you need to build a stellar documentation website. Fast, accessible, and easy to use.
- newusertoday 3y agowhy is this downvoted? looks fine to me and he is the author of this tool?
- leesalminen 3y agoI 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_ 3y agoI don't know who was first but their "Environmental impact" (https://getdoks.org/docs/start-here/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/ 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 ?
- michaelmcdonald 3y agoOldest GitHub release for Doks appears to be from 2020: https://github.com/gethyas/doks/releases?page=4 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 https://github.com/withastro/starlight/releases?page=9
- flinth_ 3y agoDamn, 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 3y agoHow does this compare to mkdocs? It seems incredibly similar to me at a glance, each generating docs from human readable markdown files.
- FireInsight 3y agoOn 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.
- bluGill 3y agoAnother 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 3y ago> deep linking into a different document This is difficult in every docu system.
- LegibleCrimson 3y agoNot hard with RST/Sphinx, but that comes with other usability nits.
- boxed 3y agoIt'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 3y agoReStructuredText (.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 3y agoAs 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.
- nbrempel 3y agoAlso worth checking out: https://scalar.com https://scalar.com
- ivanjermakov 3y agoAnd https://github.com/rust-lang/mdBook https://github.com/rust-lang/mdBook
- deathanatos 3y agoTake for example this page: https://getdoks.org/docs/start-here/getting-started/ 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 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 3y agoYou may want to replace your browser with one that works: https://imgur.com/a/0IOKXY8 https://imgur.com/a/0IOKXY8 Screenshot taken on Firefox 123.0, on macOS 14.1.
- deathanatos 3y agoCuriously, 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.
- tonymet 3y agois there a way to bypass node+npm toolchain?
- Fire-Dragon-DoL 3y agoNot sure if it is acceptable, but you could put the entire building pipeline in a docker container
- tonymet 3y agothat's a good idea. still a bit heavy but preferred to installing the toolchain on the host OS
- Fire-Dragon-DoL 3y agoAgree, very heavy handed, but in this situation it seemed acceptable
- FLpxpyJ 3y agoEyyyyy. My personal site currently runs on Doks! Check it out: https://foreverliketh.is/ https://foreverliketh.is/ Also, @henk-verlinde, I'm not on the showcase :^(
- ninacomputer 3y agobut why would a "Documentation" cms care about showcasing personal sites?
- toddmorey 3y agoI 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/ https://astro.build/themes/details/starlight/
- rudasn 3y agoSince we're at it, mkdocs with material ui is the only one I found that works perfectly well without JS.
- newusertoday 3y agois there any extended theme that supports blog and landing page along with doc from starlight that you are aware of?
- methodical 3y agoPerhaps 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/renderToStaticMarkup https://react.dev/reference/react-dom/server/renderToStaticM...
- newusertoday 3y agoif 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.
- ninacomputer 3y agoWhat 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?
- newusertoday 3y agowhich 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.
- newusertoday 3y agodocumentation is lacking for this theme. It was more comprehensive before the transition to hyas framework.