[HN Gopher] Docusaurus - Build optimized websites quickly, focus...
___________________________________________________________________
Docusaurus - Build optimized websites quickly, focus on your
content
Author : yamrzou
Score : 154 points
Date : 2024-08-29 06:27 UTC (16 hours ago)
(HTM) web link (docusaurus.io)
(TXT) w3m dump (docusaurus.io)
| newusertoday wrote:
| for some reason most of the docs site themes have anemic support
| for blogs and if you are developing something you almost always
| want landing+blog+docs, yet its either fixated on docs or blogs
| but rarely both. I wonder why?
| preommr wrote:
| Because it's trivial to mix-and-match specialized products in a
| single project. It's trivial to install docusaurus, and a ssg
| like eleventy in the same project, and configure it so that
| they have some shared components by setting configuration
| details to point to the right directory, all within one repo,
| same package manager, etc.
| sixhobbits wrote:
| I've tried most of these and this is definitely one of the best,
| especially since the latest version. It's not too heavy but
| includes all the features you don't know you need at the start,
| and a good ecosystem of plugins and extensions.
|
| Other notable mentions are
|
| - mkdocs-material, if you prefer python to js
|
| - astro starlight, not quite as mature and a bit heavier but
| looks nicer out the box and includes built-in search
| reacharavindh wrote:
| Mkdocs-material has been my go to for this use case. However, I
| once made a document website using MDbook(the thing that Rust
| uses for their own documentation and book), and have a lot of
| happy consumers.
| Onavo wrote:
| Are there any good open source documentation chatbots that you
| can integrate into the search function of docusaurus? If you
| see commercial offerings like mintlify, they all come with a Q
| and A chatbot built-in. It's not very hard to build, you just
| need to generate the RAG chunks at build-time but this is best
| implemented as part of the documentation software, rather than
| as a third party plugin since it heavily ties into the search
| feature.
| bnlxbnlx wrote:
| +1! I'd love to know, too!
| FireInsight wrote:
| mkdocs-material is fine if you prefer Python to JS, but I
| personally very much dislike how it looks, and as everything
| else it uses a weird custom Markdown flavor where indentation
| is handled weirdly which can create edge-cases where for
| example a valid GFM list is not rendered properly by MkDocs.
|
| +1 on Starlight, though, it is my go-to and I absolutely love
| it.
| lloydatkinson wrote:
| What makes starlight heavier? If anything its the opposite,
| it's not client side rendering pages like Docusaurus...
| https://starlight.astro.build/environmental-impact/
| thibaultamartin wrote:
| Likewise, I've been happy with Starlight and trust Astro
| products to be lightweight and efficient. I'm interested in
| knowing what makes it heavier
| FireInsight wrote:
| The comparisons-page clearly highlights that Docusaurus is
| way heavier. https://starlight.astro.build/environmental-
| impact/#comparis...
| Jakob wrote:
| I wish all API doc generators test the doc code examples like
| this https://rust-lang.github.io/mdBook/cli/test.html
|
| Even if the code example works today, it might not in the future
| and tests prevent people getting stuck on outdated docs like we
| often see.
| jillesvangurp wrote:
| I actually wrote a kotlin library
| (https://github.com/jillesvangurp/kotlin4example) a while ago
| to help me write documentation that is generated from code that
| actually compiles and runs.
|
| Instead of embedding code in markdown, I actually generate the
| markdown from code. Which with Kotlin is easy because you can
| write your own DSLs. And I get to refactor my code and
| documentation at the same time. It has some other nifty
| features like capturing output that you can show in the
| Markdown and a few other things.
|
| If you want to see it in action, check out the documentation
| for my kt-search project. There are probably a lot of other
| libraries out there that do similar things. But it's a thing
| that most projects don't seem to rely on for their
| documentation. And breaking code samples are a major hurdle for
| writing documentation to begin with.
|
| I find that addressing that gets you in a mode where you are
| documenting things by default. And good documentation also
| reveals design flaws because you are kind of forced to eat your
| own dog food by writing working code that shows how you would
| use a particular feature. I'm basically constantly trying to
| make life easier for both myself and my users.
| mkesper wrote:
| Reminds me of Knuth's literate programming: https://www-cs-
| faculty.stanford.edu/~knuth/lp.html
| jillesvangurp wrote:
| That was a direct inspiration.
| boxed wrote:
| I wrote a ton of custom code to do this for iommi (example:
| https://docs.iommi.rocks/en/latest/tutorial.html). I went
| further than any other library I've seen and made it so that
| the views in the examples produce static html files that are
| embedded in the resulting output via iframes.
| TDM_x wrote:
| Sounds really interesting to build it with Markdown that's cool,
| especially to make web pages thanks to AI ^^. Thanks for sharing
| this.
| AUnterrainer wrote:
| I have been using docusaurus for my tech blog (www.defconq.tech)
| and it's easy enough to use for a non front end dev.
| lukcybrain wrote:
| Glad to hear it's work without a front-end development
| background.
| anon1094 wrote:
| Yeah, it's great for non-front-end folks! The default themes
| look pretty good, and you can use a bunch of pre-made
| components right in your markdown.
| lioeters wrote:
| One of my favorite features of Docusaurus is integration with
| TypeDoc to generate API docs for TypeScript definitions. It makes
| for a useful overview of all available classes, functions, etc.
| It's not sufficient by itself as documentation, but it covers an
| important aspect as reference.
| johnny_reilly wrote:
| Long time user of (and contributor to) Docusaurus. I use it to
| build my markdown powered tech blog. https://johnnyreilly.com/ It
| is very much a Goldilocks product for me ("just right") in that
| it has React support, Markdown support, TypeScript support and a
| good amount of customisation is possible (good underlying APIs).
| It also has a great community. Props to Sebastien Lorber for
| leading the project so well!
| anon1094 wrote:
| Hey John, thanks for your contributions! Also gotta give a big
| shoutout to Sebastien and the crew for creating and constantly
| updating Docusaurus - it's one of my favorite docs software.
| Growtika wrote:
| The first time I heard about Docusaurus was when someone
| mentioned on Hacker News that they had ruined their SEO:
|
| https://news.ycombinator.com/item?id=34389421
|
| I helped him in recovering from a Google SEO penalty, and he
| documented his journey on his blog:
|
| https://johnnyreilly.com/how-we-fixed-my-seo
|
| This might be helpful for those using Docusaurus, as some default
| settings, like pagination and tag pages, can generate thousands
| of non-helpful pages. These issues can be easily fixed with
| noindex tags and a sitemap/structure cleanup.
|
| Overall, I think Docusaurus is great. It's clean, flexible, and
| the community is very responsive, so it's constantly improving at
| a fast pace
| actionfromafar wrote:
| Oh, Reilly? He should write a book. :)
| d4rkp4ttern wrote:
| I like it too but it doesn't have auto-docs based on
| docstrings, which Material for MkDocs has:
|
| https://github.com/mkdocstrings/mkdocstrings
| cpursley wrote:
| This post in particular helped me fix seo as well for
| https://appraisalinbox.com (the design still needs a lot of
| love).
|
| These days I'd probably start off using astro for a static
| site. They've got a docs starter, too.
| matsemann wrote:
| Aww man I hate clicking on a result on google, taking me to a
| pagination page where the content I'm looking for is no longer
| on that page.
| anon1094 wrote:
| Docusaurus shines in docs-as-code scenarios. I used it for
| Amplication, Februar, and other technical docs projects.
|
| The SEO features, integrated Algolia search, and built-in
| components save a lot of time and help you focus on writing
| markdown.
|
| The plugin system and React-based customization is powerful, but
| for most projects you should be fine with the provided components
| and editing the custom css file.
|
| For a look at how a dev tool company uses Docusaurus to implement
| its docs, check out this article on Amplication's approach:
|
| https://medium.com/abundant-dev/amplication-documentation-ca...
|
| This might help those wanting to use Docusaurus with a docs-as-
| code workflow, especially when using GitHub or other git
| platforms for reviews.
| albertvila wrote:
| I use Docusaurus for my software development wiki (knowledge
| base): https://albert.wiki
|
| It works very well for this purpose. I didn't bother to change
| the default UI though. And I haven't added any search mechanism
| (I keep the content organized, thus I don't need it much). It has
| a blog feature, but I don't use it.
|
| It's hosted in Netlify, deploying automatically on each push.
|
| Here's the source code if you are curious:
| https://github.com/AlbertVilaCalvo/Wiki
| DilutedMetrics wrote:
| I love Docusaurus. I use it for personal web projects as a static
| site. There's a surprising number of sites I see nowadays that
| you can tell are also built on Docusaurus.
| I_am_tiberius wrote:
| Maybe not fitting to mention that here, but Typora still doesn't
| support .mdx files out of the box. This makes maintaining
| docusaurus sites a hassle.
| archibaldJ wrote:
| So how does astro's Starlight compare to it as of Sep 2024? I've
| invested a bit time to configure Starlight for a new proj but now
| I'm a bit tempted to switch over
|
| Would love feedbacks from anyone who have been with both
| Starlight and Docusaurus; thanks!
|
| e.g. are there anything great about Starlight that I should stick
| to it? SEO-wise, etc.
| microflash wrote:
| Why are you tempted? Personally, I like Starlight's use of web
| components. It is much more lightweight and since it is based
| on Astro, you can use whatever framework you want / need.
| drdrek wrote:
| Why are there so many site publishing solutions? Is it that good
| of a business? Is it advantageous to smaller players?
| sir-dingleberry wrote:
| They're relatively easy to make.
| _chimmy_chonga_ wrote:
| we use Docusarus at work for our internal documentation sites and
| its okay. It gets the job done and it beats manually making a
| nice website for docs by hand
| ruuda wrote:
| If you don't like to run javascript outside of a browser, MkDocs
| is a great Python-based alternative: https://www.mkdocs.org/
| synergy20 wrote:
| I wish all those static site generators, and docusaurus alike doc
| sites, can add a login feature if they do not have one still.
|
| what I want is a simple CMS basically, not as complex as drupal
| etc, but at least support login to view when I need it.
| oliwarner wrote:
| There are a lot of these documentation-geared SSGs. I've tried a
| few and Starlight is what rang _least annoying_ of the bunch. No
| library lock-in, a sane theme, client-side search, a much smaller
| dependency tree than many, and quite fast to build.
|
| https://starlight.astro.build/
| sir-dingleberry wrote:
| When I see React in 2024 I get uncomfortable.
| ValentineC wrote:
| I chose Docusaurus for the Singapore hackerspace's docs site
| (https://docs.hackerspace.sg).
|
| My personal opinion when we chose Docusaurus was that it struck
| the right balance in having just enough batteries included.
|
| It was quick and easy to launch something without having to
| fiddle with too much config, while allowing some scripting,
| customisability, and templating through MDX.
|
| It's probably also a good thing that Facebook dogfoods Docusaurus
| in some places, while keeping it MIT licensed so the community
| can fork it if Facebook ever decides to stop maintaining it.
| jstasiak wrote:
| I've had some contact with Docusaurus and from my experience the
| Sphinx and reStructuredText combo is a much better solution to
| creating a robust, maintainable, cross-linked-to-nth-degree
| documentation where you actually can "focus on your content".
|
| Bonus points if you prefer to not deal with the JS ecosystem and
| prefer Python.
|
| The main downside is that while reST is well-suited for extending
| the syntax actually writing Sphinx extensions is, subjectively,
| significantly more arcane than writing React components/MDX
| plugins.
|
| A recent discussion on this topic, part of the "I prefer rST to
| Markdown" submission:
| https://news.ycombinator.com/item?id=41120772
___________________________________________________________________
(page generated 2024-08-29 23:01 UTC)