7 ms·

I was hoping for something I could use to generate my docs, but this is so incredibly over-engineered it's comical to me. React components, MDX, TypeScript conf

by brabel 4y ago

I was hoping for something I could use to generate my docs, but this is so incredibly over-engineered it's comical to me. React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs? I have my own little markdown-to-html static site generator that does nearly everything I would ever need, and it only uses a small library for conversion MD to html plus a custom, very simple templating language to do things like include other files or get a list of files in another dir so you can create a list of links... and that's it. You can probably write one yourself on a weekend. I will be sticking with my own, thanks.

rat9988 4y ago
React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs? No you don't, you only need to write the markdown.
- slorber 4y ago
  Yes, and that's exactly the value proposition of Docusaurus. You just write markdown files. Eventually you create a custom landing page with React (optional, we also support a Markdown landing page). If you want to customize your site, you can use more advanced tools, but really you can stick to Markdown if you want something simple. Now Docusaurus uses advanced things under the hood, but it's an implementation detail, not something you really have to deal with. Just try it and see: docusaurus.new
manigandham 4y ago
You don't need any of it. It's included in the framework if you want to make your docs more interactive but you can stick to plain text in markdown (like most of these frameworks).
tommica 4y ago
I use this to run my project docs, no compiling, just one index.html and the rest are markdown files: http://dynalon.github.io/mdwiki/#!index.md http://dynalon.github.io/mdwiki/#!index.md
- esprehn 4y ago
  Your docs seem to flash unstyled content for a second before the CSS loads.
- slorber 4y ago
  This is not really comparable to Docusaurus: your thing is a little toy to publish documentation online but not really useful to create a great advanced and looking doc site. Just consider this: your tool requires client-side JS to work. This is very inaccessible and does not respect the progressive enhancement philosophy of the web. A Docusaurus site takes great care of accessibility, and the experience with JS disabled remains good. Also using JS this way with anchor link routing will likely lead to bad SEO, and a flash of unstyled content which gives a really bad UX.
  - badsectoracula 4y ago
    At least as a user i find tommica's "toy" much faster and easier on the eyes than the showcase sites in Docusaurus. The only negative is that small visible "reflow" whenever a page loads. EDIT: the courier and ionic examples linked elsewhere were faster though.
  - michaelmcdonald 4y ago
    As the rep for a product: I wouldn't recommend bashing someone's project by calling it a "little toy". It works for them regardless if it looks as "fancy" as yours. Not a positive look for you or your project if this is how you're going to treat others.
    - slorber 4y ago
      Maybe the word "toy" is wrong and I'm sorry for that if it offended anymore But I stand by that such documentation tools are really not great. I've argued why here: https://news.ycombinator.com/item?id=32305770 https://news.ycombinator.com/item?id=32305770 Now if you clearly understand the tradeoffs of such tools and still decide to use it, that's fine. What I see in practice is that many decide to use such tool and are not really aware of the tradeoffs they make. I personally believe being accessible is a mandatory feature for any documentation website framework. But maybe you'll publish the docs just for yourself or a very limited set of persons, in which case you might care less.
Kolja 4y ago
I thought so, too. I've switched to mdbook[1], which is more lightweight, and (at least at the time) was one of the few solutions that compiled down to a directory that can be used without limitations while offline. [1]: https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/ – the website itself is a demo of the sites produced by mdbook.
- slorber 4y ago
  Docusaurus has a PWA plugin with offline support https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pw... We'll look into more "offline supports" in the future including producing pdf files etc (it already exists but as community plugins)
  - Kolja 4y ago
    I'm sure that Docusaurus can do a lot, and more in the future. I think the resulting pages feel a little heavy to use (how they load and react in a browser), but that's just my personal opinion. I had tried to find a tool that would be simple, quick to use, and as close to a static HTML page as possible while still retaining a "book" character. Even a Vimwiki HTML export would have been an option, were Vimwiki's Markdown support better. Mdbooks fit the bill, and does not seem to stray too much from that initial direction, as far as I can tell.
- fluidcruft 4y ago
  Just curious whether rust is an advantage for this sort of a tool? I don't know much about rust but my impression is that it's a systems language like C/C++. Is security a major problem for this sort of a build tool? It just seems like of I were writing something that processes text using a C/C++ class language isn't going to maintain well or be easy to adapt, extend or customize.
  - slorber 4y ago
    IMHO Rust is useful for its speed. Many frontend tools use Rust today (like swc, napi-rs...). We are willing to include Rust in Docusaurus in the future (alongside Node.js), as it can help to build the static doc site faster. BTW our docusaurus prod site (docusaurus.io) is built using swc already (https://swc.rs/ https://swc.rs/) Now using a 100% Rust tool to build a doc site would be great too, but at the end of the day if you want a great experience you'll also need some JS and not just plain static HTML files. And Rust devs are more likely less "frontend-y" (I've been a backend Scala dev 10 years ago, I know how good looking UIs are produced by backend devs ^^). So I guess a combination of Node.js + Rust is great, and the frontend community that care about UI/UX is more likely to contribute to the JS side to polish things.
mynameisash 4y ago
My team uses Docusaurus for internal docs. I just had to make my first contribution to that repo the other day, and it was a mess. Docusaurus didn't work from within WSL (well, it mostly worked but every page load crashed when viewing), so switching to native Windows NPM and the several dependencies and installation steps to get it working took about a half hour with the help of a colleague who knew how it worked. And ultimately, it was just so I could write markdown. The generated docs are nice, to be sure, but I certainly would not go through that pain if I had to go documentation from scratch.
- slorber 4y ago
  Hey, Docusaurus even works in your browser docusaurus.new I'm not sure why you went through all this pain, but if you don't report it, how can we fix it? Others do not have the same experience afaik.
eg312 4y ago
That's why I made https://reactivedoc.com/ https://reactivedoc.com/. You can use it to write interactive documentation in markdown and save it as a simple, self-contained, html+js file. Now I'm working on v2, with cleaner syntax & more widgets (I want to add an embedded web base terminal to run shell commands), you can see an example here: https://reactivedoc.com/editor/ https://reactivedoc.com/editor/
- slorber 4y ago
  What does it solve that Docusaurus does not solve? With MDX you can embed JS and/or React in Markdown already
  - eg312 4y ago
    I just needed a quick way to write in MD and have 'templates' with parameters to avoid copy/paste/replace, especially when documenting shell commands.
slorber 4y ago
With Docusaurus we are looking to compete with top notch documentations, not simple ones. The goal is not only to get some html files online but also to great a first-class experience for the end user. Do you truly believe that your home-made setup would be sufficient to output a top-notch doc site? Really curious to see what kind of site your setup produce, can you share a live url so that we can compare? Docusaurus v2 has a site showcase with many great looking sites: https://docusaurus.io/showcase https://docusaurus.io/showcase Many companies using it: Supabase, Redis, Figma, Ionic, Snapchat, LinkedIn, Microsoft, Shopify, Tauri... I doubt these companies would be satisfied with a home-made setup like yours. If you don't have advanced needs, you could as well just publish md files on GitHub?
- nindalf 4y ago
  I wouldn’t worry too much about that comment. The top comment is very much in keeping with the HN tradition of trashing others’ work without fully understanding the use case. My favourite HN comment went like “For a Linux user, you can already build such a system yourself quite trivially by getting an FTP account, mounting it locally with curlftpfs, and then using SVN or CVS on the mounted filesystem.” (https://news.ycombinator.com/item?id=8863 https://news.ycombinator.com/item?id=8863) Fortunately the person this was addressed to continued building Dropbox.
  - slorber 4y ago
    ahah, I welcome all comments, haters are a good source of engagement ;)
- taffit 4y ago
  Well, there's a tool for every task and yours in this case might be too overblown for the simple task that the user is trying to solve. No need to compare it to the use at bigger companies and organizations. No need to either get arrogant or stroppy. Just because a user doesn't use your tool, she is not a hater, neither. Sound a bit like "But mine is better/bigger/shinier than yours!" to me. Keep cool.
  - 4y ago
vanilla_nut 4y ago
You don’t need it to write docs. But, as someone who’s worked in a relatively large documentation org… it’s nice to have a stable, extensible base that you can extend consistently across multiple docs sites. It’s ideal to have a similar look and feel, but the flexibility to tweak that for each product. Basic docs sites can literally just be HTML. But the more you maintain them, the more you want to experiment with novel methods of documentation (think: interactive consoles, new methods of styling guides and tutorials like Apple’s SwiftUI docs, or even new methods of segmenting content within a single docs site (SDK and versioning selectors, anyone?))… eventually, simple tools will hold you back. Or you’ll end up building an unmaintainable nightmare on top of a simple tool. In those cases, it’s nice to use a “batteries included” product so you don’t have to write all of that infrastructure yourself. For personal blogs and small docs sites, it’s overkill of course. But in docs land just as in developer land, ICs want to build new skills for their resumes or personal interest. And, of course… it has a built in dark mode! Harder to find than you’d think.
- slorber 4y ago
  Thanks for the feedback Agree Docusaurus might be overkill for simple docs, however we also made sure the experience for simple usage is great. It comes with file-system routing convention, versioning, accessibility, internationalization, good SEO by default and many useful features that would take time to build in userland... We have many devs using Docusaurus as a portfolio or personal blog, we even have a dedicated showcase tag for that: https://docusaurus.io/showcase?tags=personal https://docusaurus.io/showcase?tags=personal For advanced needs, like multi-sdk support, we get you covered. Site with multiple frontend SDKs (React, Angular...): https://docs.dyte.io/react-ui-kit https://docs.dyte.io/react-ui-kit Palo Alto Networks has a dev portal with multiple products using Docusaurus, all sharing similarities but with tweaks per product: - https://xsoar.pan.dev/ https://xsoar.pan.dev/ - https://prisma.pan.dev/ https://prisma.pan.dev/
- swyx 4y ago
  yes - people should match their docs offerings to the maturity of their project: https://www.swyx.io/documentation-levels https://www.swyx.io/documentation-levels and not dismiss out of hand tools that accommodate a different level than they are currently at.
EGreg 4y ago
I came to write this. Was also hoping for a docs generator from my YUIDoc source code comments in PHP and JS. Is there anything out there that works with YUIDoc or something I can transform it into? Anything? As it is, we are using YUIDoc and themes to generate documentation and it’s pretty good.
- slorber 4y ago
  If you can find a way to generate md files from YUIDoc, then Docusaurus could consume those MD files. We have seen many examples of Docusaurus sites generating pages from code comments, GraphQL or OpenAPI schemas For example here's a plugin that does something akin to what you want, but from TS comments: https://www.npmjs.com/package/docusaurus-plugin-typedoc https://www.npmjs.com/package/docusaurus-plugin-typedoc And here is an example integration of Redoc/OpenAPI in Docusaurus: https://redocusaurus.vercel.app/examples/using-single-yaml/ https://redocusaurus.vercel.app/examples/using-single-yaml/
ndimares 4y ago
I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advanced' features. Docs are going to be one of your most used interfaces. But you should make sure that making docs 'pretty' isn't detracting from usability. If you're making internal docs, then ya, I agree with you, keep it dead simple.
- slorber 4y ago
  > Unless you're spinning up a documentation team with engineering resources, you probably want Docusaurus! > Rachel Nabors, Former ReactJS & React-Native docs manager > https://twitter.com/rachelnabors/status/1452697991039660038 https://twitter.com/rachelnabors/status/1452697991039660038 Actually I don't consider Docusaurus as a real investment. altough as a non-Node.js/React dev all this might sound complex, but this is actually the basic stack for many frontend devs today, not something very fancy. Investing in your docs mean assembling a tech team for a long effort to build a first class experience. I believe you can achieve something almost as good as a full team by having just 1 engineer working on your Docusaurus doc a few hours per week. > If you're making internal docs, then ya, I agree with you, keep it dead simple. Internal docs also deserve a great DX. You can use Docusaurus for internal docs, and use our stock template to get started in a few minutes: just write markdown files. We have been reported heavy usage of Docusaurus at Microsoft and LinkedIn for internal documentations for example. This is what our stock template look out of the box: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/ You don't have to do anything to have this DX: just write md files. Maybe you can already feed Docuaurus with your existing md files, and it will just work without any change.

by brabel 4y ago

rat9988 4y ago

React components, MDX, TypeScript config files, CSS-in-JS? Do you really need all that to write docs? No you don't, you only need to write the markdown.

slorber 4y ago
Yes, and that's exactly the value proposition of Docusaurus. You just write markdown files. Eventually you create a custom landing page with React (optional, we also support a Markdown landing page). If you want to customize your site, you can use more advanced tools, but really you can stick to Markdown if you want something simple. Now Docusaurus uses advanced things under the hood, but it's an implementation detail, not something you really have to deal with. Just try it and see: docusaurus.new

manigandham 4y ago

You don't need any of it. It's included in the framework if you want to make your docs more interactive but you can stick to plain text in markdown (like most of these frameworks).

tommica 4y ago

I use this to run my project docs, no compiling, just one index.html and the rest are markdown files: http://dynalon.github.io/mdwiki/#!index.md http://dynalon.github.io/mdwiki/#!index.md

esprehn 4y ago
Your docs seem to flash unstyled content for a second before the CSS loads.
slorber 4y ago
This is not really comparable to Docusaurus: your thing is a little toy to publish documentation online but not really useful to create a great advanced and looking doc site. Just consider this: your tool requires client-side JS to work. This is very inaccessible and does not respect the progressive enhancement philosophy of the web. A Docusaurus site takes great care of accessibility, and the experience with JS disabled remains good. Also using JS this way with anchor link routing will likely lead to bad SEO, and a flash of unstyled content which gives a really bad UX.
- badsectoracula 4y ago
  At least as a user i find tommica's "toy" much faster and easier on the eyes than the showcase sites in Docusaurus. The only negative is that small visible "reflow" whenever a page loads. EDIT: the courier and ionic examples linked elsewhere were faster though.
- michaelmcdonald 4y ago
  As the rep for a product: I wouldn't recommend bashing someone's project by calling it a "little toy". It works for them regardless if it looks as "fancy" as yours. Not a positive look for you or your project if this is how you're going to treat others.
  - slorber 4y ago
    Maybe the word "toy" is wrong and I'm sorry for that if it offended anymore But I stand by that such documentation tools are really not great. I've argued why here: https://news.ycombinator.com/item?id=32305770 https://news.ycombinator.com/item?id=32305770 Now if you clearly understand the tradeoffs of such tools and still decide to use it, that's fine. What I see in practice is that many decide to use such tool and are not really aware of the tradeoffs they make. I personally believe being accessible is a mandatory feature for any documentation website framework. But maybe you'll publish the docs just for yourself or a very limited set of persons, in which case you might care less.

Kolja 4y ago

I thought so, too. I've switched to mdbook[1], which is more lightweight, and (at least at the time) was one of the few solutions that compiled down to a directory that can be used without limitations while offline. [1]: https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/ – the website itself is a demo of the sites produced by mdbook.

slorber 4y ago
Docusaurus has a PWA plugin with offline support https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pw... We'll look into more "offline supports" in the future including producing pdf files etc (it already exists but as community plugins)
- Kolja 4y ago
  I'm sure that Docusaurus can do a lot, and more in the future. I think the resulting pages feel a little heavy to use (how they load and react in a browser), but that's just my personal opinion. I had tried to find a tool that would be simple, quick to use, and as close to a static HTML page as possible while still retaining a "book" character. Even a Vimwiki HTML export would have been an option, were Vimwiki's Markdown support better. Mdbooks fit the bill, and does not seem to stray too much from that initial direction, as far as I can tell.
fluidcruft 4y ago
Just curious whether rust is an advantage for this sort of a tool? I don't know much about rust but my impression is that it's a systems language like C/C++. Is security a major problem for this sort of a build tool? It just seems like of I were writing something that processes text using a C/C++ class language isn't going to maintain well or be easy to adapt, extend or customize.
- slorber 4y ago
  IMHO Rust is useful for its speed. Many frontend tools use Rust today (like swc, napi-rs...). We are willing to include Rust in Docusaurus in the future (alongside Node.js), as it can help to build the static doc site faster. BTW our docusaurus prod site (docusaurus.io) is built using swc already (https://swc.rs/ https://swc.rs/) Now using a 100% Rust tool to build a doc site would be great too, but at the end of the day if you want a great experience you'll also need some JS and not just plain static HTML files. And Rust devs are more likely less "frontend-y" (I've been a backend Scala dev 10 years ago, I know how good looking UIs are produced by backend devs ^^). So I guess a combination of Node.js + Rust is great, and the frontend community that care about UI/UX is more likely to contribute to the JS side to polish things.

mynameisash 4y ago

My team uses Docusaurus for internal docs. I just had to make my first contribution to that repo the other day, and it was a mess. Docusaurus didn't work from within WSL (well, it mostly worked but every page load crashed when viewing), so switching to native Windows NPM and the several dependencies and installation steps to get it working took about a half hour with the help of a colleague who knew how it worked. And ultimately, it was just so I could write markdown. The generated docs are nice, to be sure, but I certainly would not go through that pain if I had to go documentation from scratch.

slorber 4y ago
Hey, Docusaurus even works in your browser docusaurus.new I'm not sure why you went through all this pain, but if you don't report it, how can we fix it? Others do not have the same experience afaik.

eg312 4y ago

That's why I made https://reactivedoc.com/ https://reactivedoc.com/. You can use it to write interactive documentation in markdown and save it as a simple, self-contained, html+js file. Now I'm working on v2, with cleaner syntax & more widgets (I want to add an embedded web base terminal to run shell commands), you can see an example here: https://reactivedoc.com/editor/ https://reactivedoc.com/editor/

slorber 4y ago
What does it solve that Docusaurus does not solve? With MDX you can embed JS and/or React in Markdown already
- eg312 4y ago
  I just needed a quick way to write in MD and have 'templates' with parameters to avoid copy/paste/replace, especially when documenting shell commands.

slorber 4y ago

With Docusaurus we are looking to compete with top notch documentations, not simple ones. The goal is not only to get some html files online but also to great a first-class experience for the end user. Do you truly believe that your home-made setup would be sufficient to output a top-notch doc site? Really curious to see what kind of site your setup produce, can you share a live url so that we can compare? Docusaurus v2 has a site showcase with many great looking sites: https://docusaurus.io/showcase https://docusaurus.io/showcase Many companies using it: Supabase, Redis, Figma, Ionic, Snapchat, LinkedIn, Microsoft, Shopify, Tauri... I doubt these companies would be satisfied with a home-made setup like yours. If you don't have advanced needs, you could as well just publish md files on GitHub?

nindalf 4y ago
I wouldn’t worry too much about that comment. The top comment is very much in keeping with the HN tradition of trashing others’ work without fully understanding the use case. My favourite HN comment went like “For a Linux user, you can already build such a system yourself quite trivially by getting an FTP account, mounting it locally with curlftpfs, and then using SVN or CVS on the mounted filesystem.” (https://news.ycombinator.com/item?id=8863 https://news.ycombinator.com/item?id=8863) Fortunately the person this was addressed to continued building Dropbox.
- slorber 4y ago
  ahah, I welcome all comments, haters are a good source of engagement ;)
taffit 4y ago
Well, there's a tool for every task and yours in this case might be too overblown for the simple task that the user is trying to solve. No need to compare it to the use at bigger companies and organizations. No need to either get arrogant or stroppy. Just because a user doesn't use your tool, she is not a hater, neither. Sound a bit like "But mine is better/bigger/shinier than yours!" to me. Keep cool.
- 4y ago

vanilla_nut 4y ago

You don’t need it to write docs. But, as someone who’s worked in a relatively large documentation org… it’s nice to have a stable, extensible base that you can extend consistently across multiple docs sites. It’s ideal to have a similar look and feel, but the flexibility to tweak that for each product. Basic docs sites can literally just be HTML. But the more you maintain them, the more you want to experiment with novel methods of documentation (think: interactive consoles, new methods of styling guides and tutorials like Apple’s SwiftUI docs, or even new methods of segmenting content within a single docs site (SDK and versioning selectors, anyone?))… eventually, simple tools will hold you back. Or you’ll end up building an unmaintainable nightmare on top of a simple tool. In those cases, it’s nice to use a “batteries included” product so you don’t have to write all of that infrastructure yourself. For personal blogs and small docs sites, it’s overkill of course. But in docs land just as in developer land, ICs want to build new skills for their resumes or personal interest. And, of course… it has a built in dark mode! Harder to find than you’d think.

slorber 4y ago
Thanks for the feedback Agree Docusaurus might be overkill for simple docs, however we also made sure the experience for simple usage is great. It comes with file-system routing convention, versioning, accessibility, internationalization, good SEO by default and many useful features that would take time to build in userland... We have many devs using Docusaurus as a portfolio or personal blog, we even have a dedicated showcase tag for that: https://docusaurus.io/showcase?tags=personal https://docusaurus.io/showcase?tags=personal For advanced needs, like multi-sdk support, we get you covered. Site with multiple frontend SDKs (React, Angular...): https://docs.dyte.io/react-ui-kit https://docs.dyte.io/react-ui-kit Palo Alto Networks has a dev portal with multiple products using Docusaurus, all sharing similarities but with tweaks per product: - https://xsoar.pan.dev/ https://xsoar.pan.dev/ - https://prisma.pan.dev/ https://prisma.pan.dev/
swyx 4y ago
yes - people should match their docs offerings to the maturity of their project: https://www.swyx.io/documentation-levels https://www.swyx.io/documentation-levels and not dismiss out of hand tools that accommodate a different level than they are currently at.

EGreg 4y ago

I came to write this. Was also hoping for a docs generator from my YUIDoc source code comments in PHP and JS. Is there anything out there that works with YUIDoc or something I can transform it into? Anything? As it is, we are using YUIDoc and themes to generate documentation and it’s pretty good.

slorber 4y ago
If you can find a way to generate md files from YUIDoc, then Docusaurus could consume those MD files. We have seen many examples of Docusaurus sites generating pages from code comments, GraphQL or OpenAPI schemas For example here's a plugin that does something akin to what you want, but from TS comments: https://www.npmjs.com/package/docusaurus-plugin-typedoc https://www.npmjs.com/package/docusaurus-plugin-typedoc And here is an example integration of Redoc/OpenAPI in Docusaurus: https://redocusaurus.vercel.app/examples/using-single-yaml/ https://redocusaurus.vercel.app/examples/using-single-yaml/

ndimares 4y ago

I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advanced' features. Docs are going to be one of your most used interfaces. But you should make sure that making docs 'pretty' isn't detracting from usability. If you're making internal docs, then ya, I agree with you, keep it dead simple.

slorber 4y ago
> Unless you're spinning up a documentation team with engineering resources, you probably want Docusaurus! > Rachel Nabors, Former ReactJS & React-Native docs manager > https://twitter.com/rachelnabors/status/1452697991039660038 https://twitter.com/rachelnabors/status/1452697991039660038 Actually I don't consider Docusaurus as a real investment. altough as a non-Node.js/React dev all this might sound complex, but this is actually the basic stack for many frontend devs today, not something very fancy. Investing in your docs mean assembling a tech team for a long effort to build a first class experience. I believe you can achieve something almost as good as a full team by having just 1 engineer working on your Docusaurus doc a few hours per week. > If you're making internal docs, then ya, I agree with you, keep it dead simple. Internal docs also deserve a great DX. You can use Docusaurus for internal docs, and use our stock template to get started in a few minutes: just write markdown files. We have been reported heavy usage of Docusaurus at Microsoft and LinkedIn for internal documentations for example. This is what our stock template look out of the box: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/ You don't have to do anything to have this DX: just write md files. Maybe you can already feed Docuaurus with your existing md files, and it will just work without any change.